Name

       nix-instantiate - instantiate store derivations from Nix expressions

Synopsis

       nix-instantiate [--parse | --eval [--strict] [--json] [--xml] ] [--read-write-mode] [--arg
       name value] [{--attr| -A} attrPath] [--add-root path] [--expr | -E] files…

       nix-instantiate --find-file files…

Description

       The command nix-instantiate generates store derivations (../glossary.md) from (high-level)
       Nix  expressions.  It  evaluates  the  Nix expressions in each of files (which defaults to
       ./default.nix). Each top-level expression should evaluate  to  a  derivation,  a  list  of
       derivations,  or  a  set  of derivations. The paths of the resulting store derivations are
       printed on standard output.

       If files is the character -, then a Nix expression will be read from standard input.

Options

       • --add-root path
         See the corresponding option (nix-store.md) in nix-store.

       • --parse
         Just parse the input files, and print their abstract syntax trees on standard output  in
         ATerm format.

       • --eval
         Just  parse  and  evaluate  the  input files, and print the resulting values on standard
         output. No instantiation of store derivations takes place.

       • --find-file
         Look up the given files in Nix’s search path (as specified by the  NIX_PATH  environment
         variable).  If  found,  print  the  corresponding absolute paths on standard output. For
         instance, if NIX_PATH is nixpkgs=/home/alice/nixpkgs, then  nix-instantiate  --find-file
         nixpkgs/default.nix will print /home/alice/nixpkgs/default.nix.

       • --strict
         When used with --eval, recursively evaluate list elements and attributes. Normally, such
         sub-expressions are left unevaluated (since the Nix expression language is lazy).

                Warning

                This option can cause  non-termination,  because  lazy  data  structures  can  be
                infinitely large.

       • --json
         When  used  with  --eval,  print  the  resulting  value as an JSON representation of the
         abstract syntax tree rather than as an ATerm.

       • --xml
         When used with --eval, print the  resulting  value  as  an  XML  representation  of  the
         abstract  syntax  tree  rather than as an ATerm.  The schema is the same as that used by
         the toXML built-in (../expressions/builtins.md).

       • --read-write-mode
         When used with --eval, perform evaluation in read/write mode so  nix  language  features
         that  require  it  will  still work (at the cost of needing to do instantiation of every
         evaluated derivation). If this option is not enabled, there may be uninstantiated  store
         paths in the final output.

Examples

       Instantiating store derivations from a Nix expression, and building them using nix-store:

       $ nix-instantiate test.nix (instantiate)
       /nix/store/cigxbmvy6dzix98dxxh9b6shg7ar5bvs-perl-BerkeleyDB-0.26.drv

       $ nix-store -r $(nix-instantiate test.nix) (build)
       ...
       /nix/store/qhqk4n8ci095g3sdp93x7rgwyh9rdvgk-perl-BerkeleyDB-0.26 (output path)

       $ ls -l /nix/store/qhqk4n8ci095g3sdp93x7rgwyh9rdvgk-perl-BerkeleyDB-0.26
       dr-xr-xr-x    2 eelco    users        4096 1970-01-01 01:00 lib
       ...

       You can also give a Nix expression on the command line:

       $ nix-instantiate -E 'with import <nixpkgs> { }; hello'
       /nix/store/j8s4zyv75a724q38cb0r87rlczaiag4y-hello-2.8.drv

       This is equivalent to:

       $ nix-instantiate '<nixpkgs>' -A hello

       Parsing and evaluating Nix expressions:

       $ nix-instantiate --parse -E '1 + 2'
       1 + 2

       $ nix-instantiate --eval -E '1 + 2'
       3

       $ nix-instantiate --eval --xml -E '1 + 2'
       <?xml version='1.0' encoding='utf-8'?>
       <expr>
         <int value="3" />
       </expr>

       The difference between non-strict and strict evaluation:

       $ nix-instantiate --eval --xml -E 'rec { x = "foo"; y = x; }'
       ...
         <attr name="x">
           <string value="foo" />
         </attr>
         <attr name="y">
           <unevaluated />
         </attr>
       ...

       Note that y is left unevaluated (the XML representation doesn’t attempt to show non-normal
       forms).

       $ nix-instantiate --eval --xml --strict -E 'rec { x = "foo"; y = x; }'
       ...
         <attr name="x">
           <string value="foo" />
         </attr>
         <attr name="y">
           <string value="foo" />
         </attr>
       ...

                                                                               nix-instantiate(1)