Skip to content

Flake Refs

Flakes do not have to reside on disk - you can use flakes published in git repositories too! This makes it possible to deliver package scripts, development environments and more directly from github repositories. This is somewhat akin to having a custom homebrew tap or debian package mirror.

  • .
    • the flake in the local directory
  • github:nix4noobs/first-flake
    • flake in repo first-flake in the github organization nix4noobs.
    • github:<user|organization>/<repo>
  • git+https://github.com/nix4noobs/first-flake
    • same flake as above - but this approach works non-GH repos too
  • github:nix4noobs/first-flake/master
    • Use the master branch of the first-flake repo owned by nix4noobs
  • github:nix4noobs/first-flake/6a7b8f9f009e3185c5e5ffb31d9ec9383ab97e4d
    • Use the specified commit
  • github:nix4noobs/first-flake?dir=nix
    • Use flake in nix dir of the repo first-flake
    • (Note: this directory does not exist in the actual repository, this is just a example)

Note

When first referencing a remote flake, nix will fetch it and place it in its store. If the flake later changes then you can add --refresh to your nix flake command to refresh the store's copy.

Not getting the latest from a flake can seem confusing to newcomers - so consider making "release" branches which don't change.

Warning

Flakes are typically shared as git repositories, though it is possible to serve a flake as a tarball over HTTP or a file path on a networked drive.

:imp:When a flake is part of a git repository, then only the changes which are staged are considered - remember to git add your changes, otherwise the flake command won't take your changes into account!

This can seem confusing, but nix strongly favors hermetic builds. By only considering what is staged, it makes it less likely that you push your repo only for a user to discover that some changes were not committed.

Referencing flake outputs

.. _sec-flake-ref-cli:

Listing available outputs

The nix flake show <flake-ref> provides a quick way to see what a flake provides. Below is an example listing the outputs of refs4noobs:

$ nix flake show github:nix4noobs/refs4noobs
github:nix4noobs/refs4noobs/274c89fc508b5e5c927b44bc92caa215b51f9b97
├───devShells
│   ├───aarch64-darwin
│   │   ├───blue: development environment 'blue'
│   │   └───yellow: development environment 'yellow'
│   ├───aarch64-linux
│   │   ├───blue: development environment 'blue'
│   │   └───yellow: development environment 'yellow'
│   └───x86_64-linux
│       ├───blue: development environment 'blue'
│       └───yellow: development environment 'yellow'
├───formatter
│   ├───aarch64-darwin: package 'nixfmt-0.5.0'
│   ├───aarch64-linux: package 'nixfmt-0.5.0'
│   └───x86_64-linux: package 'nixfmt-0.5.0'
├───packages
│   ├───aarch64-darwin
│   │   ├───cowsay: package 'cowsay-3.04'
│   │   └───hello: package 'hello-2.12.1'
│   ├───aarch64-linux
│   │   ├───cowsay: package 'cowsay-3.04'
│   │   └───hello: package 'hello-2.12.1'
│   └───x86_64-linux
│       ├───cowsay: package 'cowsay-3.04'
│       └───hello: package 'hello-2.12.1'
└───templates
    └───starter-22-11: template: starter for 22.11

In this flake we see the following outputs:

  • Two development shells, blue and yellow
  • A formatter entry (which tool to use when formatting .nix files using nix fmt)
  • two packages, hello and cowsay
  • a template, starter-22-11

Using outputs

Note

We have not yet introduced packages, development shells or templates. However, focus on the point that each command refers to the output by the form <flake-ref>#<output-name> and that the type of output used is implied by the command. So nix develop only looks as devShell outputs while nix build looks at package outputs.

Using a development shell

Dev shells are launched via nix develop, for example, to launch the dev shell named yellow in the refs4noobs flake whose outputs we listed above, run: nix develop github:nix4noobs/refs4noobs#yellow

Using a package

Packages are a collection of files, typically a software program, which can be installed into the Nix store. Packages can sometimes be "run" - that is, the principal program in a package, e.g. emacs in the emacs package, can be executed directly from your shell.

In refs4noobs, there are two packages defined in the flake, cowsay and hello, to run cowsay, try: nix run github:nix4noobs/refs4noobs#cowsay -- "hello".

Note that -- separates input args for nix with arguments intended for the program, this is a common convention for Linux CLI tools.

Using a template

In our hello world flake, we created our first flake from scratch using the nix flake init command. Flakes created this way are made from a very basic template which leaves a bit to be desired.

However, we can ask to create a flake from a template which we or others have made in advance. To create a new flake from the starter-22-11 template in refs4noobs, run the following command:

nix flake init --template github:nix4noobs/refs4noobs#starter-22-11