main

Add Package Workflow

Add new packages to NixOS/nixpkgs repository.

⚠️ CRITICAL: Always Test With nixpkgs-review wip

Before submitting your new package PR, you MUST run nixpkgs-review wip:

nixpkgs-review wip

# This verifies:
# ✓ Your package builds successfully
# ✓ No evaluation errors
# ✓ Package can be instantiated

Untested packages that don’t build will be immediately rejected.

When to Use

  • “add package to nixpkgs”
  • “create new nixpkgs package”
  • “package new application”
  • “init package in nixpkgs”

Quick Reference

Complete Workflow

# 1. Create branch
git checkout -b pkg/package-name

# 2. Create package in pkgs/by-name
mkdir -p pkgs/by-name/pa/package-name
vim pkgs/by-name/pa/package-name/package.nix

# 3. Build and test
nix-build -A package-name
./result/bin/package-name

# 4. Review with nixpkgs-review
nixpkgs-review wip

# 5. Format code
nixfmt pkgs/by-name/pa/package-name/package.nix

# 6. Commit and push
git add .
git commit -s -m "package-name: init at 1.0.0"
git push -u origin pkg/package-name

# 7. Create PR
gh pr create

Package Location

Use pkgs/by-name (Preferred)

For top-level packages:

pkgs/by-name/
  pa/package-name/package.nix

Rules:

  • Use first 2 letters of package name as directory prefix
  • Package directory name = attribute name
  • File must be named package.nix
  • Automatically included (no all-packages.nix change needed)

Examples:

pkgs/by-name/he/hello/package.nix          # hello package
pkgs/by-name/fi/firefox/package.nix        # firefox package
pkgs/by-name/go/go/package.nix             # go package
pkgs/by-name/my/my-tool/package.nix        # my-tool package

Traditional Structure

For packages in specialized sets or categories:

pkgs/
  applications/          # GUI applications
  development/           # Development tools
    libraries/           # Libraries
    tools/               # Build tools
  servers/               # Server software
  tools/                 # Command-line tools
    networking/          # Network tools
    system/              # System tools

When to use:

  • Python packages: pkgs/development/python-modules/
  • Perl modules: pkgs/development/perl-modules/
  • Node packages: Generated via node2nix
  • Haskell packages: Generated via cabal2nix

Package Template

Basic Package Structure (Modern Pattern)

Using finalAttrs (recommended for new packages):

# pkgs/by-name/pa/package-name/package.nix
{
  lib,
  stdenv,
  fetchFromGitHub,
  nix-update-script,
  # Add build dependencies here
}:

stdenv.mkDerivation (finalAttrs: {
  pname = "package-name";
  version = "1.0.0";

  src = fetchFromGitHub {
    owner = "owner";
    repo = "repo";
    tag = "v${finalAttrs.version}";
    hash = "sha256-AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=";
  };

  nativeBuildInputs = [
    # Build-time dependencies (compilers, build tools)
  ];

  buildInputs = [
    # Runtime dependencies (libraries)
  ];

  passthru.updateScript = nix-update-script { };

  meta = {
    description = "Brief description of what this package does";
    homepage = "https://github.com/owner/repo";
    changelog = "https://github.com/owner/repo/releases/tag/v${finalAttrs.version}";
    license = lib.licenses.mit;
    maintainers = with lib.maintainers; [ your-github-username ];
    platforms = lib.platforms.linux;
    mainProgram = "package-name";
  };
})

Traditional rec pattern (still acceptable):

stdenv.mkDerivation rec {
  pname = "package-name";
  version = "1.0.0";

  src = fetchFromGitHub {
    owner = "owner";
    repo = "repo";
    rev = "v${version}";
    hash = "sha256-AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=";
  };

  # ... rest of package
}

Important: When using finalAttrs, reference version/pname within src as finalAttrs.version and finalAttrs.pname. Avoid using with lib; in meta - use explicit lib.licenses, lib.platforms instead for better overriding support.

Language-Specific Builders

Go Package (buildGoModule)

Modern pattern with finalAttrs and updateScript (recommended):

{
  lib,
  buildGoModule,
  fetchFromGitHub,
  nix-update-script,
}:

buildGoModule (finalAttrs: {
  pname = "package-name";
  version = "1.0.0";

  src = fetchFromGitHub {
    owner = "owner";
    repo = "repo";
    tag = "v${finalAttrs.version}";
    hash = "sha256-AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=";
  };

  vendorHash = "sha256-BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB=";

  ldflags = [
    "-s"
    "-w"
    "-X main.version=${finalAttrs.version}"
  ];

  passthru.updateScript = nix-update-script { };

  meta = {
    description = "Description of Go package";
    homepage = "https://github.com/owner/repo";
    changelog = "https://github.com/owner/repo/releases/tag/v${finalAttrs.version}";
    license = lib.licenses.mit;
    maintainers = with lib.maintainers; [ your-github-username ];
    mainProgram = "package-name";
  };
})

