nix-shell
1
Nix

# nix-shell

start an interactive shell based on a Nix expression

        nix-shell
        --arg name value
        --argstr name value

            --attr
            -A

          attrPath

        --command cmd
        --run cmd
        --exclude regexp
        --pure
        --keep name

              --packages
              -p

            packages

          path

## Description

The command `nix-shell` will build the dependencies of the specified derivation, but not the derivation itself. It will then start an interactive shell in which all environment variables defined by the derivation path have been set to their corresponding values, and the script `$stdenv/setup` has been sourced. This is useful for reproducing the environment of a derivation for development.

If path is not given, `nix-shell` defaults to `shell.nix` if it exists, and `default.nix` otherwise.

If path starts with `http://` or `https://`, it is interpreted as the URL of a tarball that will be downloaded and unpacked to a temporary location. The tarball must include a single top-level directory containing at least a file named `default.nix`.

If the derivation defines the variable `shellHook`, it will be evaluated after `$stdenv/setup` has been sourced. Since this hook is not executed by regular Nix builds, it allows you to perform initialisation specific to `nix-shell`. For example, the derivation attribute

    shellHook =
      ''
        echo "Hello shell"
      '';

will cause `nix-shell` to print `Hello shell`.

## Options

All options not listed here are passed to `nix-store --realise`, except for `--arg` and `--attr` / `-A` which are passed to `nix-instantiate`. See also .

`--command` cmd

  In the environment of the derivation, run the shell command cmd. This command is executed in an interactive shell. (Use `--run` to use a non-interactive shell instead.) However, a call to `exit` is implicitly added to the command, so the shell will exit after running the command. To prevent this, add `return` at the end; e.g. `--command "echo Hello; return"` will print `Hello` and then drop you into the interactive shell. This can be useful for doing any additional initialisation.

`--run` cmd

  Like `--command`, but executes the command in a non-interactive shell. This means (among other things) that if you hit Ctrl-C while the command is running, the shell exits.

`--exclude` regexp

  Do not build any dependencies whose store path matches the regular expression regexp. This option may be specified multiple times.

`--pure`

  If this flag is specified, the environment is almost entirely cleared before the interactive shell is started, so you get an environment that more closely corresponds to the “real” Nix build. A few variables, in particular `HOME`, `USER` and `DISPLAY`, are retained. Note that `~/.bashrc` and (depending on your Bash installation) `/etc/bashrc` are still sourced, so any variables set there will affect the interactive shell.

`--packages` / `-p` packages…

  Set up an environment in which the specified packages are present. The command line arguments are interpreted as attribute names inside the Nix Packages collection. Thus, `nix-shell -p libjpeg openjdk` will start a shell in which the packages denoted by the attribute names `libjpeg` and `openjdk` are present.

`-i` interpreter

  The chained script interpreter to be invoked by `nix-shell`. Only applicable in `#!`-scripts (described below).

`--keep` name

  When a `--pure` shell is started, keep the listed environment variables.

The following common options are supported:

## Environment variables

`NIX_BUILD_SHELL`

  Shell used to start the interactive environment. Defaults to the `bash` found in `PATH`.

## Examples

To build the dependencies of the package Pan, and start an interactive shell in which to build it:

    $ nix-shell '<nixpkgs>' -A pan
    [nix-shell]$ unpackPhase
    [nix-shell]$ cd pan-*
    [nix-shell]$ configurePhase
    [nix-shell]$ buildPhase
    [nix-shell]$ ./pan/gui/pan

To clear the environment first, and do some additional automatic initialisation of the interactive shell:

    $ nix-shell '<nixpkgs>' -A pan --pure \
        --command 'export NIX_DEBUG=1; export NIX_CORES=8; return'

Nix expressions can also be given on the command line. For instance, the following starts a shell containing the packages `sqlite` and `libX11`:

    $ nix-shell -E 'with import <nixpkgs> { }; runCommand "dummy" { buildInputs = [ sqlite xorg.libX11 ]; } ""'

A shorter way to do the same is:

    $ nix-shell -p sqlite xorg.libX11
    [nix-shell]$ echo $NIX_LDFLAGS
    … -L/nix/store/j1zg5v…-sqlite-3.8.0.2/lib -L/nix/store/0gmcz9…-libX11-1.6.1/lib …

