How to Use Stylix: The Beginner's Guide (First Theme, the Wallpaper Lesson, Schemes, and the Fonts Arc)

CodexFuse Team · 2026-11-06T17:19:16.401Z · 23 min read min read

What Is Stylix?

Stylix is a theming framework for NixOS, Home Manager, nix-darwin, and Nix-on-Droid, and learning how to use Stylix means learning to declare one theme and watch it spread across your whole system. One declaration carries three things, a wallpaper, a base16 colour scheme, and a set of fonts, and Stylix applies them to every supported application it knows about. As of November 2026, this Stylix tutorial pins every command to the current stable branch, release-26.05, with master as the rolling unstable alternative.

The mental model is simple: instead of theming each program by hand, you describe the look once and Stylix generates the configuration for each app. Your terminal, editor, browser, status bar, and even the bootloader all draw from the same sixteen colours and the same fonts. That is the whole promise of NixOS system theming, one source of truth for how the machine looks, rebuilt with the system instead of pasted across dotfiles.

Stylix is not a colour-scheme utility alone. The project describes itself as a theming framework that applies colour schemes, wallpapers, and fonts to a wide range of applications, unlike base16.nix or nix-colors, which hand you a palette and leave the per-app work to you. The repository holds about 100 modules, one per supported application or system component, and each module translates your theme into that application's own configuration format.

Devenv provisions whole development environments while Stylix themes the whole system interface, and the two are complementary, never rivals. The Devenv beginner guide covers the environment side of the same Nix story, while this guide covers the look of the system itself. CodexFuse offers no Stylix tool, so this guide teaches the tool itself, from install to first theme.

Stylix is free and open source under the MIT License, with no paid tier to quote. The repository had 2,464 stars and 374 forks when this guide was written, which works out to 6.59 stars per fork and a 15.2 percent fork ratio, and it was created 2020-12-21, making it 2,146 days old as of this writing. It is actively maintained: the newest commit on master landed 2026-10-25, 12 days before this writing, and the project gained 47 stars in the 36 days from September 30 to November 5, 2026, about 1.31 stars per day.

How to Use Stylix in 7 Steps

Follow these seven steps to go from an unthemed NixOS system to one coherent theme. Each step is covered in full in its own section below.

1. Add the Stylix flake input, matching the branch to your NixOS release: release-26.05 for stable, master for unstable.
2. Import the right module: stylix.nixosModules.stylix for NixOS, or stylix.homeModules.stylix for standalone Home Manager.
3. Set stylix.enable to true and rebuild, so Stylix starts managing your theme.
4. Set stylix.image to a wallpaper and let Stylix generate a palette from it, or set stylix.base16Scheme to a named scheme.
5. Pick your fonts in the four stylix.fonts slots: serif, sansSerif, monospace, and emoji.
6. Check which targets picked up the theme, and enable or disable individual targets as needed.
7. Rebuild, log out and back in where a target needs it, and view the generated palette at /etc/stylix/palette.html.

How Does One Declaration Theme Every App?

One declaration themes every app because Stylix sits between your theme and each application's own configuration format. You declare a wallpaper, sixteen base16 colours, and four fonts, and each of the roughly 100 modules renders those values into the files its application reads. Change the wallpaper or the scheme once, rebuild, and every themed application changes together.

The sixteen colours are the base16 scheme, named base00 through base0F, and each has a defined role. Base00 is the default background, base01 is a lighter background, base02 is the selection background, base05 is the default foreground text, base08 is the error colour, base09 is the urgent colour, and base0A is the warning colour. Stylix's own style guide assigns these roles consistently across window managers, notifications, and desktop helpers, so the same red means error everywhere.

The wallpaper is more than decoration. If you set stylix.image and leave stylix.base16Scheme undeclared, Stylix generates a colour scheme from the wallpaper using a genetic algorithm, and the documentation notes that more colourful images tend to yield better results. The generator is written in Haskell, and its source keeps 500 survivors per generation, creates 49,500 newborns per generation, and mutates with probability 0.75, all from a deterministic seed when running inside Nix.

Fonts travel the same way. Stylix applies your chosen fonts through each application's own font options, widely through the Fontconfig module, and by making the font packages available to the system. One font declaration therefore reaches the terminal, the editor, the browser, and the desktop shell at the same time.

How Do You Install Stylix?

Install Stylix as a flake input, because flakes are the documented route for Stylix NixOS theming and the one this guide teaches. Add the input to your flake, import the module for your platform, and keep all inputs in sync with nix flake update, since the master branch follows a rolling-release model. The documentation warns against partial updates: update inputs together, never one at a time.