Traditional rec pattern (still acceptable but less preferred):

{
  lib,
  buildGoModule,
  fetchFromGitHub,
  nix-update-script,
}:

buildGoModule rec {
  pname = "package-name";
  version = "1.0.0";

  src = fetchFromGitHub {
    owner = "owner";
    repo = "repo";
    tag = "v${version}";
    hash = "sha256-AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=";
  };

  vendorHash = "sha256-BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB=";

  ldflags = [
    "-s"
    "-w"
    "-X main.version=${version}"
  ];

  passthru.updateScript = nix-update-script { };

  meta = {
    description = "Description of Go package";
    homepage = "https://github.com/owner/repo";
    changelog = "https://github.com/owner/repo/releases/tag/v${version}";
    license = lib.licenses.mit;
    maintainers = with lib.maintainers; [ your-github-username ];
    mainProgram = "package-name";
  };
}

Getting vendorHash:

# Use fake hash first
vendorHash = lib.fakeHash;

# Build will fail and show correct hash
nix-build -A package-name
# Copy hash from error message

Rust Package (rustPlatform)

{
  lib,
  rustPlatform,
  fetchFromGitHub,
}:

rustPlatform.buildRustPackage rec {
  pname = "package-name";
  version = "1.0.0";

  src = fetchFromGitHub {
    owner = "owner";
    repo = "repo";
    rev = "v${version}";
    hash = "sha256-AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=";
  };

  cargoHash = "sha256-CCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCC=";

  meta = with lib; {
    description = "Description of Rust package";
    homepage = "https://github.com/owner/repo";
    license = licenses.mit;
    maintainers = with maintainers; [ your-github-username ];
    mainProgram = "package-name";
  };
}

Python Package (buildPythonPackage)

Note: Python packages go in pkgs/development/python-modules/

{
  lib,
  buildPythonPackage,
  fetchPypi,
  setuptools,
  wheel,
  # Test dependencies
  pytestCheckHook,
}:

buildPythonPackage rec {
  pname = "package-name";
  version = "1.0.0";
  format = "pyproject";

  src = fetchPypi {
    inherit pname version;
    hash = "sha256-AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=";
  };

  nativeBuildInputs = [
    setuptools
    wheel
  ];

  propagatedBuildInputs = [
    # Python runtime dependencies
  ];

  nativeCheckInputs = [
    pytestCheckHook
  ];

  pythonImportsCheck = [ "package_name" ];

  meta = with lib; {
    description = "Description of Python package";
    homepage = "https://github.com/owner/repo";
    license = licenses.mit;
    maintainers = with maintainers; [ your-github-username ];
  };
}

Node Package

Node packages are typically generated using node2nix. See nixpkgs documentation for details.

Getting Source Hash

From GitHub

# Using nix-prefetch-github
nix-prefetch-github owner repo --rev v1.0.0

# Manual with nix-prefetch-url
nix-prefetch-url --unpack https://github.com/owner/repo/archive/v1.0.0.tar.gz

From URL

# Prefetch tarball
nix-prefetch-url https://example.com/package-1.0.0.tar.gz

# For git repositories
nix-prefetch-git https://git.example.com/repo.git --rev v1.0.0

Using Fake Hash

src = fetchFromGitHub {
  owner = "owner";
  repo = "repo";
  rev = "v1.0.0";
  hash = lib.fakeHash;  # Use fake hash
};

Build will fail with correct hash:

error: hash mismatch in fixed-output derivation
  specified: sha256-AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=
     got:    sha256-RealHashGoesHere...

Copy the “got:” hash.

Build and Test

Build Package

# Build package
nix-build -A package-name

# Result symlink created
ls -l result/

# Test binary
./result/bin/package-name --version
./result/bin/package-name --help

Test Installation

# Install to profile
nix-env -f . -iA package-name

# Or with nix profile
nix profile install .#package-name

# Test installed version
package-name --version

Run Tests

# Tests run automatically during build if doCheck = true
nix-build -A package-name

# To debug test failures
nix-build -A package-name --keep-failed
cd /tmp/nix-build-*
# Examine test output

Review with nixpkgs-review

# Review your changes
nixpkgs-review wip

# This will:
# 1. Build your new package
# 2. Build packages that depend on it
# 3. Drop you into nix-shell
# 4. Test the package

