Stylix

Stylix is a NixOS module which applies the same colour scheme, font and wallpaper to a range of applications and desktop environments.

What's this?

base16.nix allows you to import colours from base16 into Nix code. Stylix takes this a step further:

Automatically colours and changes the font of apps
Sets your wallpaper
Exports the colour scheme to be used manually for anything we missed
Can also generate themes based on an image

For those not familiar with NixOS and Home Manager:

NixOS is a Linux distribution
Home Manager is a program which runs anywhere
Both use the Nix language and package manager
Both let you install programs and change settings via code

Stylix supports either NixOS + Home Manager, or Home Manager on its own. Certain features are only available with NixOS.

Resources

Please refer to the Stylix book for instructions and a list of supported apps.

For a visual guide, watch the Ricing Linux Has Never Been Easier | NixOS + Stylix YouTube video by Vimjoyer.

Note

It's now necessary to include stylix.enable = true in your configuration for any other settings to take effect. This is not mentioned in the video linked above.

If you have any questions, you are welcome to join our Matrix room, or ask on GitHub Discussions.

Example configurations

GNOME 46

Photos by Clay Banks and Derrick Cooper.

Try a live demo of this theme by running nix run github:danth/stylix#testbed-gnome-light or nix run github:danth/stylix#testbed-gnome-dark.

KDE Plasma 5

Photos by Aniket Deole and Tom Gainor.

KDE theming is still a work in progress - so some manual steps may be needed to apply the settings completely.

Installation

NixOS

You can install Stylix into your NixOS configuration using Flakes. This will provide theming for system level programs such as bootloaders, splash screens, and display managers.

{
  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
    stylix.url = "github:danth/stylix";
  };

  outputs = { nixpkgs, stylix, ... }: {
    nixosConfigurations."«hostname»" = nixpkgs.lib.nixosSystem {
      system = "x86_64-linux";
      modules = [ stylix.nixosModules.stylix ./configuration.nix ];
    };
  };
}

Minimal flake.nix for a NixOS configuration.

Many applications cannot be configured system wide, so Stylix will also need Home Manager to be able to change their settings within your home directory.

Installing Home Manager as a NixOS module is highly recommended if you don't use it already. This will combine it with your existing configuration, so you don't need to run any extra commands when you rebuild, and the theme you set in NixOS will automatically be used for Home Manager too.

When Stylix is installed to a NixOS configuration, it will automatically set up its Home Manager modules if it detects that Home Manager is available. You can theoretically use it without installing Home Manager, however most features will be unavailable.

nix-darwin

You can install Stylix into your nix-darwin configuration in a similar fashion to NixOS via Flakes.

{
  inputs = {
    darwin = {
      url = "github:LnL7/nix-darwin";
      inputs.nixpkgs.follows = "nixpkgs";
    };
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
    stylix.url = "github:danth/stylix";
  };

  outputs = { darwin, nixpkgs, stylix, ... }: {
    darwinConfigurations."«hostname»" = darwin.lib.darwinSystem {
      system = "aarch64-darwin";
      modules = [ stylix.darwinModules.stylix ./configuration.nix ];
    };
  };
}

Minimal flake.nix for a nix-darwin configuration.

While this won't have an effect on the looks of MacOS, since we don't have the controls to theme it like we do NixOS, it will automatically set up the Home Manager modules for you.

Home Manager

If you would prefer to use the standalone version of Home Manager, you can install Stylix directly into your Home Manager configuration instead. This could be useful if you are on another operating system, or a machine which is managed by someone else.

{
  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
    home-manager.url = "github:nix-community/home-manager";
    stylix.url = "github:danth/stylix";
  };

  outputs = { nixpkgs, home-manager, stylix, ... }: {
    homeConfigurations."«username»" = home-manager.lib.homeManagerConfiguration {
      pkgs = nixpkgs.legacyPackages.x86_64-linux;
      modules = [ stylix.homeManagerModules.stylix ./home.nix ];
    };
  };
}

Minimal flake.nix for a Home Manager configuration.

If you choose to use both NixOS and Home Manager but configure them separately, you will need to copy the settings described below into both of your configurations, as keeping them separate means that they cannot follow each other automatically.

Without flakes

If you haven't enabled flakes yet or don't want to use this feature, default.nix re-exports all the flake outputs, without requiring flakes to be enabled. This means that once you have a copy of this repo, using either a local checkout, niv, or any other method, you can import it to get the NixOS module as the nixosModules.stylix attribute and the Home Manager module as the homeManagerModules.stylix attribute.