For NixOS on the unstable channel, the input looks like this, with nixpkgs following your own nixpkgs input so the two never drift apart.

{
  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
    stylix.url = "github:nix-community/stylix";
    stylix.inputs.nixpkgs.follows = "nixpkgs";
  };
  outputs = { self, nixpkgs, stylix, ... }: {
    nixosConfigurations.myhost = nixpkgs.lib.nixosSystem {
      system = "x86_64-linux";
      modules = [ stylix.nixosModules.stylix ./configuration.nix ];
    };
  };
}

The branch rule is the one thing to get right, and it is a branch, not a version number. Stylix publishes no releases and no tags at all: its GitHub releases page is empty, and versioning happens through release branches. If you run a stable NixOS release, use the matching Stylix release branch, because a mismatched branch is the classic first failure.

NixOS 26.05 Yarara was released 2026-05-30, which makes it 160 days old as of this writing, and it is supported through 2026-12-31, leaving 55 days of support. The stable flake input for it pairs the 26.05 nixpkgs channel with the 26.05 Stylix branch.

{
  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-26.05";
    stylix.url = "github:nix-community/stylix/release-26.05";
    stylix.inputs.nixpkgs.follows = "nixpkgs";
  };
}

Home Manager users have the same choice in their own flake, with the home-manager input matched to the same release. The standalone Home Manager module import is stylix.homeModules.stylix, and the current name matters: older guides use a retired module name that no longer exists. The same staleness affects the old repository address, which several older guides still show, but the project moved to the nix-community organisation, so copy the current input from the documentation, never an old guide.

{
  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-26.05";
    home-manager.url = "github:nix-community/home-manager/release-26.05";
    stylix.url = "github:nix-community/stylix/release-26.05";
    stylix.inputs.nixpkgs.follows = "nixpkgs";
  };
  outputs = { self, nixpkgs, home-manager, stylix, ... }: {
    homeConfigurations.myuser = home-manager.lib.homeManagerConfiguration {
      pkgs = nixpkgs.legacyPackages.x86_64-linux;
      modules = [ stylix.homeModules.stylix ./home.nix ];
    };
  };
}

There is also a non-flake route, for configurations that do not use flakes. Fetch the repository with fetchFromGitHub, pin a revision and hash, and import the module from the fetched source. Flakes remain the recommended path, and the rest of this guide assumes them.

Keep your flake in version control from the start, because the theme lives in the same files as the rest of the system. The Git beginner guide covers the basics if you have not set that up yet. A tool version manager can also pin the helper tools around your flake, and the Mise beginner guide covers that lane; Mise pins tool versions, Stylix themes the interface, and the two do not overlap.

How Do You Make Your First Theme From a Wallpaper?

Your first theme starts with two lines: enable Stylix, then point it at a wallpaper. Stylix must be enabled before it applies any change, so stylix.enable is true, and stylix.image takes a path to an image file or a derivation that fetches one. Rebuild, and the wallpaper-driven palette spreads across every target that is installed.

{
  stylix.enable = true;
  stylix.image = ./wallpaper.png;
  stylix.polarity = "dark";
}

The palette comes from the genetic algorithm described above, and polarity skews it toward a dark or light theme. Set stylix.polarity to dark or light to taste, and remember that a flat grey wallpaper makes a flat grey theme. If you set both a wallpaper and an explicit base16 scheme, the explicit scheme wins, and the wallpaper is used only as the wallpaper.

You can see exactly what the generator produced. On NixOS the generated palette is viewable at /etc/stylix/palette.html, and on Home Manager at ~/.config/stylix/palette.html. Open that page after your first rebuild and check the sixteen colours before deciding whether to keep the generated scheme or pick a named one instead.

Want to try before installing anything? The project ships a testbed demo that runs a themed desktop with no installation: nix run github:nix-community/stylix#testbed:gnome:dark starts a GNOME 46 dark theme, and a KDE Plasma 5 example is shown alongside it. The demo is the fastest way to see what a Stylix theme feels like, but KDE theming is still a work in progress, and the documentation notes that some manual steps may be required to apply its theme properly.

How Do You Pick a Base16 Scheme Instead?

Pick a named scheme when you want a palette you already know, instead of one generated from a wallpaper. Set stylix.base16Scheme to a scheme file, and the usual path is the base16-schemes package from nixpkgs, which holds the scheme files under share/themes. Gruvbox dark hard is the example the documentation itself uses.

