Specialisation: multiple configuration variants in one generation

specialisation is a powerful but often underrated NixOS feature. It lets you derive several "parallel worlds" with different configuration variants within the same system generation.
In everyday terms, it is like creating several branches of your system configuration, all produced in a single build. Built variants can be activated directly, although changes to the kernel, boot setup, and some drivers require a reboot.

1. The core concept: what is a specialisation?#

Normally, running nixos-rebuild switch builds the state described by your current configuration.nix and creates a generation.
specialisation lets you define several child configurations based on that configuration. They inherit everything from the base configuration and then override or extend specific settings. A single rebuild produces the base configuration and all specialisations together, sharing one generation number.

2. Why use specialisations?#

Consider these scenarios:

1. You normally use integrated graphics for work, but occasionally connect a discrete GPU for gaming or deep learning.
2. You normally need a firewall and a proxy, but sometimes want to test local network services and adjust which test ports the firewall allows.
3. You normally use GNOME but occasionally want to try Hyprland, with separate definitions for desktop services and software selections.

Without specialisation, you would have to edit the configuration and rebuild each time.
With specialisation, you can define these occasional configurations as variants, select one directly from the GRUB menu at boot, or switch immediately with a command while the system is running. Some settings may require logging in again.

3. How to define a specialisation#

In configuration.nix, define it using specialisation.<name>.configuration.

{ config, pkgs, lib, ... }:
{
  # ===== 基础配置（日常模式）=====
  networking.firewall.enable = true;
  services.desktopManager.gnome.enable = true;
  environment.systemPackages = with pkgs; [ firefox git ];

  # ===== 特化配置 1：游戏模式 =====
  specialisation."gaming".configuration = {
    # 按服务需要开放示例端口，避免为游戏直接关闭整个防火墙
    networking.firewall.allowedUDPPorts = [ 27015 ];
    
    # 安装 Steam 和显卡驱动相关工具
    environment.systemPackages = with pkgs; [ steam mangohud gamemode ];
  };

  # ===== 特化配置 2：开发/调试模式 =====
  specialisation."debug".configuration = {
    # 启用更详细的内核日志
    boot.kernelParams = [ "debug" ];
    
    # 安装一堆调试工具
    environment.systemPackages = with pkgs; [ gdb valgrind strace ltrace ];
  };
}

4. How to use the variants#

After building them with sudo nixos-rebuild switch, there are three ways to use them:

1. Select one in GRUB at boot

Restart the computer. In the "NixOS - All configurations" submenu in GRUB, you will see entries like these:

• NixOS Generation 105 (the default base configuration)
• NixOS Generation 105 - gaming
• NixOS Generation 105 - debug

Select an entry to enter that environment.

2. Switch on a running system without rebooting

To switch immediately from "everyday mode" to "gaming mode", run:

sudo /nix/var/nix/profiles/system/specialisation/gaming/bin/switch-to-configuration test

To reevaluate or rebuild from the source configuration and activate a specific variant, use the rebuild interface supported on your machine:

sudo nixos-rebuild test --specialisation gaming

Note: how much a live switch can apply depends on the configuration. Software paths in the new closure and services that support live activation will switch, but running processes do not automatically change to the new binaries. Changes involving kernel modules or display managers, such as switching from GNOME to Hyprland, may require logging out and back in, or even rebooting, to take full effect.

3. Paths and helper tools

The official module documentation uses /run/current-system/specialisation/<name>/bin/switch-to-configuration test. After switching away from the base system, /run/current-system may point to the variant. To access sibling variants, use the system profile path that still points to the base generation, or explicitly save the base closure path. Helper tools may identify variants through marker files; check their conventions for the tool version in use. Native specialisations do not automatically guarantee an /etc/specialisation marker.

4. Overriding inherited values

Specialisations inherit their parent configuration by default, and option merging still follows the module system rules. Ordinary definitions of different boolean or string values in the parent and child can conflict. Use lib.mkForce for an explicit override; lists, by contrast, are often appended by default. For example:

specialisation.minimal.configuration = {
  services.desktopManager.gnome.enable = lib.mkForce false;
};

inheritParentConfig = false disables inheritance from the parent configuration, but you must then provide a complete, valid system configuration. This does not isolate processes, data, or hardware.

5. Advantages and limitations of specialisations#

Advantages:

• Time savings: one build makes several configurations available.
• Atomicity: variants and the base configuration are tied to the same generation and roll back together, avoiding mismatched configuration versions.
• A clean environment: software used only occasionally does not have to remain in your everyday environment.

Limitations:

• Longer builds: all variants must be built in one rebuild. If variants include substantial software such as Steam, updates evaluate them and ensure that every variant output is available. Existing store outputs or cached results can be reused, so not everything needs recompiling.
• No crossing hardware boundaries: specialisations run on the same hardware system. They are not a way to make one configuration behave differently on two different computers; use multiple nixosConfigurations in a flake for that.

Summary#

specialisation elegantly expresses the declarative nature of NixOS. It records the system’s different operating modes in configuration files, letting you switch work environments through a simple choice of directory or boot entry, with clear boundaries between activation and reboot requirements.