nixos-install(8)

nixos-install 💅

Okay bestie, welcome to the System Manager's Manual page for nixos-install. This is the one that installs bootloader + NixOS, and yes it's giving main-character installer energy. 🫶

✨ NAME ✨

nixos-install — install bootloader and NixOS

✨ SYNOPSIS ✨

nixos-install [--verbose | -v] [-I path] [--root root]
              [--system | --closure | --store-path path]
              [--flake flake-uri] [--file | -f path]
              [--attr | -A attrPath] [--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]
              [--log-format format] [--help]

Also peep these synopsis flags, bestie: --impure, --no-channel-copy, --no-root-password / --no-root-passwd, and --no-bootloader—keep those exact. The --no-channel-copy, --no-root-password, and --no-bootloader bits are lowkey called out in the install steps below. 💖

✨ DESCRIPTION ✨

This command installs NixOS in the file system mounted on /mnt, or defined through the --root option, based on the NixOS configuration specified in /mnt/etc/nixos/system.nix, /mnt/etc/nixos/configuration.nix or specified through the --file, --attror --flakeoptions. It performs the following steps:

1. It copies Nix and its dependencies to /mnt/nix/store.
2. It runs Nix in /mnt to build the given NixOS configuration.
3. It installs the current channel “nixos” in the target channel profile (unless --no-channel-copy is specified).
4. 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.
5. 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. That's the good stuff. 💅

✨ 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 root — Defaults to /mnt. If this option is given, treat the directory root as the root of the NixOS installation.
• --system path, --closure path, --store-path path — If one of those options 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’.
• --file path, -f path — Build the NixOS system from the specified file. The file must evaluate to an attribute set, and it must contain a valid NixOS configuration at attribute attrPath. This is useful for building a NixOS system from a nix file that is not a flake or a NixOS configuration module. Attribute set a with valid NixOS configuration can be made using nixos function in nixpkgs or importing and calling nixos/lib/eval-config.nix from nixpkgs. If specified without --attr option, builds the configuration from the top-level attribute set of the file.
• --attr attrPath, -A attrPath — Build the NixOS system from nix file and use the specified attribute path from file specified by the --file option. If specified without --file option, it tires to find system.nix in root/etc/nixos, in current directory and iteratively in parent directories.
• --channel channel — If this option is provided, do not copy the current “nixos” channel to the target host. Instead, use the specified derivation.
• -I Path — 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 number — 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 N — 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.
• --log-format format — Set the format of log output; one of raw, internal-json, bar or bar-with-logs.
• --help — Synonym for man nixos-install.

✨ EXAMPLES ✨

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

✨ AUTHORS ✨

Eelco Dolstra and the Nixpkgs/NixOS contributors

---

That's the whole page, bestie! Cute little sign-off time: this one comes from Debian, dated January 1, 1980, and it's the nixos-install(8) page. 💖✨