Manpages - nix3-flake.1

Example:

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

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

Example:

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";
};

Following RFC 3986, characters outside of the allowed range (i.e. neither reserved characters nor unreserved characters) must be percent-encoded.

Here are some examples of flake references in their URL-like representation:

• nixpkgs: The nixpkgs entry in the flake registry.
• nixpkgs/a3a3dda3bacf61e8a39258a0ed9c924eeca8e293: The nixpkgs entry in the flake registry, with its Git revision overridden to a specific value.
• github:NixOS/nixpkgs: The master branch of the NixOS/nixpkgs repository on GitHub.
• github:NixOS/nixpkgs/nixos-20.09: The nixos-20.09 branch of the nixpkgs repository.
• github:NixOS/nixpkgs/a3a3dda3bacf61e8a39258a0ed9c924eeca8e293: A specific revision of the nixpkgs repository.
• github:edolstra/nix-warez?dir=blender: A flake in a subdirectory of a GitHub repository.
• git+https://github.com/NixOS/patchelf: A Git repository.
• git+https://github.com/NixOS/patchelf?ref=master: A specific branch of a Git repository.
• git+https://github.com/NixOS/patchelf?ref=master&rev=f34751b88bd07d7f44f5cd3200fb4122bf916c7e: A specific branch and revision of a Git repository.
• https://github.com/NixOS/patchelf/archive/master.tar.gz: A tarball flake.

Flakes corresponding to a local path can also be referred to by a direct path reference, either /absolute/path/to/the/flake or=./relative/path/to/the/flake=. Note that the leading ./ is mandatory for relative paths. If it is omitted, the path will be interpreted as URL-like syntax, which will cause error messages like this:

error: cannot find flake 'flake:relative/path/to/the/flake' in the flake registries

The semantic of such a path is as follows:

• If the directory is part of a Git repository, then the input will be treated as a git+file: URL, otherwise it will be treated as a path: url;

• If the directory doesn't contain a flake.nix file, then Nix will search for such a file upwards in the file system hierarchy until it finds any of:

  1. The Git repository root, or
  2. The filesystem root (/), or
  3. A folder on a different mount point.

Contrary to URL-like references, path-like flake references can contain arbitrary unicode characters (except # and ?).

• .: The flake to which the current directory belongs to.
• /home/alice/src/patchelf: A flake in some other directory.
• ./../sub directory/with Ûñî©ôδ€: A flake in another relative directory that has Unicode characters in its name.

The following generic flake reference attributes are supported:

• dir: The subdirectory of the flake in which flake.nix is located. This parameter enables having multiple flakes in a repository or tarball. The default is the root directory of the flake.
• narHash: The hash of the Nix Archive (NAR) serialisation (in SRI format) of the contents of the flake. This is useful for flake types such as tarballs that lack a unique content identifier such as a Git commit hash.

In addition, the following attributes are common to several flake reference types:

• rev: A Git or Mercurial commit hash.
• ref: A Git or Mercurial branch or tag name.

Finally, some attribute are typically not specified by the user, but can occur in locked flake references and are available to Nix code:

• revCount: The number of ancestors of the commit rev.
• lastModified: The timestamp (in seconds since the Unix epoch) of the last modification of this version of the flake. For Git/Mercurial flakes, this is the commit time of commit rev, while for tarball flakes, it's the most recent timestamp of any file inside the tarball.

Currently the type attribute can be one of the following:

• indirect: The default. Indirection through the flake registry. These have the form

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

These perform a lookup of <flake-id> in the flake registry. For example, nixpkgs and nixpkgs/release-20.09 are indirect flake references. The specified rev and/or ref are merged with the entry in the registry; see nix registry for details.

For example, these are valid indirect flake references:

• nixpkgs
• nixpkgs/nixos-unstable
• nixpkgs/a3a3dda3bacf61e8a39258a0ed9c924eeca8e293
• nixpkgs/nixos-unstable/a3a3dda3bacf61e8a39258a0ed9c924eeca8e293
• sub/dir (if a flake named sub is in the registry)

• path: arbitrary local directories. The required attribute path specifies the path of the flake. The URL form is

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

where path is an absolute path to a directory in the file system containing a file named flake.nix.

If the flake at path is not inside a git repository, the path: prefix is implied and can be omitted.

path generally must be an absolute path. However, on the command line, it can be a relative path (e.g. . or ./foo) which is interpreted as relative to the current directory. In this case, it must start with . to avoid ambiguity with registry lookups (e.g. nixpkgs is a registry lookup; ./nixpkgs is a relative path).

For example, these are valid path flake references:

• path:/home/user/sub/dir
• /home/user/sub/dir (if dir/flake.nix is not in a git repository)
• ./sub/dir (when used on the command line and dir/flake.nix is not in a git repository)

• git: Git repositories. The location of the repository is specified by the attribute url. They have the URL form

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

If path starts with / (or ./ when used as an argument on the command line) and is a local path to a git repository, the leading git: or +file prefixes are implied and can be omitted.

The ref attribute defaults to resolving the HEAD reference.

The rev attribute must denote a commit that exists in the branch or tag specified by the ref attribute, since Nix doesn't do a full clone of the remote repository by default (and the Git protocol doesn't allow fetching a rev without a known ref). The default is the commit currently pointed to by ref.