let
  stylix = pkgs.fetchFromGitHub {
      owner = "danth";
      repo = "stylix";
      rev = "...";
      sha256 = "...";
  };
in {
    imports = [ (import stylix).homeManagerModules.stylix ];

    stylix = {
      enable = true;
      image = ./wallpaper.jpg;
    };
}

Example usage of the Home Manager module without flakes.

Configuration

Enable

To enable the Stylix module, declare:

{
  stylix.enable = true;
}

Note

The global enable option was recently added, so you may come across old examples which don't include it. No other settings will take effect unless stylix.enable is set to true.

Wallpaper

To start theming, you need to set a wallpaper image.

{
  stylix.image = ./wallpaper.png;
}

The option accepts derivations as well as paths, so you can fetch an image directly from the internet:

{
  stylix.image = pkgs.fetchurl {
    url = "https://www.pixelstalk.net/wp-content/uploads/2016/05/Epic-Anime-Awesome-Wallpapers.jpg";
    sha256 = "enQo3wqhgf0FEPHj2coOCvo7DuZv+x5rL/WIo4qPI50=";
  };
}

Color scheme

Generated schemes

If you only set a wallpaper, Stylix will use a genetic algorithm to create a color scheme. The quality of these schemes can vary, but more colorful images tend to have better results.

You can force a light or dark scheme using the polarity option:

{
  stylix.polarity = "dark";
}

The current scheme can be previewed in a web browser at either /etc/stylix/palette.html for NixOS, or ~/.config/stylix/palette.html for Home Manager.

Handmade schemes

If you prefer a handmade color scheme, you can choose anything from the Tinted Theming repository:

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

This option also accepts other files and formats supported by mkSchemeAttrs.

Overriding

For convenience, it is possible to override parts of stylix.base16Scheme using stylix.override. Anything that base16.nix accepts as override is valid.

When using both the Home Manager and NixOS modules, both the system overrides and the user-provided one are used in the user configuration if stylix.base16Scheme is not changed in the user config. If that is the case, only the user override is used.

Extending

When passing colors to unsupported targets or creating custom modules, it is possible to access values from the configured color scheme through config.lib.stylix.colors. An overview of the available values is shown below.

config.lib.stylix.colors = {
  base08 = "ff0000";
  base08-hex-r = "ff";
  base08-dec-r = "0.996094";
  # ...
  red = "ff0000";
  # ...
  withHashtag = {
    base08 = "#ff0000";
    # ...
  };
};

This attrset is generated by mkSchemeAttrs from base16.nix. Refer to the documentation for more info.

For more complex configurations you may find it simpler to use mustache templates to generate output files. See base16.nix documentation for usage examples.

Fonts

The default combination of fonts is:

{
  stylix.fonts = {
    serif = {
      package = pkgs.dejavu_fonts;
      name = "DejaVu Serif";
    };

    sansSerif = {
      package = pkgs.dejavu_fonts;
      name = "DejaVu Sans";
    };

    monospace = {
      package = pkgs.dejavu_fonts;
      name = "DejaVu Sans Mono";
    };

    emoji = {
      package = pkgs.noto-fonts-emoji;
      name = "Noto Color Emoji";
    };
  };
}

These can be changed as you like.

To make things look more uniform, you could replace the serif font with the sans-serif font:

{
  stylix.fonts.serif = config.stylix.fonts.sansSerif;
}

Or even choose monospace for everything:

{
  stylix.fonts = {
    serif = config.stylix.fonts.monospace;
    sansSerif = config.stylix.fonts.monospace;
    emoji = config.stylix.fonts.monospace;
  };
}

Home Manager inheritance

By default, if Home Manager is used as part of NixOS, then Stylix will be automatically installed for all users, and the NixOS theme will become their default settings.

This is convenient for single-user systems, since you can configure everything once at the system level and it will automatically carry over. For multi-user systems, you can override the settings within Home Manager to select a different theme for each user.

You may prefer to disable inheritance entirely, and set up the Home Manager version of Stylix yourself if required. Refer to the options stylix.homeManagerIntegration.autoImport and stylix.homeManagerIntegration.followSystem to customize this.

Note

There is a special case involving the stylix.base16Scheme option:

