nix-build.3

Build Nix expressions into a result

TLDR

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

$ nix build [nixpkgs#pkg]

Build a package from a flake in the current directory, showing the build logs in the process

$ nix build -L [.#pkg]

Build the default package from a flake in some directory

$ nix build [./path/to/directory]

Build a package without making the result symlink, instead printing the store path to the stdout

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

--help
    Show help message and exit.

--version
    Show version information and exit.

--no-out-link
    Don't create a symlink to the build result.

--out-link path
    Create a symlink to the build result at the specified path.

--keep-failed
    Don't garbage-collect failed builds.

--keep-going
    Continue building after a build failure.

--max-jobs count
    Set the maximum number of parallel build jobs.

--dry-run
    Evaluate the expression but don't perform any builds.

--expr expression
    Evaluate the given expression instead of reading from a file.

--arg name value
    Pass an argument to the expression.

--attr attribute-path
    Select an attribute from a Nix expression to build.

DESCRIPTION

nix-build builds Nix expressions in a hermetic and reproducible manner. It takes a Nix expression as input and produces a store path as output.
nix-build evaluates the expression in a sandbox, ensuring that builds are isolated from the user's environment. This isolation guarantees that the build process only depends on the declared dependencies, leading to consistent and predictable results.
The command is the foundation for the Nix package manager, which leverages the declarative nature of Nix expressions to create portable, reliable software builds.
It manages the fetching of source code, handling dependencies, and defining build steps within a well-defined framework.
nix-build's strong guarantees for reproducibility make it suitable for complex software projects and distributed build environments. By default, nix-build places the result in the current directory, but it can be changed with --out-link or the program automatically generates name.

CAVEATS

Builds are performed in a sandbox with limited access to the network and user environment. Ensure dependencies are properly declared in the Nix expression.

EXIT STATUS

nix-build returns 0 on success, and a non-zero value on failure. Failure could mean a syntax error in the Nix expression, or that one of the build steps returned a non-zero exit code.

NIX EXPRESSIONS

Nix expressions are the declarative language used to define software packages and environments. They specify the source code, dependencies, build instructions, and other metadata required to build a package.
These expressions are evaluated by nix-build to create reproducible builds.

HISTORY

nix-build is a core component of the Nix package manager, which was initially developed by Eelco Dolstra. The command's design emphasizes reproducibility and isolation, building upon the concepts of purely functional package management. It has evolved alongside the Nix ecosystem, with ongoing improvements to performance, feature set, and security.