nix-shell

View documentation for the traditional shell

$ tldr nix-shell.2

$ tldr nix shell.3

nix-shell [options...] [<nix-file>]
nix-shell [options...] --packages <pkgs...>
nix-shell [options...] --expr <nix-expression>
nix-shell [options...] --run <command>

--run <command>
    Execute a specific command in the shell's environment instead of entering an interactive shell.

--pure
    Create a pristine shell environment, discarding most inherited environment variables for reproducibility.

--keep <env-var>
    Used with --pure, specifies environment variables from the parent shell to retain.

--ignore-environment
    Ignores all inherited environment variables, similar to --pure but less strict regarding shell functions.

--attr <path>
    Select a specific attribute path within the Nix expression to define the shell environment.

--file <nix-file>
    Specify the Nix expression file (e.g., shell.nix) to build the environment from. Defaults to shell.nix or default.nix in the current directory.

--expr <nix-expression>
    Provide a Nix expression directly on the command line to define the shell environment.

--packages <pkgs...>
    Define a shell environment by listing packages from nixpkgs directly, e.g., nix-shell -p git hello.

--arg <name> <value>
    Pass a Nix value as an argument to the Nix expression that defines the shell.

--argstr <name> <value>
    Similar to --arg, but ensures the value is passed as a string.

--show-trace
    Display a detailed stack trace on Nix evaluation errors, which is useful for debugging.

<nix-file>
    Positional argument for the Nix expression file (alternative to --file).

--help
    Display a help message with available options and usage.

--version
    Show the nix-shell version information.

nix-shell is a core command from the Nix package manager, designed to create reproducible, isolated development or build environments on demand. It evaluates a Nix expression (typically from a file like shell.nix or default.nix) to determine the exact set of dependencies, tools, and environment variables required for a project. Instead of installing software globally, nix-shell provides these components temporarily within the current shell session. When the session ends, the environment disappears, leaving no lasting changes to the system. This capability makes nix-shell invaluable for ensuring consistent developer setups, testing software in clean environments, and quickly trying out new tools without system clutter. It leverages Nix's content-addressable store for unparalleled reproducibility.

Initial Setup Time: The first time a nix-shell environment is entered, Nix might need to build or download many dependencies, which can take considerable time and bandwidth.
Disk Usage: Nix's content-addressable store can accumulate many derivations, potentially consuming significant disk space over time, though it is shared across projects.
Nix Language Learning Curve: Effectively using nix-shell for complex projects requires a basic understanding of the Nix expression language and its ecosystem.
Impurity Challenges: While striving for purity, certain operations (like network access or direct file system interactions outside the Nix store) can still introduce non-reproducibility.

nix-shell frequently leverages the vast Nixpkgs collection. By specifying packages with -p or by building derivations from Nixpkgs within a shell.nix, users gain access to an immense array of pre-defined software and tools, significantly simplifying environment setup.

The primary strength of nix-shell is its ability to create highly reproducible environments. Nix's deterministic dependency resolution and immutable build store ensure that identical nix-shell invocations on different machines (given the same Nix store content) will yield precisely identical development environments, virtually eliminating 'it works on my machine' issues.

A special feature within a Nix shell derivation is the shellHook attribute. This allows arbitrary shell commands to be executed automatically immediately after the shell is entered. It's commonly used for project-specific setup tasks like activating language-specific virtual environments, setting additional environment variables, or displaying custom welcome messages.

nix-shell has been a fundamental part of the Nix package manager since its early development. It represents the original approach to creating declarative development environments within the Nix ecosystem. While the newer nix shell command (introduced with the Nix Flakes feature) offers a more streamlined, opinionated, and flake-aware experience, nix-shell remains widely used, especially for legacy projects, non-flake setups, or when direct interaction with traditional Nix expressions is preferred. Its design laid the groundwork for Nix's core promise of reproducible development.

nix-build(1), nix-instantiate(1), nix-store(1), nix(1)