nix-build.3

Build a package from nixpkgs, symlinking the result to ./result

$ nix build [nixpkgs#pkg]

$ nix build -L [.#pkg]

$ nix build [path/to/directory]

$ nix build --no-link --print-out-paths

nix-build [path] [options...]
nix-build --expr expression [options...]
nix-build --attr attribute-path [options...]

[path]
    Path to the Nix expression file (e.g., default.nix) or directory containing it. Defaults to ./default.nix if omitted.

--arg name value
    Passes an argument named name with a Nix expression value to the top-level Nix expression.

--argstr name value
    Passes a string argument named name with string value to the top-level Nix expression.

-A attribute-path
    Selects and builds a specific attribute from the Nix expression. Can be used multiple times.

-E, --expr expression
    Evaluates and builds the given Nix expression string directly, instead of a file.

-Q, --no-out-link
    Suppresses the creation of the result symlink in the current directory.

-o path, --out-link path
    Creates the symlink to the build result at the specified path instead of ./result.

--check
    Performs a lightweight sanity check on the built derivation, like checking for missing paths.

--dry-run
    Shows what would be built and downloaded without actually performing the operations.

--show-trace
    Shows a detailed stack trace in case of evaluation errors, useful for debugging Nix expressions.

--max-jobs N
    Limits the number of jobs that Nix can run in parallel during a build. Default is 1.

--builders string
    Specifies a string of build machines to use (e.g., ssh://user@host arch).

--builders-use-substitutes
    Allows remote builders to use substitutes when possible, rather than rebuilding.

-K, --keep-failed
    Prevents Nix from deleting the temporary build directory when a build fails, useful for debugging.

-L, --print-build-logs
    Prints the build logs to standard output as the build progresses.

--option name value
    Sets a Nix configuration option for this command invocation (e.g., builders-use-substitutes).

nix-build is a fundamental command in the Nix package manager, designed to build derivations defined by Nix expressions. When executed, it interprets a specified Nix expression (typically a .nix file or a specific attribute within one) and attempts to build the corresponding software package or configuration. The command ensures a reproducible and atomic build process, leveraging Nix's unique functional approach to package management.

If the build is successful, nix-build places the resulting output path into the Nix store (e.g., /nix/store/hash-package-version). Crucially, it then creates a symbolic link named result in the current directory, pointing to this store path. This result symlink allows easy access to the built artifact. nix-build is widely used for developing and testing packages, as it isolates build environments and guarantees that dependencies are precisely managed. It supports various options for controlling build parameters, specifying attributes to build, or influencing how the output link is handled.

nix-build requires a working Nix installation and typically interacts with the Nix daemon. Builds can consume significant disk space and CPU resources. The result symlink in the current directory is generally overwritten on subsequent successful runs unless explicitly told not to or linked elsewhere. Dependencies must be precisely defined within the Nix expression for reproducible builds.

If no path is specified, nix-build defaults to building the default.nix file found in the current directory.

By default, a symlink named result is created in the current working directory, pointing to the built derivation in the Nix store. This symlink is typically removed and recreated on subsequent successful builds. Alternative symlink paths can be specified using --out-link.

Before commencing a build, nix-build attempts to download pre-built binaries (known as substitutes) from configured binary caches. This mechanism significantly accelerates the build process by reusing existing artifacts instead of rebuilding from source.

nix-build is one of the original, foundational commands of the Nix package manager, introduced early in its development. It encapsulates the core principle of Nix: building software derivations deterministically. Over time, while its fundamental purpose remains unchanged, the Nix ecosystem has evolved, leading to the introduction of the unified nix command (often called nix-command) in Nix 2.0 and later. The nix build subcommand within the new nix command provides a more modern and consistent interface, eventually aiming to supersede nix-build. However, nix-build remains widely used in existing Nix projects and scripts due to its long-standing presence and simplicity for direct derivation building.

nix-shell(1), nix-instantiate(1), nix-store(1), nix-prefetch-url(1), nix-repl(1), nix(1)