When git+file is used without specifying ref or rev, files are fetched directly from the local path as long as they have been added to the Git repository. If there are uncommitted changes, the reference is treated as dirty and a warning is printed.

For example, the following are valid Git flake references:

• git:/home/user/sub/dir
• /home/user/sub/dir (if dir/flake.nix is in a git repository)
• ./sub/dir (when used on the command line and dir/flake.nix is in a git repository)
• git+https://example.org/my/repo
• git+https://example.org/my/repo?dir=flake1
• git+ssh://[email protected]/NixOS/nix?ref=v1.2.3
• git://github.com/edolstra/dwarffs?ref=unstable&rev=e486d8d40e626a20e06d792db8cc5ac5aba9a5b4
• git+file:///home/my-user/some-repo/some-repo

• mercurial: Mercurial repositories. The URL form is similar to the git type, except that the URL schema must be one of hg+http, hg+https, hg+ssh or hg+file.
• tarball: Tarballs. The location of the tarball is specified by the attribute url. In URL form, the schema must be tarball+http://, tarball+https:// or tarball+file://. If the extension corresponds to a known archive format (.zip, .tar, .tgz, .tar.gz, .tar.xz, .tar.bz2 or .tar.zst), then the tarball+ can be dropped. This can also be used to set the location of gitea/forgejo branches. See here
• file: Plain files or directory tarballs, either over http(s) or from the local disk. In URL form, the schema must be file+http://, file+https:// or file+file://. If the extension doesn't correspond to a known archive format (as defined by the tarball fetcher), then the file+ prefix can be dropped.

• github: A more efficient way to fetch repositories from GitHub. The following attributes are required:

  • owner: The owner of the repository.
  • repo: The name of the repository.

  These are downloaded as tarball archives, rather than through Git. This is often much faster and uses less disk space since it doesn't require fetching the entire history of the repository. On the other hand, it doesn't allow incremental fetching (but full downloads are often faster than incremental fetches!).

  The URL syntax for github flakes is:

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

<rev-or-ref> specifies the name of a branch or tag (ref), or a commit hash (rev). Note that unlike Git, GitHub allows fetching by commit hash without specifying a branch or tag.

You can also specify host as a parameter, to point to a custom GitHub Enterprise server.

Some examples:

• github:edolstra/dwarffs
• github:edolstra/dwarffs/unstable
• github:edolstra/dwarffs/d3f2baba8f425779026c6ec04021b2e927f61e31
• github:internal/project?host=company-github.example.org

• gitlab: Similar to github, is a more efficient way to fetch GitLab repositories. The following attributes are required:

  • owner: The owner of the repository.
  • repo: The name of the repository.

  Like github, these are downloaded as tarball archives.

  The URL syntax for gitlab flakes is:

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

  <rev-or-ref> works the same as github. Either a branch or tag name (ref), or a commit hash (rev) can be specified.

  Since GitLab allows for self-hosting, you can specify host as a parameter, to point to any instances other than gitlab.com.

  Some examples:

  • gitlab:veloren/veloren
  • gitlab:veloren/veloren/master
  • gitlab:veloren/veloren/80a4d7f13492d916e47d6195be23acae8001985a
  • gitlab:openldap/openldap?host=git.openldap.org

  When accessing a project in a (nested) subgroup, make sure to URL-encode any slashes, i.e. replace / with %2F:

  • gitlab:veloren%2Fdev/rfcs