If the wallpaper in a Home Manager configuration is changed, then Home Manager will stop inheriting the color scheme from NixOS. This allows Home Manager configurations to use the automatic palette generator without being overridden.

Similarly, stylix.override is not inherited if the color scheme is different.

Turning targets on and off

In Stylix terms, a target is anything which can have colors, fonts or a wallpaper applied to it. Each module in this repository should correspond to a target of the same name.

Each target has an option like stylix.targets.«target».enable to turn its styling on or off. Normally, it's turned on automatically when the target is installed. You can set stylix.autoEnable = false to opt out of this behaviour, in which case you'll need to manually enable each target you want to be styled.

Targets are different between Home Manager and NixOS, and sometimes available in both cases. If both are available, it is always correct to enable both. The reference pages have a list of targets for NixOS and Home Manager respectively.

Tips and tricks

Adjusting the brightness and contrast of a background image

If you want to use a background image for your desktop but find it too bright or distracting, you can use the imagemagick package to dim the image, or adjust its brightness and contrast to suit your preference.

Here's an example Nix expression that takes an input image, applies a brightness/contrast adjustment to it, and saves the result as a new image file:

{ pkgs, ... }:

let
  inputImage = ./path/to/image.jpg;
  brightness = -30;
  contrast = 0;
  fillColor = "black"
in
{
  stylix.image = pkgs.runCommand "dimmed-background.png" { } ''
    ${pkgs.imagemagick}/bin/convert "${inputImage}" -brightness-contrast ${brightness},${contrast} -fill ${fillColor} $out
  '';
}

Dynamic wallpaper generation based on selected theme

With imagemagick, you can also dynamically generate wallpapers based on the selected theme. Similarly, you can use a template image and repaint it for the current theme.

{ pkgs, ... }:

let
  theme = "${pkgs.base16-schemes}/share/themes/catppuccin-latte.yaml";
  wallpaper = pkgs.runCommand "image.png" {} ''
        COLOR=$(${pkgs.yq}/bin/yq -r .base00 ${theme})
        COLOR="#"$COLOR
        ${pkgs.imagemagick}/bin/magick convert -size 1920x1080 xc:$COLOR $out
  '';
in {
  stylix = {
    image = wallpaper;
    base16Scheme = theme;
  };
}

Which is neatly implemented as a single function in lib.stylix.pixel:

{ pkgs, config, ... }:

{
  stylix = {
    image = config.lib.stylix.pixel "base0A";
    base16Scheme = "${pkgs.base16-schemes}/share/themes/catppuccin-latte.yaml";
  };
}

Completely disabling some stylix targets

Nixpkgs module system sometimes works in non-intuitive ways, e.g. parts of the configuration guarded by lib.mkIf are still being descended into. This means that every loaded (and not enabled) module must be compatible with others - in the sense that every option that is mentioned in the disabled parts of the configuration still needs to be defined somewhere.

Sometimes that can be a problem, when your particular configuration diverges enough from what stylix expects. In that case you can try stubbing all the missing options in your configuration.

Or in a much clearer fashion you can just disable offending stylix targets by adding the following disableModules line next to importing stylix itself:

imports = [ flake.inputs.stylix.nixosModules.stylix ];
disabledModules = [ "${flake.inputs.stylix}/modules/<some-module>/nixos.nix" ];

NixOS options

The following options can only be set in a NixOS configuration.

stylix.enable

Whether to enable Stylix.

When this is false, all theming is disabled and all other options are ignored.

Type: boolean

Default: false

Example: true

stylix.autoEnable

Whether to enable targets by default.

When this is false, all targets are disabled unless explicitly enabled.

When this is true, most targets are enabled by default. A small number remain off by default, because they require further manual setup, or they are only applicable in specific circumstances which cannot be detected automatically.

Type: boolean

Default: true

Example: false

stylix.base16Scheme

A scheme following the base16 standard.

This can be a path to a file, a string of YAML, or an attribute set.

Type: path or strings concatenated with “\n” or (attribute set)

Default: The colors used in the theming.

Those are automatically selected from the background image by default, but could be overridden manually.

stylix.cursor.package

Package providing the cursor theme.

Type: package

Default: <derivation vanilla-dmz-0.4.5>

stylix.cursor.name

The cursor name within the package.

Type: string

Default: "Vanilla-DMZ"

stylix.cursor.size

The cursor size.

Type: signed integer

