Agent Skills: Nix Flakes

Nix Flakes

Modern Nix project management with hermeticity and reproducibility through flake.lock.

Core Commands

Project Management

# Initialize a new flake in the current directory
nix flake init

# Create a new flake from template
nix flake new hello -t templates#hello

# Update flake.lock (updates all inputs)
nix flake update

# Update specific input only
nix flake update nixpkgs

# Lock without updating (create missing entries)
nix flake lock

# Check flake for syntax and common errors
nix flake check

# Show flake outputs
nix flake show

# Show flake metadata (inputs, revisions)
nix flake metadata path:.
nix flake info path:.  # Alias for metadata

# Prefetch flake and inputs into store
nix flake prefetch github:NixOS/nixpkgs
nix flake prefetch-inputs path:.

# Clone flake repository
nix flake clone nixpkgs --dest ./nixpkgs

Running and Building

Always prefix local flake paths with path: (e.g., path:.) to ensure Nix uses all files in the directory without requiring them to be staged in Git.

# Build the default package
nix build path:.

# Build a specific output
nix build path:.#packageName

# Run the default app
nix run path:.

# Run a specific app from a flake
nix run path:.#appName

# Run an app from a remote flake
nix run github:numtide/treefmt

Development Environments

In a headless environment, use nix develop with --command to run tasks within the environment.

# Run a command inside the devShell
nix develop path:. --command make build

# Check if current environment matches devShell
nix develop path:. --command env

Flake Structure (flake.nix)

A basic flake.nix pattern:

{
  description = "A basic flake";

  inputs = {
    nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable";
  };

  outputs = { self, nixpkgs }:
    let
      system = "x86_64-linux";
      pkgs = nixpkgs.legacyPackages.${system};
    in {
      packages.${system}.default = pkgs.hello;

      devShells.${system}.default = pkgs.mkShell {
        buildInputs = [ pkgs.git pkgs.vim ];
      };
    };
}

Best Practices

• Locking: Manage the flake.lock file to ensure reproducibility.
• Purity: Flakes are "pure" by default. They cannot access files outside the flake directory unless they are tracked (e.g. in the git tree if using git).
• Non-Interactive: When using nix develop, always use the --command flag to ensure scripts remain non-interactive.

Debugging Flakes

# Inspect inputs
nix flake metadata path:.

# Evaluate a specific output
nix eval path:.#packages.x86_64-linux.default.name

Related Skills

• nix: Run applications without installation and create development environments using Nix.
• nh: Manage NixOS and Home Manager operations with improved output using nh.

Related Tools

• search-nix-packages: Search for packages available in the NixOS package repository when working with flakes.
• search-nix-options: Find configuration options available in NixOS for flake configurations.
• search-home-manager-options: Find configuration options for Home Manager in flake setups.