To begin the installation, you have to boot your computer from the install drive.

The graphical installer is recommended for desktop users and will guide you through the installation.

NixOS can be installed on BIOS or UEFI systems. The procedure for a UEFI installation is broadly the same as for a BIOS installation. The differences are mentioned in the following steps.

The NixOS manual is available by running nixos-help in the command line or from the application menu in the desktop environment.

To have access to the command line on the graphical images, open Terminal (GNOME) or Konsole (Plasma) from the application menu.

You are logged-in automatically as nixos. The nixos user account has an empty password so you can use sudo without a password:

$ sudo -i

You can use loadkeys to switch to your preferred keyboard layout. (We even provide neo2 via loadkeys de neo!)

If the text is too small to be legible, try setfont ter-v32n to increase the font size.

To install over a serial port connect with 115200n8 (e.g. picocom -b 115200 /dev/ttyUSB0). When the bootloader lists boot entries, select the serial console boot entry.

# parted /dev/sda -- mklabel msdos
# parted /dev/sda -- mkpart primary 1MB -8GB
# parted /dev/sda -- mkpart primary linux-swap -8GB 100%

# parted /dev/sda -- mklabel gpt
# parted /dev/sda -- mkpart root ext4 512MB -8GB
# parted /dev/sda -- mkpart swap linux-swap -8GB 100%
# parted /dev/sda -- mkpart ESP fat32 1MB 512MB
# parted /dev/sda -- set 3 esp on

# mkfs.ext4 -L nixos /dev/sda1
# mkswap -L swap /dev/sda2
# swapon /dev/sda2
# mkfs.fat -F 32 -n boot /dev/sda3        # (for UEFI systems only)
# mount /dev/disk/by-label/nixos /mnt
# mkdir -p /mnt/boot                      # (for UEFI systems only)
# mount -o umask=077 /dev/disk/by-label/boot /mnt/boot # (for UEFI systems only)
# nixos-generate-config --root /mnt
# nano /mnt/etc/nixos/configuration.nix
# nixos-install
# reboot

{ config, pkgs, ... }: {
  imports = [
    # Include the results of the hardware scan.
    ./hardware-configuration.nix
  ];

  boot.loader.grub.device = "/dev/sda";   # (for BIOS systems only)
  boot.loader.systemd-boot.enable = true; # (for UEFI systems only)

  # Note: setting fileSystems is generally not
  # necessary, since nixos-generate-config figures them out
  # automatically in hardware-configuration.nix.
  #fileSystems."/".device = "/dev/disk/by-label/nixos";

  # Enable the OpenSSH server.
  services.sshd.enable = true;
}

You can keep a NixOS system up-to-date automatically by adding the following to configuration.nix:

{
  system.autoUpgrade.enable = true;
  system.autoUpgrade.allowReboot = true;
}

This enables a periodically executed systemd service named nixos-upgrade.service. If the allowReboot option is false, it runs nixos-rebuild switch --upgrade to upgrade NixOS to the latest version in the current channel. (To see when the service runs, see systemctl list-timers.) If allowReboot is true, then the system will automatically reboot if the new generation contains a different kernel, initrd or kernel modules. You can also specify a channel explicitly, e.g.

{ system.autoUpgrade.channel = "https://channels.nixos.org/nixos-25.11"; }

To build an ISO image for the channel nixos-unstable:

$ git clone https://github.com/NixOS/nixpkgs.git
$ cd nixpkgs/nixos
$ git switch nixos-unstable
$ nix-build -A config.system.build.isoImage -I nixos-config=modules/installer/cd-dvd/installation-cd-minimal.nix default.nix

To check the content of an ISO image, mount it like so:

# mount -o loop -t iso9660 ./result/iso/nixos-image-25.05pre-git-x86_64-linux.iso /mnt/iso

If you need additional (non-distributable) drivers or firmware in the installer, you might want to extend these configurations.

For example, to build the GNOME graphical installer ISO, but with support for certain WiFi adapters present in some MacBooks, you can create the following file at modules/installer/cd-dvd/installation-cd-graphical-gnome-macbook.nix:

{ config, ... }:

{
  imports = [ ./installation-cd-graphical-gnome.nix ];

  boot.initrd.kernelModules = [ "wl" ];

  boot.kernelModules = [
    "kvm-intel"
    "wl"
  ];
  boot.extraModulePackages = [ config.boot.kernelPackages.broadcom_sta ];
}