Default: 32

stylix.fonts.packages

A list of all the font packages that will be installed.

Type: list of package (read only)

stylix.fonts.emoji

Emoji font.

Type: submodule

Default:

{
  name = "Noto Color Emoji";
  package = <derivation noto-fonts-color-emoji-2.047>;
}

stylix.fonts.emoji.package

Package providing the font.

Type: package

stylix.fonts.emoji.name

Name of the font within the package.

Type: string

stylix.fonts.monospace

Monospace font.

Type: submodule

Default:

{
  name = "DejaVu Sans Mono";
  package = <derivation dejavu-fonts-2.37>;
}

stylix.fonts.monospace.package

Package providing the font.

Type: package

stylix.fonts.monospace.name

Name of the font within the package.

Type: string

stylix.fonts.sansSerif

Sans-serif font.

Type: submodule

Default:

{
  name = "DejaVu Sans";
  package = <derivation dejavu-fonts-2.37>;
}

stylix.fonts.sansSerif.package

Package providing the font.

Type: package

stylix.fonts.sansSerif.name

Name of the font within the package.

Type: string

stylix.fonts.serif

Serif font.

Type: submodule

Default:

{
  name = "DejaVu Serif";
  package = <derivation dejavu-fonts-2.37>;
}

stylix.fonts.serif.package

Package providing the font.

Type: package

stylix.fonts.serif.name

Name of the font within the package.

Type: string

stylix.fonts.sizes.applications

The font size used by applications.

Type: unsigned integer, meaning >=0

Default: 12

stylix.fonts.sizes.desktop

The font size used in window titles/bars/widgets elements of the desktop.

Type: unsigned integer, meaning >=0

Default: 10

stylix.fonts.sizes.popups

The font size for notifications/popups and in general overlay elements of the desktop.

Type: unsigned integer, meaning >=0

Default: 10

stylix.fonts.sizes.terminal

The font size for terminals/text editors.

Type: unsigned integer, meaning >=0

Default: 12

stylix.homeManagerIntegration.autoImport

Whether to import Stylix automatically for every Home Manager user.

This only works if you are using home-manager.users.«name» within your NixOS configuration, rather than running Home Manager independently.

Type: boolean

Default: true

Example: false

stylix.homeManagerIntegration.followSystem

When this option is true, Home Manager configurations will follow the NixOS configuration by default, rather than using the standard default settings.

This only applies to Home Manager configurations managed by stylix.homeManagerIntegration.autoImport.

Type: boolean

Default: true

Example: false

stylix.image

Wallpaper image.

This is set as the background of your desktop environment, if possible, and used to generate a colour scheme if you don’t set one manually.

Type: path or package convertible to it

stylix.imageScalingMode

Wallpaper scaling mode;

This is the scaling mode your wallpaper image will use assuming it doesnt fix your monitor perfectly

Type: one of “stretch”, “fill”, “fit”, “center”, “tile”

Default: "fill"

stylix.opacity.applications

The opacity of the windows of applications, the amount of applications supported is currently limited

Type: floating point number

Default: 1.0

stylix.opacity.desktop

The opacity of the windows of bars/widgets, the amount of applications supported is currently limited

Type: floating point number

Default: 1.0

stylix.opacity.popups

The opacity of the windows of notifications/popups, the amount of applications supported is currently limited

Type: floating point number

Default: 1.0

stylix.opacity.terminal

The opacity of the windows of terminals, this works across all terminals supported by stylix

Type: floating point number

Default: 1.0

stylix.override

An override that will be applied to stylix.base16Scheme when generating config.lib.stylix.colors.

Takes anything that a scheme generated by base16nix can take as argument to override.

Type: attribute set

Default: { }

stylix.polarity

Use this option to force a light or dark theme.

By default we will select whichever is ranked better by the genetic algorithm. This aims to get good contrast between the foreground and background, as well as some variety in the highlight colours.

Type: one of “either”, “light”, “dark”

Default: "either"

stylix.targets.chromium.enable

Whether to enable theming for Chromium, Google Chrome and Brave.

Type: boolean

Scope	Purpose
`ci`	Changes to GitHub Actions workflows.
`doc`	Changes to the website, `README.md`, and so on.
`stylix`	Changes in the `stylix` directory, `flake.nix`, and other global code.
Name of target	Changes to code for a particular target.
`treewide`	Changes across many targets.