nixos-install - Man Page

nixos-install [{ --verbose | -v }] [-I path] [--root root] [--system path] [--flake flake-uri] [{--impure}] [--channel channel] [--no-channel-copy] [{ --no-root-password | --no-root-passwd }] [--no-bootloader] [{ --max-jobs | -j } number] [--cores number] [--option name value] [--show-trace] [--keep-going] [--help]

This command installs NixOS in the file system mounted on /mnt, based on the NixOS configuration specified in /mnt/etc/nixos/configuration​.nix​. It performs the following steps:

• It copies Nix and its dependencies to /mnt/nix/store​.
• It runs Nix in /mnt to build the NixOS configuration specified in /mnt/etc/nixos/configuration​.nix​.
• It installs the current channel “nixos” in the target channel profile (unless --no-channel-copy is specified)​.
• It installs the GRUB boot loader on the device specified in the option boot​.loader​.grub​.device (unless --no-bootloader is specified), and generates a GRUB configuration file that boots into the NixOS configuration just installed​.
• It prompts you for a password for the root account (unless --no-root-password is specified)​.

This command is idempotent: if it is interrupted or fails due to a temporary problem (e​.g​. a network issue), you can safely re-run it​.

This command accepts the following options:

--verbose / -v

Increases the level of verbosity of diagnostic messages printed on standard error​. For each Nix operation, the information printed on standard output is well-defined; any diagnostic information is printed on standard error, never on standard output​.

Please note that this option may be specified repeatedly​.

--root

Defaults to /mnt​. If this option is given, treat the directory root as the root of the NixOS installation​.

--system

If this option is provided, nixos-install will install the specified closure rather than attempt to build one from /mnt/etc/nixos/configuration​.nix​.

The closure must be an appropriately configured NixOS system, with boot loader and partition configuration that fits the target host​. Such a closure is typically obtained with a command such as nix-build -I nixos-config=​./configuration​.nix '<nixpkgs/nixos>' -A system --no-out-link

--flake flake-uri#name

Build the NixOS system from the specified flake​. The flake must contain an output named nixosConfigurations​.name​.

--channel

If this option is provided, do not copy the current “nixos” channel to the target host​. Instead, use the specified derivation​.

-I

Add a path to the Nix expression search path​. This option may be given multiple times​. See the NIX_PATH environment variable for information on the semantics of the Nix search path​. Paths added through -I take precedence over NIX_PATH​.

--max-jobs,  -j

Sets the maximum number of build jobs that Nix will perform in parallel to the specified number​. The default is 1​. A higher value is useful on SMP systems or to exploit I/O latency​.

--cores

Sets the value of the NIX_BUILD_CORES environment variable in the invocation of builders​. Builders can use this variable at their discretion to control the maximum amount of parallelism​. For instance, in Nixpkgs, if the derivation attribute enableParallelBuilding is set to true, the builder passes the -jN flag to GNU Make​. The value 0 means that the builder should use all available CPU cores in the system​.

--option name value

Set the Nix configuration option name to value​.

--show-trace

Causes Nix to print out a stack trace in case of Nix expression evaluation errors​.

--keep-going

Causes Nix to continue building derivations as far as possible in the face of failed builds​.

--help

Synonym for man nixos-install​.

A typical NixOS installation is done by creating and mounting a file system on /mnt, generating a NixOS configuration in /mnt/etc/nixos/configuration​.nix, and running nixos-install​. For instance, if we want to install NixOS on an ext4 file system created in /dev/sda1:

$ mkfs​.ext4 /dev/sda1
$ mount /dev/sda1 /mnt
$ nixos-generate-config --root /mnt
$ # edit /mnt/etc/nixos/configuration​.nix
$ nixos-install
$ reboot

Eelco Dolstra

Copyright © 2007-2020 Eelco Dolstra