Nix Best Practices

by alleneubank2921eb8a685aNo license52 starsListed Oct 8, 2026Updated Oct 8, 2026Repository updated 3 months ago

Use when working with Nix flakes, overlays, shell.nix, or flake.nix files.

ArchivedInstructions onlySoftware Development DevOps & Cloud

AI-generated overview

Reference guidance for writing Nix flakes, overlays, dev shells and handling unfree packages.

What it does: Provides conventions and code patterns for Nix flake structure, input follows chaining, applying overlays, handling unfree packages, building binary overlay repositories, dev shells, direnv integration and common commands. It also lists troubleshooting steps for typical flake errors such as missing inputs, unfree package failures, duplicate nixpkgs downloads and hash mismatches. It is an instructions-only reference and produces no files or scripts.
When to use it: Use it when authoring or reviewing flake.nix, shell.nix or overlay definitions, or when diagnosing Nix flake errors. It suits developers who need established patterns for dev shells, overlays and unfree package configuration.
Requirements: No scripts or tooling are bundled; it is instructions only. Applying the guidance assumes a working Nix installation with flakes enabled, and network access for fetching flake inputs and binaries.

Nix Best Practices

Flake Structure

Standard flake.nix structure:

nix

{  description = "Project description";
  inputs = {    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";    flake-utils.url = "github:numtide/flake-utils";  };
  outputs = { self, nixpkgs, flake-utils }:    flake-utils.lib.eachDefaultSystem (system:      let        pkgs = import nixpkgs {          inherit system;        };      in {        devShells.default = pkgs.mkShell {          buildInputs = with pkgs; [            # packages here          ];        };      });}

{  description = "Project description";
  inputs = {    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";    flake-utils.url = "github:numtide/flake-utils";  };
  outputs = { self, nixpkgs, flake-utils }:    flake-utils.lib.eachDefaultSystem (system:      let        pkgs = import nixpkgs {          inherit system;        };      in {        devShells.default = pkgs.mkShell {          buildInputs = with pkgs; [            # packages here          ];        };      });}

Follows Pattern (Avoid Duplicate Nixpkgs)

When adding overlay inputs, use follows to share the parent nixpkgs and avoid downloading multiple versions:

nix

inputs = {  nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
  # Overlay follows parent nixpkgs  some-overlay.url = "github:owner/some-overlay";  some-overlay.inputs.nixpkgs.follows = "nixpkgs";
  # Chain follows through intermediate inputs  another-overlay.url = "github:owner/another-overlay";  another-overlay.inputs.nixpkgs.follows = "some-overlay";};

inputs = {  nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
  # Overlay follows parent nixpkgs  some-overlay.url = "github:owner/some-overlay";  some-overlay.inputs.nixpkgs.follows = "nixpkgs";
  # Chain follows through intermediate inputs  another-overlay.url = "github:owner/another-overlay";  another-overlay.inputs.nixpkgs.follows = "some-overlay";};

All inputs must be listed in outputs function even if not directly used:

Applying Overlays

Overlays modify or add packages to nixpkgs:

nix

let  pkgs = import nixpkgs {    inherit system;    overlays = [      overlay1.overlays.default      overlay2.overlays.default      # Inline overlay      (final: prev: {        myPackage = prev.myPackage.override { ... };      })    ];  };in

let  pkgs = import nixpkgs {    inherit system;    overlays = [      overlay1.overlays.default      overlay2.overlays.default      # Inline overlay      (final: prev: {        myPackage = prev.myPackage.override { ... };      })    ];  };in

Handling Unfree Packages

Option 1: nixpkgs-unfree (Recommended for Teams)

Use numtide/nixpkgs-unfree for EULA-licensed packages without requiring user config:

nix

inputs = {  nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";  nixpkgs-unfree.url = "github:numtide/nixpkgs-unfree/nixos-unstable";  nixpkgs-unfree.inputs.nixpkgs.follows = "nixpkgs";
  # Unfree overlay follows nixpkgs-unfree  proprietary-tool.url = "github:owner/proprietary-tool-overlay";  proprietary-tool.inputs.nixpkgs.follows = "nixpkgs-unfree";};

inputs = {  nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";  nixpkgs-unfree.url = "github:numtide/nixpkgs-unfree/nixos-unstable";  nixpkgs-unfree.inputs.nixpkgs.follows = "nixpkgs";
  # Unfree overlay follows nixpkgs-unfree  proprietary-tool.url = "github:owner/proprietary-tool-overlay";  proprietary-tool.inputs.nixpkgs.follows = "nixpkgs-unfree";};

This chains: proprietary-tool → nixpkgs-unfree → nixpkgs

Option 2: User Config

Users add to ~/.config/nixpkgs/config.nix:

Option 3: Specific Packages (Flake)

nix

let  pkgs = import nixpkgs {    inherit system;    config.allowUnfreePredicate = pkg: builtins.elem (lib.getName pkg) [      "specific-package"    ];  };in

let  pkgs = import nixpkgs {    inherit system;    config.allowUnfreePredicate = pkg: builtins.elem (lib.getName pkg) [      "specific-package"    ];  };in

Note: config.allowUnfree in flake.nix doesn't work with nix develop - use nixpkgs-unfree or user config.

Creating Binary Overlay Repos

When nixpkgs builds a community version lacking features (common with open-core tools), create an overlay that fetches official binaries.

Pattern (see 0xBigBoss/atlas-overlay, 0xBigBoss/bun-overlay)

nix

{  inputs = {    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";    flake-utils.url = "github:numtide/flake-utils";  };
  outputs = { self, nixpkgs, flake-utils }:    flake-utils.lib.eachDefaultSystem (system:      let        pkgs = nixpkgs.legacyPackages.${system};
        version = "1.0.0";
        # Platform-specific binaries        sources = {          "x86_64-linux" = {            url = "https://example.com/tool-linux-amd64-v${version}";            sha256 = "sha256-AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=";          };          "aarch64-linux" = {            url = "https://example.com/tool-linux-arm64-v${version}";            sha256 = "sha256-BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB=";          };          "x86_64-darwin" = {            url = "https://example.com/tool-darwin-amd64-v${version}";            sha256 = "sha256-CCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCC=";          };          "aarch64-darwin" = {            url = "https://example.com/tool-darwin-arm64-v${version}";            sha256 = "sha256-DDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD=";          };        };
        source = sources.${system} or (throw "Unsupported system: ${system}");
        toolPackage = pkgs.stdenv.mkDerivation {          pname = "tool";          inherit version;
          src = pkgs.fetchurl {            inherit (source) url sha256;          };
          sourceRoot = ".";          dontUnpack = true;
          installPhase = ''            mkdir -p $out/bin            cp $src $out/bin/tool            chmod +x $out/bin/tool          '';
          meta = with pkgs.lib; {            description = "Tool description";            homepage = "https://example.com";            license = licenses.unfree;  # or appropriate license            platforms = builtins.attrNames sources;          };        };      in {        packages.default = toolPackage;        packages.tool = toolPackage;
        overlays.default = final: prev: {          tool = toolPackage;        };      })    // {      overlays.default = final: prev: {        tool = self.packages.${prev.system}.tool;      };    };}

{  inputs = {    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";    flake-utils.url = "github:numtide/flake-utils";  };
  outputs = { self, nixpkgs, flake-utils }:    flake-utils.lib.eachDefaultSystem (system:      let        pkgs = nixpkgs.legacyPackages.${system};
        version = "1.0.0";
        # Platform-specific binaries        sources = {          "x86_64-linux" = {            url = "https://example.com/tool-linux-amd64-v${version}";            sha256 = "sha256-AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=";          };          "aarch64-linux" = {            url = "https://example.com/tool-linux-arm64-v${version}";            sha256 = "sha256-BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB=";          };          "x86_64-darwin" = {            url = "https://example.com/tool-darwin-amd64-v${version}";            sha256 = "sha256-CCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCC=";          };          "aarch64-darwin" = {            url = "https://example.com/tool-darwin-arm64-v${version}";            sha256 = "sha256-DDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD=";          };        };
        source = sources.${system} or (throw "Unsupported system: ${system}");
        toolPackage = pkgs.stdenv.mkDerivation {          pname = "tool";          inherit version;
          src = pkgs.fetchurl {            inherit (source) url sha256;          };
          sourceRoot = ".";          dontUnpack = true;
          installPhase = ''            mkdir -p $out/bin            cp $src $out/bin/tool            chmod +x $out/bin/tool          '';
          meta = with pkgs.lib; {            description = "Tool description";            homepage = "https://example.com";            license = licenses.unfree;  # or appropriate license            platforms = builtins.attrNames sources;          };        };      in {        packages.default = toolPackage;        packages.tool = toolPackage;
        overlays.default = final: prev: {          tool = toolPackage;        };      })    // {      overlays.default = final: prev: {        tool = self.packages.${prev.system}.tool;      };    };}

Getting SHA256 Hashes

bash

nix-prefetch-url https://example.com/tool-linux-amd64-v1.0.0# Returns hash in base32, convert to SRI format:nix hash to-sri --type sha256 <base32-hash>

nix-prefetch-url https://example.com/tool-linux-amd64-v1.0.0# Returns hash in base32, convert to SRI format:nix hash to-sri --type sha256 <base32-hash>

Or use SRI directly:

Dev Shell Patterns

Basic Shell

nix

devShells.default = pkgs.mkShell {  buildInputs = with pkgs; [    nodejs    python3  ];
  shellHook = ''    echo "Dev environment ready"  '';};

devShells.default = pkgs.mkShell {  buildInputs = with pkgs; [    nodejs    python3  ];
  shellHook = ''    echo "Dev environment ready"  '';};

With Environment Variables

nix

devShells.default = pkgs.mkShell {  buildInputs = with pkgs; [ postgresql ];
  # Set at shell entry  DATABASE_URL = "postgres://localhost/dev";
  # Or in shellHook for dynamic values  shellHook = ''    export PROJECT_ROOT="$(pwd)"  '';};

devShells.default = pkgs.mkShell {  buildInputs = with pkgs; [ postgresql ];
  # Set at shell entry  DATABASE_URL = "postgres://localhost/dev";
  # Or in shellHook for dynamic values  shellHook = ''    export PROJECT_ROOT="$(pwd)"  '';};

Native Dependencies (C Libraries)

nix

devShells.default = pkgs.mkShell {  buildInputs = with pkgs; [    openssl    postgresql  ];
  # Expose headers and libraries  shellHook = ''    export C_INCLUDE_PATH="${pkgs.openssl.dev}/include:$C_INCLUDE_PATH"    export LIBRARY_PATH="${pkgs.openssl.out}/lib:$LIBRARY_PATH"    export PKG_CONFIG_PATH="${pkgs.openssl.dev}/lib/pkgconfig:$PKG_CONFIG_PATH"  '';};

devShells.default = pkgs.mkShell {  buildInputs = with pkgs; [    openssl    postgresql  ];
  # Expose headers and libraries  shellHook = ''    export C_INCLUDE_PATH="${pkgs.openssl.dev}/include:$C_INCLUDE_PATH"    export LIBRARY_PATH="${pkgs.openssl.out}/lib:$LIBRARY_PATH"    export PKG_CONFIG_PATH="${pkgs.openssl.dev}/lib/pkgconfig:$PKG_CONFIG_PATH"  '';};

Direnv Integration

.envrc for flake projects:

For unfree packages without nixpkgs-unfree:

Common Commands

bash

# Update all inputsnix flake update
# Update specific inputnix flake update some-input
# Check flake validitynix flake check
# Show flake metadatanix flake metadata
# Enter dev shellnix develop
# Run command in dev shellnix develop -c <command>
# Build packagenix build .#packageName
# Run packagenix run .#packageName

# Update all inputsnix flake update
# Update specific inputnix flake update some-input
# Check flake validitynix flake check
# Show flake metadatanix flake metadata
# Enter dev shellnix develop
# Run command in dev shellnix develop -c <command>
# Build packagenix build .#packageName
# Run packagenix run .#packageName

Troubleshooting

"unexpected argument" Error

All inputs must be listed in outputs function:

nix

# Wrongoutputs = { self, nixpkgs }: ...
# Right (if you have more inputs)outputs = { self, nixpkgs, other-input, ... }: ...

# Wrongoutputs = { self, nixpkgs }: ...
# Right (if you have more inputs)outputs = { self, nixpkgs, other-input, ... }: ...

Unfree Package Errors with nix develop

config.allowUnfree in flake.nix doesn't propagate to nix develop. Use:

nixpkgs-unfree input (recommended)
User's ~/.config/nixpkgs/config.nix
NIXPKGS_ALLOW_UNFREE=1 nix develop --impure

Duplicate Nixpkgs Downloads

Use follows to chain inputs to a single nixpkgs source.

Overlay Not Applied

Ensure overlay is in the overlays list when importing nixpkgs:

Hash Mismatch

Re-fetch with nix-prefetch-url and update the hash. Hashes change when upstream updates binaries at the same URL.

Source and attribution

Source:alleneubank/claude-codein.claude/skills/nix-best-practicesat commit2921eb8

License: No license

Content belongs to its original authors. SourceWeft indexes it from a public repository.

Report or request removal

Nix Best Practices

Nix Best Practices

Flake Structure

Follows Pattern (Avoid Duplicate Nixpkgs)

Applying Overlays

Handling Unfree Packages

Option 1: nixpkgs-unfree (Recommended for Teams)

Option 2: User Config

Option 3: Specific Packages (Flake)

Creating Binary Overlay Repos

Pattern (see 0xBigBoss/atlas-overlay, 0xBigBoss/bun-overlay)

Getting SHA256 Hashes

Dev Shell Patterns

Basic Shell

With Environment Variables

Native Dependencies (C Libraries)

Direnv Integration

Common Commands

Troubleshooting

"unexpected argument" Error

Unfree Package Errors with nix develop

Duplicate Nixpkgs Downloads

Overlay Not Applied

Hash Mismatch

Source and attribution

More from alleneubank/claude-code

React Best Practices

Web Fetch

Typescript Best Practices

Zig Best Practices

Python Best Practices

More in Software Development

Playground

M5 Onboard

Cardputer Buddy

Web Design Guidelines

Vercel React Native Skills

Vercel React Best Practices