nix3-build

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 [options...] [installables...]

--json
    Output build results and other information in JSON format.

--no-link
    Do not create the default symlink (result) to the build output.

--out-link <path>
    Create a symlink at the specified path to the build result (default: ./result).

--offline
    Do not allow network access during evaluation or building.

--builders <spec>
    Specify which remote builders to use for distributed builds.

--flake <path>
    Treat inputs as flake references (e.g., ., nixpkgs#hello).

--show-trace
    Show a detailed evaluation trace on error, useful for debugging.

--refresh
    Re-evaluate and update Nix Flake inputs before building.

--impure
    Allow impure evaluation, which can compromise reproducibility but is sometimes necessary for debugging.

--override-input <input>=<path>
    Override a specific flake input with a different path or URI.

--max-jobs <n>
    Set the maximum number of parallel build jobs.

--cores <n>
    Set the number of CPU cores to use for local builds.

--store <uri>
    Specify a different Nix store to build into or query.

The nix build command is a cornerstone of the Nix package manager, designed to evaluate and build software derivations into the Nix store. It takes Nix expressions, which define how software should be built, and executes the necessary steps like fetching sources, compiling, and installing.

Unlike its predecessor, nix-build, this command is part of the modern, unified Nix CLI (often conceptualized as 'nix3') and offers enhanced features, particularly native support for Nix Flakes. It enables users to build specific attributes from a flake.nix file or traditional Nix expressions.

Upon successful completion, nix build places the built artifacts in the immutable Nix store and, by default, creates a symlink named result in the current directory pointing to the output. This ensures reproducibility and isolation of build products.

nix build relies on the Nix daemon for multi-user builds or remote operations. Ensure the daemon is running if you encounter permissions or connectivity issues.
By design, Nix outputs are immutable; once built, a derivation path in the store cannot be modified. This ensures reproducibility but means changes require rebuilding.
The reproducibility of builds depends heavily on the purity of the build environment and the precise definition of all inputs. Impure operations (e.g., network access during build) can compromise reproducibility.

When nix build successfully completes, it creates a symlink named result in the current directory. This symlink points to the root of the built derivation in the Nix store. This is a convenient way to access the built artifacts without knowing their exact cryptic store path.

For example, if you build a package, you can often find its executables under ./result/bin/. The --no-link option can prevent this symlink creation, and --out-link allows specifying a custom symlink name or path.

One of the key strengths of nix build is its deep integration with Nix Flakes. It allows users to directly build specific outputs defined within a flake.nix file. For instance, to build the packages.x86_64-linux.hello output from a flake, you can simply run nix build .#hello.

This paradigm simplifies dependency management and project structure, making it easier to define and build reproducible projects. nix build leverages the locked inputs of flakes to ensure repeatable builds across different environments.

The nix build command emerged as part of the strategic overhaul of the Nix CLI, often referred to as the 'new' or 'nix3' CLI during its development phase. Its primary goal was to provide a more consistent, user-friendly interface and native support for Nix Flakes, a declarative way to manage Nix projects and their dependencies.

It effectively superseded the older nix-build command, consolidating its functionality while introducing a modern approach to interacting with the Nix ecosystem. The introduction of nix build marked a significant step towards the unification and simplification of common Nix workflows, making it the recommended method for building derivations in modern Nix environments.

nix run(1), nix shell(1), nix develop(1), nix install(1), nix-store(1)