The `-p` flag looks up Nixpkgs in the Nix search path. You can override it by passing `-I` or setting `NIX_PATH`. For example, the following gives you a shell containing the Pan package from a specific revision of Nixpkgs:

    $ nix-shell -p pan -I nixpkgs=https://github.com/NixOS/nixpkgs-channels/archive/8a3eea054838b55aca962c3fbde9c83c102b8bf2.tar.gz

    [nix-shell:~]$ pan --version
    Pan 0.139

## Use as a `#!`-interpreter

You can use `nix-shell` as a script interpreter to allow scripts written in arbitrary languages to obtain their own dependencies via Nix. This is done by starting the script with the following lines:

    #! /usr/bin/env nix-shell
    #! nix-shell -i real-interpreter -p packages

where real-interpreter is the “real” script interpreter that will be invoked by `nix-shell` after it has obtained the dependencies and initialised the environment, and packages are the attribute names of the dependencies in Nixpkgs.

The lines starting with `#! nix-shell` specify `nix-shell` options (see above). Note that you cannot write `#! /usr/bin/env nix-shell -i ...` because many operating systems only allow one argument in `#!` lines.

For example, here is a Python script that depends on Python and the `prettytable` package:

    #! /usr/bin/env nix-shell
    #! nix-shell -i python -p python pythonPackages.prettytable

    import prettytable

    # Print a simple table.
    t = prettytable.PrettyTable(["N", "N^2"])
    for n in range(1, 10): t.add_row([n, n * n])
    print t

Similarly, the following is a Perl script that specifies that it requires Perl and the `HTML::TokeParser::Simple` and `LWP` packages:

    #! /usr/bin/env nix-shell
    #! nix-shell -i perl -p perl perlPackages.HTMLTokeParserSimple perlPackages.LWP

    use HTML::TokeParser::Simple;

    # Fetch nixos.org and print all hrefs.
    my $p = HTML::TokeParser::Simple->new(url => 'http://nixos.org/');

    while (my $token = $p->get_tag("a")) {
        my $href = $token->get_attr("href");
        print "$href\n" if $href;
    }

Sometimes you need to pass a simple Nix expression to customize a package like Terraform:

    #! /usr/bin/env nix-shell
    #! nix-shell -i bash -p "terraform.withPlugins (plugins: [ plugins.openstack ])"

    terraform apply

You must use double quotes (`"`) when passing a simple Nix expression in a nix-shell shebang.

Finally, using the merging of multiple nix-shell shebangs the following Haskell script uses a specific branch of Nixpkgs/NixOS (the 18.03 stable branch):

    #! /usr/bin/env nix-shell
    #! nix-shell -i runghc -p "haskellPackages.ghcWithPackages (ps: [ps.HTTP ps.tagsoup])"
    #! nix-shell -I nixpkgs=https://github.com/NixOS/nixpkgs-channels/archive/nixos-18.03.tar.gz

    import Network.HTTP
    import Text.HTML.TagSoup

    -- Fetch nixos.org and print all hrefs.
    main = do
      resp <- Network.HTTP.simpleHTTP (getRequest "http://nixos.org/")
      body <- getResponseBody resp
      let tags = filter (isTagOpenName "a") $ parseTags body
      let tags' = map (fromAttrib "href") tags
      mapM_ putStrLn $ filter (/= "") tags'

If you want to be even more precise, you can specify a specific revision of Nixpkgs:

    #! nix-shell -I nixpkgs=https://github.com/NixOS/nixpkgs-channels/archive/0672315759b3e15e2121365f067c1c8c56bb4722.tar.gz

The examples above all used `-p` to get dependencies from Nixpkgs. You can also use a Nix expression to build your own dependencies. For example, the Python example could have been written as:

    #! /usr/bin/env nix-shell
    #! nix-shell deps.nix -i python

where the file `deps.nix` in the same directory as the `#!`-script contains:

    with import <nixpkgs> {};

    runCommand "dummy" { buildInputs = [ python pythonPackages.prettytable ]; } ""

## Environment variables