# In nix-shell
package-name --version
package-name --help

# Exit when satisfied
exit

Format Code

# Format Nix file
nixfmt pkgs/by-name/pa/package-name/package.nix

# Or format all changed files
nixfmt $(git diff --name-only '*.nix')

Commit Message Format

New Package

package-name: init at 1.0.0

New Package with Details

package-name: init at 1.0.0

Package description and why it's useful.

Closes #12345

Python Package

python3Packages.package-name: init at 1.0.0

Create Pull Request

Push Branch

# Push to your fork
git push -u origin pkg/package-name

Create PR with GitHub CLI

# Create PR
gh pr create

# Fill in:
# Title: package-name: init at 1.0.0
# Description: What the package does, why it's useful

PR Description Template

## Description
Brief description of what this package does.

## Checklist
- [ ] Built and tested locally
- [ ] Ran nixpkgs-review
- [ ] Formatted with nixfmt
- [ ] Meta attributes complete (description, license, maintainers)
- [ ] mainProgram set (if applicable)

## Testing
Tested on x86_64-linux:
- [x] Builds successfully
- [x] Binary executes
- [x] --help and --version work

Checklist

Before submitting PR:

  • Package builds successfully (nix-build -A package-name)
  • Binary works (./result/bin/package-name)
  • Ran nixpkgs-review wip
  • Formatted with nixfmt
  • Used pkgs/by-name structure (if top-level package)
  • Used tag instead of rev in fetchFromGitHub
  • Added passthru.updateScript = nix-update-script { };
  • Used finalAttrs pattern (recommended)
  • Added nix-update-script to function inputs
  • Correct package name (lowercase, hyphens)
  • Accurate description
  • Correct license
  • Added yourself to maintainers
  • Set mainProgram (if applicable)
  • Commit message follows convention
  • Signed commit (-s flag)

Modern Nix Patterns

The finalAttrs Pattern

The finalAttrs pattern provides self-referencing within package definitions:

stdenv.mkDerivation (finalAttrs: {
  pname = "package";
  version = "1.0.0";

  # Can reference finalAttrs.version here
  src = fetchurl {
    url = "https://example.com/${finalAttrs.pname}-${finalAttrs.version}.tar.gz";
    hash = "...";
  };

  # Can also reference in build phases
  buildPhase = ''
    echo "Building ${finalAttrs.pname} version ${finalAttrs.version}"
  '';
})

Benefits:

  • Better override support (overrideAttrs works correctly)
  • No need for rec { } (avoids recursion issues)
  • Clearer intent when self-referencing

When to use:

  • Recommended for all new packages
  • Especially when referencing pname/version in src, phases, or scripts
  • Migration from rec is encouraged but not required

When NOT to use finalAttrs.pname/version in src hash:

# DON'T DO THIS - hash won't change when overriding
src = fetchurl {
  url = "https://example.com/${finalAttrs.pname}-${finalAttrs.version}.tar.gz";
  hash = "sha256-fixedhash...";  # This hash is for specific version!
};

Overriding version will cause hash mismatch. Instead, users must override both version AND hash when needed.

Meta Attributes Without ‘with lib’

Modern style avoids with lib; in meta for better overriding:

# Modern (recommended)
meta = {
  description = "Package description";
  license = lib.licenses.mit;
  maintainers = with lib.maintainers; [ yourhandle ];
  platforms = lib.platforms.linux;
};

# Old style (still works, but less preferred)
meta = with lib; {
  description = "Package description";
  license = licenses.mit;
  maintainers = with maintainers; [ yourhandle ];
  platforms = platforms.linux;
};

The with lib.maintainers is acceptable since it’s a simple lookup list.

Common Review Feedback

Expect reviewers to ask for these improvements:

1. “Use tag instead of rev in fetchFromGitHub”

# Change from:
src = fetchFromGitHub {
  owner = "owner";
  repo = "repo";
  rev = "v${version}";
  hash = "...";
};

# To:
src = fetchFromGitHub {
  owner = "owner";
  repo = "repo";
  tag = "v${version}";  # Preferred nowadays
  hash = "...";
};

Reference: fetchFromGitHub docs

2. “Add passthru.updateScript”

# Add nix-update-script to inputs
{
  lib,
  buildGoModule,
  fetchFromGitHub,
  nix-update-script,  # Add this
}:

# Add to package definition
passthru.updateScript = nix-update-script { };

Reference: Automatic package updates

3. “Please use pkgs/by-name structure”

# Move from:
pkgs/tools/networking/package-name/default.nix

# To:
pkgs/by-name/pa/package-name/package.nix