• sourcehut: Similar to github, is a more efficient way to fetch SourceHut repositories. The following attributes are required:

  • owner: The owner of the repository (including leading ~).
  • repo: The name of the repository.

  Like github, these are downloaded as tarball archives.

  The URL syntax for sourcehut flakes is:

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

  <rev-or-ref> works the same as github. Either a branch or tag name (ref), or a commit hash (rev) can be specified.

  Since SourceHut allows for self-hosting, you can specify host as a parameter, to point to any instances other than git.sr.ht.

  Currently, ref name resolution only works for Git repositories. You can refer to Mercurial repositories by simply changing host to hg.sr.ht (or any other Mercurial instance). With the caveat that you must explicitly specify a commit hash (rev).

  Some examples:

  • sourcehut:~misterio/nix-colors
  • sourcehut:~misterio/nix-colors/main
  • sourcehut:~misterio/nix-colors?host=git.example.org
  • sourcehut:~misterio/nix-colors/182b4b8709b8ffe4e9774a4c5d6877bf6bb9a21c
  • sourcehut:~misterio/nix-colors/21c1a380a6915d890d408e9f22203436a35bb2de?host=hg.sr.ht

The attribute inputs specifies the dependencies of a flake, as an attrset mapping input names to flake references. For example, the following specifies a dependency on the nixpkgs and import-cargo repositories:

# 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";
};

Alternatively, you can use the URL-like syntax:

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

Each input is fetched, evaluated and passed to the outputs function as a set of attributes with the same name as the corresponding input. The special input named self refers to the outputs and source tree of this flake. Thus, a typical outputs function looks like this:

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

It is also possible to omit an input entirely and only list it as expected function argument to outputs. Thus,

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

without an inputs.nixpkgs attribute is equivalent to

inputs.nixpkgs = {
  type = "indirect";
  id = "nixpkgs";
};

Repositories that don't contain a flake.nix can also be used as inputs, by setting the input's flake attribute to false:

inputs.grcov = {
  type = "github";
  owner = "mozilla";
  repo = "grcov";
  flake = false;
};

outputs = { self, nixpkgs, grcov }: {
  packages.x86_64-linux.grcov = stdenv.mkDerivation {
    src = grcov;
    ...
  };
};

Transitive inputs can be overridden from a flake.nix file. For example, the following overrides the nixpkgs input of the nixops input:

inputs.nixops.inputs.nixpkgs = {
  type = "github";
  owner = "my-org";
  repo = "nixpkgs";
};

It is also possible to “inherit” an input from another input. This is useful to minimize flake dependencies. For example, the following sets the nixpkgs input of the top-level flake to be equal to the nixpkgs input of the dwarffs input of the top-level flake:

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

The value of the follows attribute is a /-separated sequence of input names denoting the path of inputs to be followed from the root flake.

Overrides and follows can be combined, e.g.

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

sets the nixpkgs input of nixops to be the same as the nixpkgs input of dwarffs. It is worth noting, however, that it is generally not useful to eliminate transitive nixpkgs flake inputs in this way. Most flakes provide their functionality through Nixpkgs overlays or NixOS modules, which are composed into the top-level flake's nixpkgs input; so their own nixpkgs input is usually irrelevant.

• --debug Set the logging verbosity level to ‘debug'.
• --log-format format Set the format of log output; one of raw, internal-json, bar or bar-with-logs.
• --print-build-logs / -L Print full build logs on standard error.
• --quiet Decrease the logging verbosity level.
• --verbose / -v Increase the logging verbosity level.

• --help Show usage information.
• --offline Disable substituters and consider all previously downloaded files up-to-date.
• --option name value Set the Nix configuration setting name to value (overriding nix.conf).
• --refresh Consider all previously downloaded files out-of-date.
• --version Show version information. Note See man nix.conf for overriding configuration settings with command line flags.