{
  stylix.base16Scheme = "${pkgs.base16-schemes}/share/themes/gruvbox-dark-hard.yaml";
  stylix.override = {
    base00 = "282c34";
  };
}

A Stylix base16 scheme is sixteen named colours with fixed semantic roles, and Tinted Theming is the project that continues the base16 format today. The schemes now live in the tinted-theming/schemes repository, on its spec-0.11 branch, which was created 2023-12-15 and is 1,057 days old as of this writing.

Do not go looking for the old base16-schemes repository: it is archived and deprecated, created 2022-05-25 and 1,626 days old, and its own readme says builders should move to the new schemes repository. The pkgs.base16-schemes package path in the Stylix documentation is still the correct thing to quote.

The stylix.base16Scheme option also accepts other files and formats supported by mkSchemeAttrs, so you can pass a scheme as a Nix attrset or a derivation path, not only a YAML file. If the named scheme is almost right, override part of it instead of forking the whole file. The stylix.override option accepts anything base16.nix accepts as an override, so a single colour change is one line, as the example above shows.

Overrides follow an inheritance rule worth knowing once. When both the NixOS and Home Manager modules are used, the system override and the user override combine, unless the user changes stylix.base16Scheme itself, in which case only the user override is used. Keep overrides small and named, so the next person reading your configuration can see what you changed and why.

How Do Stylix Fonts Work?

Stylix fonts work through four slots, not three, and the fourth is the one older guides miss. The slots are serif, sansSerif, monospace, and emoji, and each takes a font package plus a font name. The defaults are all DejaVu except emoji, which defaults to Noto Color Emoji, so a fresh Stylix system already has coherent fonts before you change anything.

Set a slot by naming a package and a font, and Stylix carries that choice into every application that takes a font from it. The documentation shows replacing the serif font with the sans-serif one, and setting monospace for everything, both as one-line assignments. A typical custom set looks like this, with the monospace font doing the heavy lifting in terminals and editors.

{
  stylix.fonts = {
    serif = {
      package = pkgs.dejavu_fonts;
      name = "DejaVu Serif";
    };
    sansSerif = {
      package = pkgs.dejavu_fonts;
      name = "DejaVu Sans";
    };
    monospace = {
      package = pkgs.jetbrains-mono;
      name = "JetBrains Mono";
    };
    emoji = {
      package = pkgs.noto-fonts-color-emoji;
      name = "Noto Color Emoji";
    };
  };
}

Fonts reach applications in three ways: through an application's own font options, widely through the Fontconfig module, and by making the font packages available to the system. That is why one font declaration covers the terminal, the editor, the browser, and the desktop shell at once. If a font looks wrong in one application only, check that application's own font option first, because Stylix sets it through the application's module, not by patching the application.

What Are Stylix Targets and How Do You Control Them?

A Stylix target is anything that can have colours, fonts, or a wallpaper applied to it. Each target has an option of the form stylix.targets.target-name.enable, and by default a target turns itself on automatically whenever the corresponding application is installed. That auto-enable behaviour is what makes Stylix feel automatic: install Alacritty through Home Manager, and the Alacritty target themes it without further configuration.

Auto-enable has a condition that surprises beginners. Most targets require their application's module to be enabled on the host platform first: the Alacritty target, for example, requires enabling Home Manager's programs.alacritty.enable option, because Stylix needs the Home Manager module to know the application exists. A community help thread from 2025-07-24, 470 days old, records exactly this confusion, and the fix is to enable the application through Home Manager and let Stylix see it.

Targets differ between Home Manager and NixOS, and sometimes a target is available in both places. The documentation says that when both are available, it is always correct to enable both. System-level targets such as GRUB and Plymouth live on the NixOS side, while user applications such as terminals and browsers live on the Home Manager side.

Turn a target off with one line when you prefer your own configuration for that application. Setting stylix.targets.firefox.enable to false leaves Firefox exactly as you configured it, while everything else follows the theme. Set stylix.autoEnable to false to opt out of automatic enabling entirely, and then enable each target you want by hand.

{
  stylix.targets = {
    firefox.enable = false;
    waybar.enable = true;
  };
  stylix.autoEnable = false;
}

Two of the targets above deserve a closer look, because they are the applications most readers theme first. The Alacritty beginner guide covers the terminal itself, and the Neovim beginner guide covers the editor; Stylix themes the interface around the editor, while the nixvim module configures the editor itself, and that line is drawn once here so the two lanes never blur.

