name: Nixpkgs description: Contributing to NixOS/nixpkgs repository. USE WHEN in nixpkgs repository (git remote contains NixOS/nixpkgs OR path contains github.com/NixOS/nixpkgs), reviewing PRs, updating packages, or contributing to nixpkgs.

Nixpkgs Contribution Guide

Purpose

Expert guidance for contributing to the NixOS/nixpkgs repository, reviewing pull requests, and maintaining packages.

Context Detection

This skill activates when:

Git remote URL contains NixOS/nixpkgs or nixos/nixpkgs
Current directory path contains github.com/NixOS/nixpkgs or ~/src/nixpkgs
User explicitly mentions nixpkgs-review, nix-update, or nixpkgs contribution
User asks a question about nix packages

Workflow Routing

When the user’s request matches specific nixpkgs operations, route to the appropriate workflow:

Workflow	Trigger	File
Review	“review pr”, “nixpkgs-review”, “review pull request”, “test pr”	`workflows/Review.md`
Add Package	“add package”, “new package”, “init package”, “create package”	`workflows/AddPackage.md`
Update Package	“update package”, “bump version”, “upgrade package”, “nix-update”	`workflows/UpdatePackage.md`
Fix Package	“fix package”, “broken package”, “build failing”, “package doesn’t work”	`workflows/FixPackage.md`
Maintainer	“maintainer”, “triage issues”, “package maintenance”, “become maintainer”	`workflows/Maintainer.md`

When to use workflows:

Route when the user explicitly asks about one of these operations
Workflows provide comprehensive, step-by-step guidance for nixpkgs contributions
For general nixpkgs questions or tool usage, continue with this main skill

Quick Reference

Review PR

# Review pull request (multi-arch recommended)
nixpkgs-review pr 12345 --systems 'x86_64-linux aarch64-linux' --no-shell

# Review single architecture (quick test)
nixpkgs-review pr 12345

# Review and post results
nixpkgs-review pr 12345 --post-result

# Review specific packages only
nixpkgs-review pr 12345 -p firefox

Auto-Merge PR (Maintainers)

# Automated review + approve + merge (if you're maintainer of all touched packages)
~/.config/claude/skills/Nixpkgs/scripts/auto-merge-pr 12345

Update Package

# Update package version
nix-update package-name

# Update and build
nix-update --build package-name

# Update, build, and commit
nix-update --build --commit package-name

Review Local Changes

# Review uncommitted changes
nixpkgs-review wip

# Review staged changes only
nixpkgs-review wip --staged

# Review specific commit
nixpkgs-review rev HEAD

nixpkgs-review

Installation

# Run without installing
nix run nixpkgs#nixpkgs-review

# Install to profile
nix profile install nixpkgs#nixpkgs-review

# In development shell
nix-shell -p nixpkgs-review

Basic PR Review

# Review PR on multiple architectures (recommended for thorough review)
nixpkgs-review pr 12345 --systems 'x86_64-linux aarch64-linux' --no-shell

# Review PR by number (single arch, interactive)
nixpkgs-review pr 12345

# Review PR by URL
nixpkgs-review pr https://github.com/NixOS/nixpkgs/pull/12345

# Multi-arch review will:
# 1. Fetch the PR
# 2. Determine changed packages
# 3. Build all changed packages on both x86_64 and aarch64
# 4. Catch architecture-specific issues
# 5. Provide more comprehensive testing

Post Results to PR

# Post build report as comment
nixpkgs-review pr 12345 --post-result

# Requires GitHub authentication
# Set up with gh, hub, or GITHUB_TOKEN

GitHub Authentication

# Method 1: GitHub CLI (recommended)
gh auth login

# Method 2: Environment variable
export GITHUB_TOKEN=ghp_...

# Method 3: hub configuration
# ~/.config/hub:
github.com:
- user: username
  oauth_token: token
  protocol: https

Review Options

# Build only specific packages
nixpkgs-review pr 12345 -p firefox chromium

# Build packages matching regex
nixpkgs-review pr 12345 --package-regex "python.*"

# Review for multiple systems
nixpkgs-review pr 12345 --systems 'x86_64-linux aarch64-linux'

# Don't enter shell (non-interactive)
nixpkgs-review pr 12345 --no-shell

# Run custom command instead of shell
nixpkgs-review pr 12345 --run "nix-shell -p hello --run hello"

# Print results to stdout
nixpkgs-review pr 12345 --print-result

