<refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude" xml:id="sec-nix-shell"> <refmeta> <refentrytitle>nix-shell</refentrytitle> <manvolnum>1</manvolnum> <refmiscinfo class="source">Nix</refmiscinfo> <refmiscinfo class="version"><xi:include href="version.txt" parse="text"/></refmiscinfo> </refmeta> <refnamediv> <refname>nix-shell</refname> <refpurpose>start an interactive shell based on a Nix expression</refpurpose> </refnamediv> <refsynopsisdiv> <cmdsynopsis> <command>nix-shell</command> <arg><option>--arg</option> <replaceable>name</replaceable> <replaceable>value</replaceable></arg> <arg><option>--argstr</option> <replaceable>name</replaceable> <replaceable>value</replaceable></arg> <arg> <group choice='req'> <arg choice='plain'><option>--attr</option></arg> <arg choice='plain'><option>-A</option></arg> </group> <replaceable>attrPath</replaceable> </arg> <arg><option>--command</option> <replaceable>cmd</replaceable></arg> <arg><option>--exclude</option> <replaceable>regexp</replaceable></arg> <arg><option>--pure</option></arg> <group choice='req'> <group choice='plain'> <group> <arg choice='plain'><option>--packages</option></arg> <arg choice='plain'><option>-p</option></arg> </group> <replaceable>packages</replaceable> </group> <arg><replaceable>path</replaceable></arg> </group> </cmdsynopsis> </refsynopsisdiv> <refsection><title>Description</title> <para>The command <command>nix-shell</command> 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 <replaceable>path</replaceable> have been set to their corresponding values, and the script <literal>$stdenv/setup</literal> has been sourced. This is useful for reproducing the environment of a derivation for development.</para> <para>If <replaceable>path</replaceable> is not given, <command>nix-shell</command> defaults to <filename>shell.nix</filename> if it exists, and <filename>default.nix</filename> otherwise.</para> <para>If the derivation defines the variable <varname>shellHook</varname>, it will be evaluated after <literal>$stdenv/setup</literal> has been sourced. Since this hook is not executed by regular Nix builds, it allows you to perform initialisation specific to <command>nix-shell</command>. For example, the derivation attribute <programlisting> shellHook = '' echo "Hello shell" ''; </programlisting> will cause <command>nix-shell</command> to print <literal>Hello shell</literal>.</para> </refsection> <refsection><title>Options</title> <para>All options not listed here are passed to <command>nix-store --realise</command>, except for <option>--arg</option> and <option>--attr</option> / <option>-A</option> which are passed to <command>nix-instantiate</command>. <phrase condition="manual">See also <xref linkend="sec-common-options" />.</phrase></para> <variablelist> <varlistentry><term><option>--command</option> <replaceable>cmd</replaceable></term> <listitem><para>In the environment of the derivation, run the shell command <replaceable>cmd</replaceable> instead of starting an interactive shell. However, if you end the shell command with <literal>return</literal>, you still get an interactive shell. This can be useful for doing any additional initialisation.</para></listitem> </varlistentry> <varlistentry><term><option>--exclude</option> <replaceable>regexp</replaceable></term> <listitem><para>Do not build any dependencies whose store path matches the regular expression <replaceable>regexp</replaceable>. This option may be specified multiple times.</para></listitem> </varlistentry> <varlistentry><term><option>--pure</option></term> <listitem><para>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 <envar>HOME</envar>, <envar>USER</envar> and <envar>DISPLAY</envar>, are retained. Note that <filename>~/.bashrc</filename> and (depending on your Bash installation) <filename>/etc/bashrc</filename> are still sourced, so any variables set there will affect the interactive shell.</para></listitem> </varlistentry> <varlistentry><term><option>--packages</option> / <option>-p</option></term> <listitem><para>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, <literal>nix-shell -p libjpeg openjdk</literal> will start a shell in which the packages denoted by the attribute names <varname>libjpeg</varname> and <varname>openjdk</varname> are present.</para></listitem> </varlistentry> </variablelist> <para>The following common options are supported:</para> <variablelist condition="manpage"> <xi:include href="opt-common.xml#xmlns(db=http://docbook.org/ns/docbook)xpointer(//db:variablelist[@xml:id='opt-common']/*)" /> </variablelist> </refsection> <refsection><title>Examples</title> <para>To build the dependencies of the package Pan, and start an interactive shell in which to build it: <screen> $ nix-shell '<nixpkgs>' -A pan [nix-shell]$ unpackPhase [nix-shell]$ cd pan-* [nix-shell]$ configurePhase [nix-shell]$ buildPhase [nix-shell]$ ./pan/gui/pan </screen> To clear the environment first, and do some additional automatic initialisation of the interactive shell: <screen> $ nix-shell '<nixpkgs>' -A pan --pure \ --command 'export NIX_DEBUG=1; export NIX_CORES=8; return' </screen> Nix expressions can also be given on the command line. For instance, the following starts a shell containing the packages <literal>sqlite</literal> and <literal>libX11</literal>: <screen> $ nix-shell -E 'with import <nixpkgs> { }; runCommand "dummy" { buildInputs = [ sqlite xorg.libX11 ]; } ""' </screen> A shorter way to do the same is: <screen> $ 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 … </screen> </para> </refsection> <refsection condition="manpage"><title>Environment variables</title> <variablelist> <xi:include href="env-common.xml#xmlns(db=http://docbook.org/ns/docbook)xpointer(//db:variablelist[@xml:id='env-common']/*)" /> </variablelist> </refsection> </refentry>