nix-shell.2
Enter a reproducible build environment
TLDR
Start with nix expression in shell.nix or default.nix in the current directory
Run shell command in non-interactive shell and exit
Start with expression in default.nix in the current directory
Start with packages loaded from nixpkgs
Start with packages loaded from specific nixpkgs revision
Evaluate rest of file in specific interpreter, for use in #!-scripts (see
SYNOPSIS
nix-shell [options…] [path] [args…]
PARAMETERS
--pure
Purify environment by resetting vars and symlinking inputs
--impure
Allow impure builds (default)
--run CMD
Run single command instead of interactive shell
--command CMD
Run command in shell, then exit
-p pkgs
Build environment with listed packages
--packages pkgs
Synonym for -p
--expr EXPR
Use Nix expression directly
--attr ATTR
Select attribute from Nix expression
--flake REF
Use Nix flake reference
-i FILE
Set shellHook from file
--arg NAME VALUE
Pass argument to Nix function
--argstr NAME STRING
Pass string argument
--keep-going
Continue on build errors
--option VAR VALUE
Set Nix configuration option
--help
Display usage information
--version
Print version
DESCRIPTION
The nix-shell command starts an interactive shell in an environment constructed from a Nix expression. It allows developers to temporarily enter a shell with specific dependencies available without installing them system-wide.
Nix-shell evaluates the given Nix expression (defaulting to shell.nix or default.nix) to build a derivation providing a bash shell. Packages specified in the expression become available in the PATH.
Key features include --pure mode, which provides a clean environment by resetting environment variables and copying inputs into the store, ensuring reproducibility. Impure mode (default) inherits the parent shell's environment.
Common use cases: prototyping Haskell/Rust projects with -p for quick package lists, running one-off commands with --run, or debugging builds. It integrates with Nix flakes via --flake.
This enables declarative, reproducible development environments across machines, leveraging Nix's functional package management.
CAVEATS
Resource-intensive in pure mode due to input copying; flakes require Nix 2.4+; impure mode may leak non-reproducible state.
COMMON INVOCATION
nix-shell -p hello for quick env with 'hello'; nix-shell --pure for clean slate; nix-shell .#devShells.default with flakes.
Uses shell.nix: { pkgs ? import <nixpkgs> {} }: pkgs.mkShell { buildInputs = [ pkgs.hello ]; }
EXIT BEHAVIOR
Shell exits on Ctrl-D or exit; changes discarded unless impure or committed to store.
HISTORY
Developed as part of Nixpkgs by Eelco Dolstra (2003); nix-shell introduced ~2012 in Nix 1.0 for reproducible dev shells; evolved with flakes in Nix 2.4 (2021) for modern workflows.