# Sandbox mode (protect HOME)
nixpkgs-review pr 12345 --sandbox

System Selection (–systems flag)

The --systems flag allows building for multiple architectures. Use space-separated values in quotes.

# Multiple specific platforms (space-separated in quotes)
nixpkgs-review pr 12345 --systems 'x86_64-linux aarch64-linux'

# Predefined groups
nixpkgs-review pr 12345 --systems all       # all 4 platforms
nixpkgs-review pr 12345 --systems linux     # both Linux (x86_64, aarch64)
nixpkgs-review pr 12345 --systems darwin    # both Darwin (x86_64, aarch64)
nixpkgs-review pr 12345 --systems x64       # both x86_64 (linux, darwin)
nixpkgs-review pr 12345 --systems aarch64   # both aarch64 (linux, darwin)

Valid platforms: x86_64-linux, aarch64-linux, x86_64-darwin, aarch64-darwin

Interactive Commands

# After nixpkgs-review pr drops you in shell:

# Approve PR (adds approval comment)
nix-shell> nixpkgs-review approve

# Merge PR (requires maintainer access)
nix-shell> nixpkgs-review merge

# Show PR comments
nix-shell> nixpkgs-review comments

# Exit shell
nix-shell> exit

Merge Bot (Maintainers Only)

For PRs labeled 2.status: merge-bot eligible, maintainers can request automated merge:

# Post comment on PR to trigger auto-merge
gh pr comment 12345 --body "@NixOS/nixpkgs-merge-bot merge"

# Or via web interface: comment "@NixOS/nixpkgs-merge-bot merge"

Requirements:

You are listed as maintainer of ALL touched packages
PR targets a development branch (master, staging, etc.)
PR touches only files in pkgs/by-name/
PR is approved OR opened by r-ryantm/committer
You are a member of @NixOS/nixpkgs-maintainers

Use cases:

Simple version bumps you maintain
Dependency updates for your packages
Low-risk changes to packages you maintain

Note: Sometimes GitHub gets stuck after enabling Auto Merge. Leave another approval to trigger the merge.

Automation Script: auto-merge-pr

For maintainers, an automation script is provided to streamline the review and merge process.

Location: ~/.config/claude/skills/Nixpkgs/scripts/auto-merge-pr

Usage:

# From nixpkgs repository
~/.config/claude/skills/Nixpkgs/scripts/auto-merge-pr <PR_NUMBER>

# Or add to PATH for convenience
export PATH="$HOME/.config/claude/skills/Nixpkgs/scripts:$PATH"
auto-merge-pr <PR_NUMBER>

What it does:

Fetches PR details and identifies packages in pkgs/by-name/
Checks if you’re a maintainer of ALL touched packages
Runs nixpkgs-review pr <PR_NUMBER> --no-shell
If successful, approves PR and triggers merge bot in one comment
If not maintainer or build fails, exits with error message

Example:

cd ~/src/nixpkgs
auto-merge-pr 480509

Output:

🔍 Fetching PR #480509 details...
📦 Found packages: kompose
👤 Your GitHub username: vdemeester
✅ You are a maintainer of kompose

🏗️  Building PR #480509...
[nixpkgs-review build output...]

✅ Build successful!
📝 Approving PR and triggering merge bot...
✅ Done! PR approved and merge bot triggered.

Review Local Changes

# Review your uncommitted changes
nixpkgs-review wip

# Review staged changes only
nixpkgs-review wip --staged

# Review specific commit
nixpkgs-review rev HEAD

# Review commit range
nixpkgs-review rev HEAD~3..HEAD

# Review remote branch
nixpkgs-review rev origin/staging

nix-update

Installation

# Run without installing
nix run nixpkgs#nix-update

# Install to profile
nix profile install nixpkgs#nix-update

# In development shell
nix-shell -p nix-update

Basic Package Update

# Update package to latest version
nix-update package-name

# Update will:
# 1. Fetch latest version from upstream
# 2. Update version in package expression
# 3. Update source hash
# 4. Update cargo/npm hashes if applicable

Update Options

# Update and build
nix-update --build package-name

# Update and run tests
nix-update --test package-name

# Update and enter nix-shell
nix-update --shell package-name

# Update and review with nixpkgs-review
nix-update --review package-name

# Update and format file
nix-update --format package-name

# Update and commit
nix-update --commit package-name

