nix3-flake

Create a new flake (just the flake.nix file) from the default template, in the current directory

$ nix flake init

$ nix flake update

$ nix flake lock --update-input [input]

$ nix flake show [github:owner/repo]

$ nix flake --help

nix flake subcommand [options] [arguments]

Common subcommands:
  nix flake build [flake-reference]#
  nix flake run [flake-reference]# [-- app-args]
  nix flake update [flake-reference]
  nix flake init [--template ]
  nix flake show [flake-reference]

--show-trace
    Display stack traces on error for debugging Nix expressions.

--json
    Produce machine-readable JSON output where applicable.

--override-input
    Override a specific flake input with a different flake reference or path.

--refresh
    Refresh all flake inputs before performing the operation, re-fetching their latest versions.

--flake
    Specify the flake to operate on. Defaults to the flake in the current directory if not provided.

--option
    Set a Nix configuration option for the current command invocation.

The nix flake command group provides the primary interface for interacting with Nix flakes. Flakes are an experimental feature in Nix 3 that aim to improve reproducibility, composability, and usability of Nix projects. A flake is essentially a directory containing a flake.nix file and optionally a flake.lock file. The flake.nix defines the project's inputs (dependencies) and outputs (like packages, applications, or NixOS modules). The flake.lock file ensures bit-for-bit reproducibility by pinning all inputs to specific revisions and cryptographic hashes.

Using flakes, developers can define self-contained, versioned Nix projects that are easier to share, build, and integrate with other flakes. This paradigm shift helps manage complex dependencies, provides a more predictable build environment, and facilitates collaboration. The nix flake subcommands allow for operations such as building, running, updating, evaluating, and creating flake-based projects.

Flakes are still an experimental feature in Nix. This means their behavior, API, and underlying implementation may change in future Nix versions. To enable flake functionality, you must add experimental-features = nix-command flakes to your Nix configuration file (nix.conf). While offering significant benefits in reproducibility and dependency management, flakes introduce a new paradigm that can be initially complex for users familiar only with traditional Nix expressions.

A flake-reference is a string that specifies the location of a flake. It can be a local path (e.g., . for the current directory, ../my-flake), a Git repository URL (e.g., github:NixOS/nixpkgs, git+https://example.com/repo), or a URL to a tarball (e.g., https://example.com/archive.tar.gz). It allows specifying a specific branch, tag, or commit hash for precise versioning.

The flake.nix file is the core of a flake, defining its inputs (dependencies) and outputs (what the flake provides, like packages, applications, or NixOS modules). The flake.lock file, which is automatically generated and updated, pins all direct and transitive inputs to specific cryptographic hashes and Git revisions. This locking mechanism is crucial for guaranteeing bit-for-bit reproducibility of builds, ensuring that a flake will build the same way every time, regardless of when or where it's built.

The concept of Nix flakes was introduced as an experimental feature in Nix 2.4, primarily to address limitations in previous Nix workflows, such as ensuring strict reproducibility, standardizing project inputs and outputs, and improving the discoverability of Nix-based projects. Prior to flakes, managing transitive dependencies and ensuring exact build environments across different machines could be challenging. Flakes provide a more robust and opinionated structure, similar to package-lock.json or Gemfile.lock in other ecosystems, aiming to lock down all dependencies to specific revisions. This development marks a significant step towards making Nix more accessible, predictable, and composable for complex software projects.

nix(1), git(1)