For applications with no Stylix module, you can still use the theme's colours. The config.lib.stylix.colors attrset exposes the configured scheme as values you can consume in your own modules: base08 as a plain hex string, base08-hex-r as the red channel in hex, base08-dec-r as the red channel in decimal, named colours such as red, and a withHashtag sub-attrset with the leading hash included. The attrset is generated by mkSchemeAttrs from base16.nix, which is the library Stylix builds on.

{
  config,
  lib,
  ...
}: {
  programs.myapp.settings = {
    background = config.lib.stylix.colors.withHashtag.base00;
    accent = config.lib.stylix.colors.withHashtag.base0D;
  };
}

How Do You Make a Theme Dark or Light?

Make a theme dark or light with stylix.polarity, which skews the generated palette toward dark or light. Set it to dark for a dark theme or light for a light theme, and it applies when the palette is generated from a wallpaper. Polarity is a skew, not a switch: it biases the genetic algorithm's output rather than replacing the palette.

Polarity matters most for wallpaper-generated themes, because a named base16 scheme already declares its own lightness. If you picked gruvbox-dark-hard, the scheme is dark by definition, and polarity has nothing to generate. If your Stylix wallpaper theme came from a bright photograph, polarity dark pulls the background colours down toward a usable dark theme instead of a washed-out one.

Check the result in the generated palette page after each change. The palette at /etc/stylix/palette.html on NixOS, or ~/.config/stylix/palette.html on Home Manager, shows the sixteen colours with their roles, so you can see whether the background is dark enough and the text still has contrast. Adjust polarity, rebuild, and re-check until the palette reads well.

NixOS Module or Home Manager Module: Which Shape Fits You?

Choose the NixOS module when Stylix should theme the whole machine, and the Stylix Home Manager module when it should theme one user's applications. The two shapes share the same options, but they theme different layers, and most readers want the NixOS shape with Home Manager inside it. The documentation recommends Home Manager as a NixOS module, and calls it highly recommended, because most Stylix features are unavailable without Home Manager.

When Home Manager runs as a NixOS module, Stylix installs its Home Manager modules automatically if it detects Home Manager, and the NixOS theme becomes every user's default settings. A user can still override the theme in their own Home Manager configuration, and the documentation notes a special case: if the wallpaper in a Home Manager configuration is changed, Home Manager stops inheriting the colour scheme from NixOS. Disable inheritance entirely with stylix.homeManagerIntegration.autoImport and stylix.homeManagerIntegration.followSystem if you want the two layers fully separate.

The other two platforms follow the same pattern with their own module names. On macOS, stylix.darwinModules.stylix sets up the Home Manager modules, though it does not change the look of macOS itself.

On Android, stylix.nixOnDroidModules.stylix applies the colour scheme and monospace font to the Nix-on-Droid terminal. This guide focuses on NixOS, where the full range of targets is available.

What Should You Do When a Target Does Not Theme?

Start with the three checks that solve most cases: the application must be enabled through its own Home Manager module, the target must not be disabled, and the system must have been rebuilt after the change. Auto-enable only fires for applications Stylix can see through Home Manager, so an application installed imperatively, outside the Home Manager configuration, stays unthemed until you enable it declaratively. Force a target on explicitly with stylix.targets.target-name.enable set to true when auto-enable misses it.

Some applications cannot be themed, and knowing which saves hours. GNOME Console, also known as kgx, is not themeable by Stylix, because it uses libadwaita rather than GTK, and the GTK target does not cover it.

A Discourse thread from about 445 days ago records users hitting exactly this wall, and the working answer was to accept the limitation or disable the conflicting QT target. KDE theming remains unfinished too, so expect rough edges there rather than a finished experience.

Stale guides are the third common cause, and they fail silently. If a guide tells you to use github:danth/stylix as the flake input, or stylix.homeManagerModules.stylix as the module name, or a version number where a branch belongs, it predates the move to nix-community and the current branch model.

The DeepWiki installation-and-setup summary is 560 days old, about 2025-04-25, and carries all three errors, and a 2024 walkthrough on tty.is carries the old input and the old documentation address. Check the input URL, the module name, and the branch against the current documentation before debugging anything else.

Stylix vs Base16.nix vs Nix-Colors: What Is the Difference?

The difference is how much work each tool does for you. Nix-colors hands you a palette, base16.nix hands you a palette plus templates, and Stylix hands you a finished theme across roughly 100 applications. All three build on the same sixteen-colour base16 idea, but they stop at different points, and the right choice depends on whether you want to write per-app configuration yourself.