4. “Add yourself as maintainer”

meta = {
  maintainers = with lib.maintainers; [ yourhandle ];
};

5. “Set mainProgram”

meta = {
  mainProgram = "binary-name";  # The primary executable
};

6. “Use finalAttrs pattern”

# Change from:
stdenv.mkDerivation rec {

# To:
stdenv.mkDerivation (finalAttrs: {

Reference: Fixed-point pattern

7. “Format with nixfmt”

nixfmt pkgs/by-name/pa/package-name/package.nix

8. “Fix commit message format”

# Should be:
package-name: init at 1.0.0

# Not:
Add package-name
Added new package package-name

9. “Add package description”

meta = {
  description = "Brief, clear description of what this does";
  # Not: "A package for..."
  # Not: "package-name is a..."
};

10. “Specify correct license”

# Check upstream LICENSE file
meta = {
  license = lib.licenses.mit;  # Match upstream exactly
};

11. “Remove unnecessary dependencies”

# Only include dependencies actually used
# Reviewers may ask: "Is pkg-config actually needed?"

12. “Use nativeBuildInputs for build tools”

# Move build tools from buildInputs
nativeBuildInputs = [ cmake pkg-config ];
buildInputs = [ openssl ];  # Only runtime deps

Common Issues

Package Name

  • Use lowercase
  • Use hyphens, not underscores
  • Match upstream name when possible
  • Don’t include language prefix (no “python-”, “go-”, etc.)

Dependencies

nativeBuildInputs (build-time):

  • Compilers (gcc, rustc)
  • Build tools (cmake, meson, pkg-config)
  • Code generators

buildInputs (runtime):

  • Libraries (openssl, zlib)
  • Runtime dependencies

propagatedBuildInputs (dependencies that must be in runtime environment):

  • Libraries that expose headers
  • Python dependencies

License

Find license in upstream repository:

# Common licenses
licenses.mit
licenses.asl20        # Apache 2.0
licenses.gpl3Only
licenses.lgpl3Only
licenses.bsd3
licenses.mpl20        # Mozilla Public License 2.0

Platforms

# Common platform sets
platforms.linux
platforms.darwin
platforms.unix        # Linux + macOS
platforms.all

Real Package Examples

Example 1: Simple CLI Tool (Go)

A minimal Go CLI tool with no extra dependencies:

# pkgs/by-name/he/hello-go/package.nix
{
  lib,
  buildGoModule,
  fetchFromGitHub,
}:

buildGoModule rec {
  pname = "hello-go";
  version = "1.2.3";

  src = fetchFromGitHub {
    owner = "example";
    repo = "hello-go";
    rev = "v${version}";
    hash = "sha256-AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=";
  };

  vendorHash = "sha256-BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB=";

  ldflags = [
    "-s"
    "-w"
    "-X main.version=${version}"
  ];

  meta = {
    description = "Simple hello world CLI tool";
    homepage = "https://github.com/example/hello-go";
    license = lib.licenses.mit;
    maintainers = with lib.maintainers; [ yourhandle ];
    mainProgram = "hello-go";
  };
}

Example 2: Rust Application with Dependencies

A Rust application that needs system libraries:

# pkgs/by-name/my/my-rust-app/package.nix
{
  lib,
  rustPlatform,
  fetchFromGitHub,
  pkg-config,
  openssl,
  stdenv,
  darwin,
}:

rustPlatform.buildRustPackage rec {
  pname = "my-rust-app";
  version = "2.1.0";

  src = fetchFromGitHub {
    owner = "example";
    repo = "my-rust-app";
    rev = "v${version}";
    hash = "sha256-AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=";
  };

  cargoHash = "sha256-BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB=";

  nativeBuildInputs = [ pkg-config ];

  buildInputs =
    [ openssl ]
    ++ lib.optionals stdenv.hostPlatform.isDarwin [
      darwin.apple_sdk.frameworks.Security
      darwin.apple_sdk.frameworks.SystemConfiguration
    ];

  meta = {
    description = "Rust application for doing something useful";
    homepage = "https://github.com/example/my-rust-app";
    license = lib.licenses.asl20;
    maintainers = with lib.maintainers; [ yourhandle ];
    mainProgram = "my-rust-app";
  };
}

Example 3: C/C++ Application with CMake

Traditional C++ application using CMake build system:

# pkgs/by-name/my/myapp/package.nix
{
  lib,
  stdenv,
  fetchFromGitHub,
  cmake,
  pkg-config,
  zlib,
  libpng,
  boost,
}:

stdenv.mkDerivation (finalAttrs: {
  pname = "myapp";
  version = "3.0.1";

  src = fetchFromGitHub {
    owner = "example";
    repo = "myapp";
    rev = "v${finalAttrs.version}";
    hash = "sha256-AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=";
  };

  nativeBuildInputs = [
    cmake
    pkg-config
  ];

  buildInputs = [
    zlib
    libpng
    boost
  ];

  cmakeFlags = [
    "-DENABLE_TESTS=OFF"
    "-DBUILD_SHARED_LIBS=ON"
  ];

  meta = {
    description = "C++ application for processing images";
    homepage = "https://github.com/example/myapp";
    license = lib.licenses.gpl3Only;
    maintainers = with lib.maintainers; [ yourhandle ];
    platforms = lib.platforms.unix;
    mainProgram = "myapp";
  };
})

Example 4: Python Application

Python CLI tool installed as application (not library):

# pkgs/by-name/py/pytool/package.nix
{
  lib,
  python3Packages,
  fetchFromGitHub,
}:

python3Packages.buildPythonApplication rec {
  pname = "pytool";
  version = "1.5.0";
  pyproject = true;

  src = fetchFromGitHub {
    owner = "example";
    repo = "pytool";
    rev = "v${version}";
    hash = "sha256-AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=";
  };

  build-system = with python3Packages; [
    setuptools
    wheel
  ];

  dependencies = with python3Packages; [
    click
    requests
    pyyaml
  ];

  nativeCheckInputs = with python3Packages; [
    pytestCheckHook
  ];

  pythonImportsCheck = [ "pytool" ];

  meta = {
    description = "Python tool for data processing";
    homepage = "https://github.com/example/pytool";
    license = lib.licenses.mit;
    maintainers = with lib.maintainers; [ yourhandle ];
    mainProgram = "pytool";
  };
}

Example 5: Application with Wrapper

Application that needs runtime dependencies in PATH:

# pkgs/by-name/my/myshell/package.nix
{
  lib,
  stdenv,
  fetchFromGitHub,
  makeWrapper,
  bash,
  git,
  curl,
  jq,
}:

stdenv.mkDerivation (finalAttrs: {
  pname = "myshell";
  version = "0.5.0";

  src = fetchFromGitHub {
    owner = "example";
    repo = "myshell";
    rev = "v${finalAttrs.version}";
    hash = "sha256-AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=";
  };

  nativeBuildInputs = [ makeWrapper ];

  installPhase = ''
    runHook preInstall

    mkdir -p $out/bin
    cp myshell.sh $out/bin/myshell
    chmod +x $out/bin/myshell

    # Wrap to add runtime dependencies to PATH
    wrapProgram $out/bin/myshell \
      --prefix PATH : ${
        lib.makeBinPath [
          bash
          git
          curl
          jq
        ]
      }

    runHook postInstall
  '';

  meta = {
    description = "Shell script wrapper for git operations";
    homepage = "https://github.com/example/myshell";
    license = lib.licenses.mit;
    maintainers = with lib.maintainers; [ yourhandle ];
    mainProgram = "myshell";
  };
})

Example 6: Desktop Application

GUI application with desktop entry:

# pkgs/by-name/my/myapp-gui/package.nix
{
  lib,
  stdenv,
  fetchFromGitHub,
  cmake,
  pkg-config,
  qt6,
  wrapQtAppsHook,
  makeDesktopItem,
  copyDesktopItems,
}:

stdenv.mkDerivation (finalAttrs: {
  pname = "myapp-gui";
  version = "2.0.0";

  src = fetchFromGitHub {
    owner = "example";
    repo = "myapp-gui";
    rev = "v${finalAttrs.version}";
    hash = "sha256-AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=";
  };

  nativeBuildInputs = [
    cmake
    pkg-config
    wrapQtAppsHook
    copyDesktopItems
  ];

  buildInputs = [
    qt6.qtbase
    qt6.qtsvg
  ];

  desktopItems = [
    (makeDesktopItem {
      name = "myapp-gui";
      exec = "myapp-gui";
      icon = "myapp-gui";
      desktopName = "MyApp GUI";
      comment = "GUI application for MyApp";
      categories = [ "Utility" ];
    })
  ];

  postInstall = ''
    install -Dm644 resources/icon.png $out/share/icons/hicolor/256x256/apps/myapp-gui.png
  '';

  meta = {
    description = "Graphical user interface for MyApp";
    homepage = "https://github.com/example/myapp-gui";
    license = lib.licenses.gpl3Plus;
    maintainers = with lib.maintainers; [ yourhandle ];
    platforms = lib.platforms.linux;
    mainProgram = "myapp-gui";
  };
})

Resources