Name

nix flake - manage Nix flakes

Synopsis

nix flake [option…] subcommand

where subcommand is one of the following:

• nix flake archive (./nix3-flake-archive.md) - copy a flake and all its inputs to a store

• nix flake check (./nix3-flake-check.md) - check whether the flake evaluates and run its tests

• nix flake clone (./nix3-flake-clone.md) - clone flake repository

• nix flake info (./nix3-flake-info.md) - show flake metadata

• nix flake init (./nix3-flake-init.md) - create a flake in the current directory from a template

• nix flake lock (./nix3-flake-lock.md) - create missing lock file entries

• nix flake metadata (./nix3-flake-metadata.md) - show flake metadata

• nix flake new (./nix3-flake-new.md) - create a flake in the specified directory from a template

• nix flake prefetch (./nix3-flake-prefetch.md) - download the source tree denoted by a flake reference into the Nix store

• nix flake show (./nix3-flake-show.md) - show the outputs provided by a flake

• nix flake update (./nix3-flake-update.md) - update flake lock file

Description

nix flake provides subcommands for creating, modifying and querying Nix flakes. Flakes are the unit for packaging Nix code in a reproducible and discoverable way. They can have dependencies on other flakes, making it possible to have multi-repository Nix projects.

A flake is a filesystem tree (typically fetched from a Git repository or a tarball) that contains a file named flake.nix in the root directory. flake.nix specifies some metadata about the flake such as dependencies (called inputs), as well as its outputs (the Nix values such as packages or NixOS modules provided by the flake).

Flake references

Flake references (flakerefs) are a way to specify the location of a flake. These have two different forms:

•

An attribute set representation, e.g.

{
type = "github";
owner = "NixOS";
repo = "nixpkgs";
}

The only required attribute is type. The supported types are listed below.

•

A URL-like syntax, e.g.

github:NixOS/nixpkgs

These are used on the command line as a more convenient alternative to the attribute set representation. For instance, in the command

# nix build github:NixOS/nixpkgs#hello

github:NixOS/nixpkgs is a flake reference (while hello is an output attribute). They are also allowed in the inputs attribute of a flake, e.g.

inputs.nixpkgs.url = github:NixOS/nixpkgs;

is equivalent to

inputs.nixpkgs = {
type = "github";
owner = "NixOS";
repo = "nixpkgs";
};

[path:]<path>(\?<params)?