Then build it like in the example above:

$ git clone https://github.com/NixOS/nixpkgs.git
$ cd nixpkgs/nixos
$ export NIXPKGS_ALLOW_UNFREE=1
$ nix-build -A config.system.build.isoImage -I nixos-config=modules/installer/cd-dvd/installation-cd-graphical-gnome-macbook.nix default.nix

The config value enforcement is implemented via mkImageMediaOverride = mkOverride 60; and therefore primes over simple value assignments, but also yields to mkForce.

This property allows image designers to implement in semantically correct ways those configuration values upon which the correct functioning of the image depends.

For example, the iso base image overrides those file systems which it needs at a minimum for correct functioning, while the installer base image overrides the entire file system layout because there can’t be any other guarantees on a live medium than those given by the live medium itself. The latter is especially true before formatting the target block device(s). On the other hand, the netboot iso only overrides its minimum dependencies since netboot images are always made-to-target.

If you want to rewrite Nix store paths, e.g., to remove the /nix/store prefix or to nest it below a parent path, you can do that through the nixStorePrefix option.

{
  fileSystems."/nix/store".device = "/dev/disk/by-partlabel/nix-store";

  image.repart.partitions = {
    "store" = {
      storePaths = [ config.system.build.toplevel ];
      nixStorePrefix = "/";
      repartConfig = {
        Type = "linux-generic";
        Label = "nix-store";
        # ...
      };
    };
  };
}

{
  fileSystems."/" = {
    device = "/dev/disk/by-partlabel/root";
    fsType = "btrfs";
    options = [ "subvol=/@" ];
  };

  fileSystems."/nix/store" = {
    device = "/dev/disk/by-partlabel/root";
    fsType = "btrfs";
    options = [ "subvol=/@nix-store" ];
  };

  image.repart.partitions = {
    "root" = {
      storePaths = [ config.system.build.toplevel ];
      nixStorePrefix = "/@nix-store";
      repartConfig = {
        Type = "root";
        Label = "root";
        Format = "btrfs";
        Subvolumes = "/@ /@nix-store";
        MakeDirectories = "/@ /@nix-store";
        # ...
      };
    };
  };
}

The image/repart.nix module can also be used to build self-contained software appliances.

The generation based update mechanism of NixOS is not suited for appliances. Updates of appliances are usually either performed by replacing the entire image with a new one or by updating partitions via an A/B scheme. See the Chrome OS update process for an example of how to achieve this. The appliance image built in the following example does not contain a configuration.nix and thus you will not be able to call nixos-rebuild from this system. Furthermore, it uses a Unified Kernel Image.

let
  pkgs = import <nixpkgs> { };
  efiArch = pkgs.stdenv.hostPlatform.efiArch;
in
(pkgs.nixos [
  (
    {
      config,
      lib,
      pkgs,
      modulesPath,
      ...
    }:
    {

      imports = [ "${modulesPath}/image/repart.nix" ];

      boot.loader.grub.enable = false;

      fileSystems."/".device = "/dev/disk/by-label/nixos";

      image.repart = {
        name = "image";
        partitions = {
          "esp" = {
            contents = {
              "/EFI/BOOT/BOOT${lib.toUpper efiArch}.EFI".source =
                "${pkgs.systemd}/lib/systemd/boot/efi/systemd-boot${efiArch}.efi";

              "/EFI/Linux/${config.system.boot.loader.ukiFile}".source =
                "${config.system.build.uki}/${config.system.boot.loader.ukiFile}";
            };
            repartConfig = {
              Type = "esp";
              Format = "vfat";
              SizeMinBytes = "96M";
            };
          };
          "root" = {
            storePaths = [ config.system.build.toplevel ];
            repartConfig = {
              Type = "root";
              Format = "ext4";
              Label = "nixos";
              Minimize = "guess";
            };
          };
        };
      };

    }
  )
]).image

The NixOS configuration file generally looks like this:

{ config, pkgs, ... }:

{
  # option definitions
}

The first line ({ config, pkgs, ... }:) denotes that this is actually a function that takes at least the two arguments config and pkgs. (These are explained later, in chapter Writing NixOS Modules) The function returns a set of option definitions ({ ... }). These definitions have the form name = value, where name is the name of an option and value is its value. For example,

{ config, pkgs, ... }:

{
  services.httpd.enable = true;
  services.httpd.adminAddr = "[email protected]";
  services.httpd.virtualHosts.localhost.documentRoot = "/webroot";
}

defines a configuration with three option definitions that together enable the Apache HTTP Server with /webroot as the document root.

Sets can be nested, and in fact dots in option names are shorthand for defining a set containing another set. For instance, services.httpd.enable defines a set named services that contains a set named httpd, which in turn contains an option definition named enable with value true. This means that the example above can also be written as:

{ config, pkgs, ... }:

{
  services = {
    httpd = {
      enable = true;
      adminAddr = "[email protected]";
      virtualHosts = {
        localhost = {
          documentRoot = "/webroot";
        };
      };
    };
  };
}

which may be more convenient if you have lots of option definitions that share the same prefix (such as services.httpd).

NixOS checks your option definitions for correctness. For instance, if you try to define an option that doesn’t exist (that is, doesn’t have a corresponding option declaration), nixos-rebuild will give an error like:

The option `services.httpd.enable' defined in `/etc/nixos/configuration.nix' does not exist.

Likewise, values in option definitions must have a correct type. For instance, services.httpd.enable must be a Boolean (true or false). Trying to give it a value of another type, such as a string, will cause an error:

The option value `services.httpd.enable' in `/etc/nixos/configuration.nix' is not a boolean.

Options have various types of values. The most important are:

If you find yourself repeating yourself over and over, it’s time to abstract. Take, for instance, this Apache HTTP Server configuration:

{
  services.httpd.virtualHosts = {
    "blog.example.org" = {
      documentRoot = "/webroot/blog.example.org";
      adminAddr = "[email protected]";
      forceSSL = true;
      enableACME = true;
    };
    "wiki.example.org" = {
      documentRoot = "/webroot/wiki.example.org";
      adminAddr = "[email protected]";
      forceSSL = true;
      enableACME = true;
    };
  };
}

It defines two virtual hosts with nearly identical configuration; the only difference is the document root directories. To prevent this duplication, we can use a let:

let
  commonConfig = {
    adminAddr = "[email protected]";
    forceSSL = true;
    enableACME = true;
  };
in
{
  services.httpd.virtualHosts = {
    "blog.example.org" = (commonConfig // { documentRoot = "/webroot/blog.example.org"; });
    "wiki.example.org" = (commonConfig // { documentRoot = "/webroot/wiki.example.org"; });
  };
}

The let commonConfig = ... defines a variable named commonConfig. The // operator merges two attribute sets, so the configuration of the second virtual host is the set commonConfig extended with the document root option.

You can write a let wherever an expression is allowed. Thus, you also could have written:

{
  services.httpd.virtualHosts =
    let
      commonConfig = {
        # ...
      };
    in
    {
      "blog.example.org" = (
        commonConfig
        // {
          # ...
        }
      );
      "wiki.example.org" = (
        commonConfig
        // {
          # ...
        }
      );
    };
}

but not { let commonConfig = ...; in ...; } since attributes (as opposed to attribute values) are not expressions.

Functions provide another method of abstraction. For instance, suppose that we want to generate lots of different virtual hosts, all with identical configuration except for the document root. This can be done as follows:

{
  services.httpd.virtualHosts =
    let
      makeVirtualHost = webroot: {
        documentRoot = webroot;
        adminAddr = "[email protected]";
        forceSSL = true;
        enableACME = true;
      };
    in
    {
      "example.org" = (makeVirtualHost "/webroot/example.org");
      "example.com" = (makeVirtualHost "/webroot/example.com");
      "example.gov" = (makeVirtualHost "/webroot/example.gov");
      "example.nl" = (makeVirtualHost "/webroot/example.nl");
    };
}

Here, makeVirtualHost is a function that takes a single argument webroot and returns the configuration for a virtual host. That function is then called for several names to produce the list of virtual host configurations.

The NixOS configuration mechanism is modular. If your configuration.nix becomes too big, you can split it into multiple files. Likewise, if you have multiple NixOS configurations (e.g. for different computers) with some commonality, you can move the common configuration into a shared file.

Modules have exactly the same syntax as configuration.nix. In fact, configuration.nix is itself a module. You can use other modules by including them from configuration.nix, e.g.:

{ config, pkgs, ... }:

{
  imports = [
    ./vpn.nix
    ./kde.nix
  ];
  services.httpd.enable = true;
  environment.systemPackages = [ pkgs.emacs ];
  # ...
}

Here, we include two modules from the same directory, vpn.nix and kde.nix. The latter might look like this:

{ config, pkgs, ... }:

{
  services.xserver.enable = true;
  services.displayManager.sddm.enable = true;
  services.desktopManager.plasma6.enable = true;
  environment.systemPackages = [ pkgs.vim ];
}

Note that both configuration.nix and kde.nix define the option environment.systemPackages. When multiple modules define an option, NixOS will try to merge the definitions. In the case of environment.systemPackages the lists of packages will be concatenated. The value in configuration.nix is merged last, so for list-type options, it will appear at the end of the merged list. If you want it to appear first, you can use mkBefore:

{ boot.kernelModules = mkBefore [ "kvm-intel" ]; }

This causes the kvm-intel kernel module to be loaded before any other kernel modules.

For other types of options, a merge may not be possible. For instance, if two modules define services.httpd.adminAddr, nixos-rebuild will give an error:

The unique option `services.httpd.adminAddr' is defined multiple times, in `/etc/nixos/httpd.nix' and `/etc/nixos/configuration.nix'.

When that happens, it’s possible to force one definition take precedence over the others:

{ services.httpd.adminAddr = pkgs.lib.mkForce "[email protected]"; }

When using multiple modules, you may need to access configuration values defined in other modules. This is what the config function argument is for: it contains the complete, merged system configuration. That is, config is the result of combining the configurations returned by every module. (If you’re wondering how it’s possible that the (indirect) result of a function is passed as an input to that same function: that’s because Nix is a “lazy” language — it only computes values when they are needed. This works as long as no individual configuration value depends on itself.)

For example, here is a module that adds some packages to environment.systemPackages only if services.xserver.enable is set to true somewhere else:

{ config, pkgs, ... }:

{
  environment.systemPackages =
    if config.services.xserver.enable then
      [
        pkgs.firefox
        pkgs.thunderbird
      ]
    else
      [ ];
}

With multiple modules, it may not be obvious what the final value of a configuration option is. The command nixos-option allows you to find out:

$ nixos-option services.xserver.enable
true

$ nixos-option boot.kernelModules
[ "tun" "ipv6" "loop" ... ]

Interactive exploration of the configuration is possible using nix repl, a read-eval-print loop for Nix expressions. A typical use:

$ nix repl '<nixpkgs/nixos>'

nix-repl> config.networking.hostName
"mandark"

nix-repl> map (x: x.hostName) config.services.httpd.virtualHosts
[ "example.org" "example.gov" ]

While abstracting your configuration, you may find it useful to generate modules using code, instead of writing files. The example below would have the same effect as importing a file which sets those options.

{ config, pkgs, ... }:

let
  netConfig = hostName: {
    networking.hostName = hostName;
    networking.useDHCP = false;
  };

in
{
  imports = [ (netConfig "nixos.localdomain") ];
}

With declarative package management, you specify which packages you want on your system by setting the option environment.systemPackages. For instance, adding the following line to configuration.nix enables the Mozilla Thunderbird email application:

{ environment.systemPackages = [ pkgs.thunderbird ]; }

The effect of this specification is that the Thunderbird package from Nixpkgs will be built or downloaded as part of the system when you run nixos-rebuild switch.

You can get a list of the available packages as follows:

$ nix-env -qaP '*' --description
nixos.firefox   firefox-23.0   Mozilla Firefox - the browser, reloaded
...

The first column in the output is the attribute name, such as nixos.thunderbird.

Note: the nixos prefix tells us that we want to get the package from the nixos channel and works only in CLI tools. In declarative configuration, use pkgs prefix (variable).

To “uninstall” a package, remove it from environment.systemPackages and run nixos-rebuild switch.

{
  nixpkgs.config = {
    allowUnfree = true;
  };
}

{
  environment.systemPackages = with pkgs; [
    sl
    (pass.withExtensions (
      subpkgs: with subpkgs; [
        pass-audit
        pass-otp
        pass-genphrase
      ]
    ))
    (python3.withPackages (subpkgs: with subpkgs; [ requests ]))
    cowsay
  ];
}

{ environment.systemPackages = [ (pkgs.emacs.override { gtk = pkgs.gtk3; }) ]; }