# Combine options
nix-update --build --test --commit package-name

Update to Specific Version

# Update to specific version
nix-update --version=1.2.3 package-name

# Update to unstable/latest
nix-update --version=unstable package-name

# Update to branch
nix-update --version=branch=main package-name

Update Source Types

# PyPI package
nix-update python3Packages.package-name

# GitHub release
nix-update github-package

# Git repository
nix-update --version=branch=main git-package

# Cargo.lock update
nix-update --build rust-package

Contributing to nixpkgs

⚠️ CRITICAL: Always Run nixpkgs-review wip Before Submitting

Before submitting ANY pull request to nixpkgs, you MUST run nixpkgs-review wip:

# This is NOT optional - always run before pushing:
nixpkgs-review wip

# This ensures:
# ✓ Your changes build successfully
# ✓ Dependent packages aren't broken
# ✓ You catch issues before CI does
# ✓ You don't waste reviewer time with broken PRs

Why this matters:

CI takes time and resources - broken PRs waste both
Reviewers won’t look at PRs that fail basic builds
You’ll find and fix issues faster locally than through CI
It’s respectful to the nixpkgs community

When to run it:

After making any changes (run nixpkgs-review wip)
After updating a package (run nixpkgs-review wip)
After fixing a bug (run nixpkgs-review wip)
Before committing (run nixpkgs-review wip)
Before pushing (run nixpkgs-review wip)

Setup nixpkgs Repository

# Clone nixpkgs
cd ~/src/github.com/NixOS
git clone https://github.com/NixOS/nixpkgs.git
cd nixpkgs

# Add upstream remote
git remote add upstream https://github.com/NixOS/nixpkgs.git

# Create development environment
nix-shell -p nix-update nixpkgs-review nixfmt-rfc-style

Update Package Workflow

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

# 2. Update package
nix-update --build --commit package-name

# 3. Review changes
nixpkgs-review wip

# 4. Push and create PR
git push -u origin update/package-name
gh pr create

Add New Package Workflow

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

# 2. Create package file
mkdir -p pkgs/by-name/ne/new-package
vim pkgs/by-name/ne/new-package/package.nix

# 3. Test build
nix-build -A new-package

# 4. Review
nixpkgs-review wip

# 5. Format
nixfmt pkgs/by-name/ne/new-package/package.nix

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

Fix Package Workflow

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

# 2. Make changes
vim pkgs/path/to/package/default.nix

# 3. Test build
nix-build -A package-name

# 4. Review all affected packages
nixpkgs-review wip

# 5. Commit and push
git add .
git commit -s -m "package-name: fix issue description"
git push -u origin fix/package-name-issue
gh pr create

Review Best Practices

Review Workflow

# 1. Review PR on multiple architectures (recommended)
nixpkgs-review pr 12345 --systems 'x86_64-linux aarch64-linux' --no-shell

# OR: Review PR interactively (single arch)
nixpkgs-review pr 12345

# 2. In the nix-shell (if interactive), test packages
nix-shell> package-name --version
nix-shell> package-name --help

# 3. Check for issues
nix-shell> ls -la $(which package-name)

# 4. If good, approve (or use gh pr review for multi-arch)
nix-shell> nixpkgs-review approve
# OR (if --no-shell was used):
gh pr review 12345 --approve --body "Built successfully on x86_64-linux and aarch64-linux. LGTM."

# 5. Exit
nix-shell> exit

What to Check

Package builds successfully: No build errors
Tests pass: If package has tests
Binary works: Can execute and shows help
Dependencies correct: No missing runtime dependencies
License correct: Matches upstream
Meta attributes: Description, homepage accurate
No regressions: Dependent packages still build

Common Review Scenarios

Version Update PR

# Review version bump (multi-arch recommended)
nixpkgs-review pr 12345 --systems 'x86_64-linux aarch64-linux' --no-shell

# Check:
# - Version number correct
# - Hash updated correctly
# - Tests still pass on both architectures
# - No breaking changes

New Package PR

# Review new package
nixpkgs-review pr 12345 -p new-package

# Check:
# - Package name follows conventions
# - In correct category (pkgs/by-name/)
# - Meta attributes complete
# - License specified
# - Maintainers added
# - Tests included

Security Update PR

# Review security update
nixpkgs-review pr 12345

# Check:
# - CVE mentioned in description
# - Version fixes vulnerability
# - All variants updated (if multiple)
# - Consider backport to stable