Stylix sits on top of base16.nix rather than replacing it. The config.lib.stylix.colors attrset is generated by mkSchemeAttrs from base16.nix, so the palette machinery underneath Stylix is the same library you would use directly.

Base16.nix's own readme says it plainly: base16.nix is a simple theming interface, not an all-batteries-included ricing engine, but if you want one, check out Stylix. That sentence is the whole relationship in one line.

Per-app manual theming is the alternative all three replace, and it is worth naming honestly. Hand-writing colours into each program's own configuration gives total control and works for any application, including ones no tool supports.

The cost is repetition: every colour change is repeated once per application, and the copies drift apart over time. Stylix trades that control for one declaration and ready modules, and anything without a module stays manual, either through a custom module built on config.lib.stylix.colors or by hand-theming that one application.

repo created 2020-12-21:        2146 days old
last push on master 2026-10-25:   12 days ago
release-26.05 updated 2026-10-09: 28 days ago
NixOS 26.05 released 2026-05-30:  160 days ago; support ends 2026-12-31 (55 days left)
NixOS 25.11 EOL 2026-06-30:       129 days ago
stars per fork: 2464/374 = 6.59; fork ratio 15.2%
open issues per 100 stars: 216/2464 = 8.77
genetic algorithm: 500 survivors, 49500 newborns per generation, 0.75 mutation probability
stars growth: +47 in 36 days (2026-09-30 to 2026-11-05), about 1.31 per day

Sources

This guide was written from sources fetched this run. The Stylix documentation supplied the installation, configuration, and style-guide facts: the flake input URL, the module imports, the release-branch matching rule, the enable and image options, the genetic-algorithm palette generation, the four font slots, the target system, and the config.lib.stylix.colors attrset.

The GitHub repository supplied the project facts: 2,464 stars, 374 forks, creation on 2020-12-21, the MIT license, the empty releases page, the release branches, and the module count of about 100 entries. The palette-generator source on the master branch confirmed the genetic algorithm's numbers: 500 survivors, 49,500 newborns per generation, and a 0.75 mutation probability.

The versioning facts came from the repository's branches page and the NixOS release record: release-26.05 updated 2026-10-09, NixOS 26.05 Yarara released 2026-05-30 with support through 2026-12-31, and NixOS 25.11 end of life on 2026-06-30. The scheme facts came from the Tinted Theming repositories: tinted-theming/schemes as the current home on its spec-0.11 branch, and tinted-theming/base16-schemes as archived and deprecated. The comparison facts came from the base16.nix repository, created 2021-05-06 with its last push 2025-05-06, and from nix-colors as linked in the Stylix documentation.

The field itself was checked this run: the DeepWiki installation-and-setup summary at 560 days old, the DeepWiki theming page at 363 days old, the 2024 tty.is walkthrough section, the Hysenlabs project analysis updated September 29, 2026, the NixOS Discourse help thread from 2025-07-24, and the NixOS Wiki, which has no Stylix page at all. All ages and ratios in this guide were recomputed in Python this run, and the star and fork counts were re-checked against the GitHub API this run.

Frequently Asked Questions

Does Stylix work without flakes?

Yes, through the non-flake route: fetch the repository with fetchFromGitHub, pin a revision and hash, and import the module from the fetched source. Flakes remain the recommended path, and the rest of this guide assumes them, because the branch matching and input syncing are simpler with flakes.

Which Stylix branch should I use with NixOS 26.05?

Use release-26.05, the branch that matches NixOS 26.05, and use master only with nixos-unstable. There are no release tags to pin, and NixOS 25.11 is end of life, so its branch is legacy only and should not be used for a new setup.

Can Stylix theme an app it has no module for?

Yes, with your own work: read the theme's colours from config.lib.stylix.colors in a custom module, or generate the application's configuration from a mustache template, as the base16.nix documentation shows. If that is more effort than the application is worth, keep hand-theming that one application and let Stylix handle the rest.

Why is my terminal not picking up the theme?

Check three things in order: the terminal must be enabled through its own Home Manager module, the target must not be disabled, and the system must have been rebuilt after the change. Auto-enable only sees applications configured through Home Manager, so enable the application declaratively or force the target on with stylix.targets.target-name.enable set to true.

Is Stylix free?

Yes, Stylix is free and open source under the MIT License, with no paid tier and no pricing to quote. The only costs around it are your own: the time to write the configuration, and whatever backend or hosting you run alongside it, which this guide does not price.