nix-shell.3

Start an interactive shell with some packages from nixpkgs

$ nix shell [nixpkgs#pkg1 nixpkgs#packageSet.pkg2 ...]

$ nix shell [nixpkgs/nixos-21.05#pkg]

$ nix shell -L

$ nix shell [github:owner/repo#pkg]

$ nix shell [nixpkgs#pkg] -c [some-cmd --someflag 'Some other arguments']

nix-shell [path] [options] -- [args...]
nix-shell -p packages... [options] -- [args...]
nix-shell --run command

-p packages...
    Enters a shell with the specified Nix packages available in the PATH and other environment variables. Useful for ad-hoc environments.

--run command
    Executes the specified command within the created shell environment and then exits. The shell is not interactive.

-A attribute
    Selects a specific derivation or package attribute from the Nix expression to build the shell environment from.

--pure
    Creates a purely isolated shell environment. Most environment variables from the calling shell are removed, ensuring reproducibility and reducing interference.

--arg name value
    Passes an argument name with a literal Nix value to the Nix expression. The value is parsed as a Nix expression.

--argstr name value
    Passes an argument name with a string value to the Nix expression. The value is treated as a literal string.

--keep NAME
    When used with --pure, preserves the specified environment variable NAME from the calling shell in the new environment.

--show-trace
    Shows a detailed evaluation trace for Nix expressions, useful for debugging errors during environment creation.

--option name value
    Sets a Nix configuration option to the specified value for the duration of the command execution.

nix-shell allows users to create reproducible and isolated development environments. It instantiates a Nix expression, making specified dependencies and tools available within a new shell session without permanently installing them globally. This is ideal for development, debugging, or running specific commands with precise dependencies. The shell environment is set up such that binaries are available in PATH, and other necessary environment variables are configured. By default, nix-shell looks for shell.nix or default.nix in the current directory, but a specific Nix expression or a list of packages can also be provided. It promotes "pure" environments, minimizing interference from the host system's existing software.

nix-shell aims for pure environments, but without --pure, it can inherit variables that might affect reproducibility. Relying on mutable inputs like NIX_PATH or external system configuration can lead to non-deterministic environments. Shells like zsh or fish might require specific configurations to properly source shell.nix scripts, as nix-shell defaults to bash for its shell startup. Users should be mindful of the shellHook and buildInputs within Nix expressions for proper environment setup.

Several environment variables can influence nix-shell's behavior:
NIX_PATH: Controls where Nix looks for imported Nix expressions. It's a colon-separated list of paths.
NIX_BUILD_SHELL: Specifies the shell to use for building (defaults to bash). Can be overridden.
NIX_SHELL_PRESERVE_PROMPT: If set, prevents nix-shell from modifying the shell prompt upon entry.

To enter a shell with git and htop available:
nix-shell -p git htop

To build a shell from shell.nix and run a command:
nix-shell --run 'npm install && npm start'

To get a pure shell for a specific attribute from a Nix expression:
nix-shell -A myProject.devShell --pure

nix-shell emerged as a fundamental component of the Nix package manager, evolving alongside NixOS and its declarative approach to system configuration and development. Its design is rooted in the Nix philosophy of reproducible builds and isolated environments, providing a practical way for developers to quickly set up projects with precise dependencies without traditional package installation. While no specific standalone history for nix-shell exists, its development has mirrored the maturation of the Nix ecosystem, becoming indispensable for creating reliable and portable development workflows.

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