Working with Package Sets

Python Packages

# Update Python package
nix-update python3Packages.package-name

# Review Python package PR
nixpkgs-review pr 12345 -p python3Packages.package-name

Haskell Packages

# Update Haskell package
nix-update haskellPackages.package-name

# Update all Haskell packages
# (This is done by nixpkgs maintainers)

Node Packages

# Node packages use node2nix
# Manual update required

# Review node package
nixpkgs-review pr 12345 -p nodePackages.package-name

Commit Message Format

Version Updates

package-name: 1.0.0 -> 1.1.0

New Packages

package-name: init at 1.0.0

Fixes

package-name: fix build on aarch64-linux

Multi-Package Updates

pythonPackages: update multiple packages

- package1: 1.0 -> 1.1
- package2: 2.0 -> 2.1

Breaking Changes

package-name: 1.0.0 -> 2.0.0

Breaking changes:
- API changed from X to Y
- Configuration format updated

Advanced nixpkgs-review

Remote Builders

# Use remote builder
nixpkgs-review pr 12345 \
  --remote user@builder-host \
  --remote-build-host user@builder-host

# Configure in ~/.config/nixpkgs-review/config.toml
[remote]
host = "user@builder-host"

Custom Build Options

# Use specific nixpkgs checkout
nixpkgs-review pr 12345 --nixpkgs /path/to/nixpkgs

# Extra nix options
nixpkgs-review pr 12345 --extra-nixpkgs-config '{ allowUnfree = true; }'

Batch Review

# Review multiple PRs
for pr in 12345 12346 12347; do
  nixpkgs-review pr $pr --no-shell --post-result
done

Package Organization

pkgs/by-name Structure

pkgs/by-name/
  he/hello/package.nix       # Packages starting with "he"
  fi/firefox/package.nix     # Packages starting with "fi"
  go/go/package.nix          # Packages starting with "go"

Rules:

Package name determines directory (first 2 letters)
File must be named package.nix
One package per directory
Automatically included in all-packages.nix

Traditional Structure

pkgs/
  applications/
  development/
  servers/
  tools/

Use for packages not yet migrated to by-name.

Troubleshooting

Build Failures

# Keep build directory on failure
nixpkgs-review pr 12345 --keep-going

# Show full build logs
nixpkgs-review pr 12345 | tee review.log

Authentication Issues

# Check GitHub token
gh auth status

# Refresh token
gh auth refresh

# Set token manually
export GITHUB_TOKEN=$(gh auth token)

Evaluation Errors

# Show evaluation trace
nixpkgs-review pr 12345 --show-trace

# Check for syntax errors
nix-instantiate --parse default.nix

Tips and Tricks

⚠️ ALWAYS run nixpkgs-review wip before submitting: This is the most important step - test your changes locally before pushing
Test multiple architectures when reviewing: Use --systems 'x86_64-linux aarch64-linux' to catch arch-specific issues
Use –post-result: Auto-comment on PRs to help maintainers
Review regularly: Help reduce PR backlog
Test on your system: Real-world testing is valuable
Be thorough but kind: Constructive feedback
Check ofborg results: CI results before reviewing
Use nix-update: Automate version updates
Review related PRs: Check for conflicts
Comment on approach: Not just build success
Approve quickly: Don’t block good PRs
Learn from reviews: Read other reviewers’ comments

Resources

Examples

Example 1: Updating a package in nixpkgs

User: "Update tektoncd-cli to the latest version"
→ Finds package in nixpkgs repository
→ Updates version and hash in default.nix
→ Runs nix-build to test the update
→ Checks for breaking changes or new dependencies
→ Creates commit following nixpkgs standards
→ Opens pull request to nixpkgs
→ Result: Package updated and PR submitted

Example 2: Reviewing a nixpkgs PR

User: "Review nixpkgs PR #12345"
→ Checks out PR branch locally
→ Reviews code changes for correctness
→ Tests build with nix-build
→ Verifies meta attributes are correct
→ Checks commit message follows standards
→ Leaves review comments or approval
→ Result: Thorough PR review completed

Example 3: Adding a new package

User: "Add this new tool to nixpkgs"
→ Creates package directory structure
→ Writes derivation with proper builder (buildGoModule, etc.)
→ Adds to all-packages.nix
→ Tests on multiple platforms
→ Follows nixpkgs contribution guidelines
→ Result: New package ready for nixpkgs