git(+http|+https|+ssh|+git|+file|):(//<server>)?<path>(\?<params>)?

github:<owner>/<repo>(/<rev-or-ref>)?(\?<params>)?

[flake:]<flake-id>(/<rev-or-ref>(/rev)?)?

Flake format

As an example, here is a simple flake.nix that depends on the Nixpkgs flake and provides a single package (i.e. an installable derivation):

{


  description = "A flake for building Hello World";


  inputs.nixpkgs.url = github:NixOS/nixpkgs/nixos-20.03;


  outputs = { self, nixpkgs }: {


    packages.x86_64-linux.default =


      # Notice the reference to nixpkgs here.


      with import nixpkgs { system = "x86_64-linux"; };


      stdenv.mkDerivation {


        name = "hello";


        src = self;


        buildPhase = "gcc -o hello ./hello.c";


        installPhase = "mkdir -p $out/bin; install -t $out/bin hello";


      };


  };
}

The following attributes are supported in flake.nix:

• description: A short, one-line description of the flake.
• inputs: An attrset specifying the dependencies of the flake (described below).
• outputs: A function that, given an attribute set containing the outputs of each of the input flakes keyed by their identifier, yields the Nix values provided by this flake. Thus, in the example above, inputs.nixpkgs contains the result of the call to the outputs function of the nixpkgs flake.

In addition to the outputs of each input, each input in inputs also contains some metadata about the inputs. These are:

The value returned by the outputs function must be an attribute set. The attributes can have arbitrary values; however, various nix subcommands require specific attributes to have a specific value (e.g. packages.x86_64-linux must be an attribute set of derivations built for the x86_64-linux platform).

•

nixConfig: a set of nix.conf options to be set when evaluating any part of a flake. In the interests of security, only a small set of whitelisted options (currently bash-prompt, bash-prompt-suffix, and flake-registry) are allowed to be set without confirmation so long as accept-flake-config is not set in the global configuration.

# A GitHub repository.
inputs.import-cargo = {


  type = "github";


  owner = "edolstra";


  repo = "import-cargo";
};
# An indirection through the flake registry.
inputs.nixpkgs = {


  type = "indirect";


  id = "nixpkgs";
};

inputs.import-cargo.url = github:edolstra/import-cargo;
inputs.nixpkgs.url = "nixpkgs";

outputs = { self, nixpkgs, import-cargo }: {


  ... outputs ...
};

outputs = { self, nixpkgs }: ...;

inputs.nixpkgs = {


  type = "indirect";


  id = "nixpkgs";
};

inputs.grcov = {


  type = "github";


  owner = "mozilla";


  repo = "grcov";


  flake = false;
};
outputs = { self, nixpkgs, grcov }: {


  packages.x86_64-linux.grcov = stdenv.mkDerivation {


    src = grcov;


    ...


  };
};

inputs.nixops.inputs.nixpkgs = {


  type = "github";


  owner = "my-org";


  repo = "nixpkgs";
};

inputs.nixpkgs.follows = "dwarffs/nixpkgs";

inputs.nixops.inputs.nixpkgs.follows = "dwarffs/nixpkgs";

Lock files

Inputs specified in flake.nix are typically “unlocked” in the sense that they don’t specify an exact revision. To ensure reproducibility, Nix will automatically generate and use a lock file called flake.lock in the flake’s directory. The lock file contains a graph structure isomorphic to the graph of dependencies of the root flake. Each node in the graph (except the root node) maps the (usually) unlocked input specifications in flake.nix to locked input specifications. Each node also contains some metadata, such as the dependencies (outgoing edges) of the node.

For example, if flake.nix has the inputs in the example above, then the resulting lock file might be:

{


  "version": 7,


  "root": "n1",


  "nodes": {


    "n1": {


      "inputs": {


        "nixpkgs": "n2",


        "import-cargo": "n3",


        "grcov": "n4"


      }


    },


    "n2": {


      "inputs": {},


      "locked": {


        "owner": "edolstra",


        "repo": "nixpkgs",


        "rev": "7f8d4b088e2df7fdb6b513bc2d6941f1d422a013",


        "type": "github",


        "lastModified": 1580555482,


        "narHash": "sha256-OnpEWzNxF/AU4KlqBXM2s5PWvfI5/BS6xQrPvkF5tO8="


      },


      "original": {


        "id": "nixpkgs",


        "type": "indirect"


      }


    },


    "n3": {


      "inputs": {},


      "locked": {


        "owner": "edolstra",


        "repo": "import-cargo",


        "rev": "8abf7b3a8cbe1c8a885391f826357a74d382a422",


        "type": "github",


        "lastModified": 1567183309,


        "narHash": "sha256-wIXWOpX9rRjK5NDsL6WzuuBJl2R0kUCnlpZUrASykSc="


      },


      "original": {


        "owner": "edolstra",


        "repo": "import-cargo",


        "type": "github"


      }


    },


    "n4": {


      "inputs": {},


      "locked": {


        "owner": "mozilla",


        "repo": "grcov",


        "rev": "989a84bb29e95e392589c4e73c29189fd69a1d4e",


        "type": "github",


        "lastModified": 1580729070,


        "narHash": "sha256-235uMxYlHxJ5y92EXZWAYEsEb6mm+b069GAd+BOIOxI="


      },


      "original": {


        "owner": "mozilla",


        "repo": "grcov",


        "type": "github"


      },


      "flake": false


    }


  }
}

This graph has 4 nodes: the root flake, and its 3 dependencies. The nodes have arbitrary labels (e.g. n1). The label of the root node of the graph is specified by the root attribute. Nodes contain the following fields:

• inputs: The dependencies of this node, as a mapping from input names (e.g. nixpkgs) to node labels (e.g. n2).
• original: The original input specification from flake.lock, as a set of builtins.fetchTree arguments.
• locked: The locked input specification, as a set of builtins.fetchTree arguments. Thus, in the example above, when we build this flake, the input nixpkgs is mapped to revision 7f8d4b088e2df7fdb6b513bc2d6941f1d422a013 of the edolstra/nixpkgs repository on GitHub.

It also includes the attribute narHash, specifying the expected contents of the tree in the Nix store (as computed by nix hash-path), and may include input-type-specific attributes such as the lastModified or revCount. The main reason for these attributes is to allow flake inputs to be substituted from a binary cache: narHash allows the store path to be computed, while the other attributes are necessary because they provide information not stored in the store path.

•

flake: A Boolean denoting whether this is a flake or non-flake dependency. Corresponds to the flake attribute in the inputs attribute in flake.nix.

The original and locked attributes are omitted for the root node. This is because we cannot record the commit hash or content hash of the root flake, since modifying flake.lock will invalidate these.

The graph representation of lock files allows circular dependencies between flakes. For example, here are two flakes that reference each other:

{


  inputs.b = ... location of flake B ...;


  # Tell the 'b' flake not to fetch 'a' again, to ensure its 'a' is


  # *this* 'a'.


  inputs.b.inputs.a.follows = "";


  outputs = { self, b }: {


    foo = 123 + b.bar;


    xyzzy = 1000;


  };
}

and

{


  inputs.a = ... location of flake A ...;


  inputs.a.inputs.b.follows = "";


  outputs = { self, a }: {


    bar = 456 + a.xyzzy;


  };
}

Lock files transitively lock direct as well as indirect dependencies. That is, if a lock file exists and is up to date, Nix will not look at the lock files of dependencies. However, lock file generation itself does use the lock files of dependencies by default.