nix-search

name: nix-search description: Use when helping users find Nix packages, NixOS configuration options, or flakes. Triggers when writing nix code, answering questions about installing software with nix, searching for which package provides a binary/program, looking up nixos options, finding package versions or platform availability, discovering flakes

Overview

Use the nix-search CLI tool to search packages, options, and flakes from search.nixos.org. Run searches proactively whenever you need package information - don't ask permission for read-only searches.

When To Use

Use when helping users find Nix packages, NixOS configuration options, or flakes. Triggers when:

writing Nix code (flake.nix, configuration.nix) that needs package names,
answering questions about installing software with Nix,
searching for which package provides a binary/program,
looking up NixOS options for system configuration,
finding package versions or platform availability,
discovering flakes. Be proactive - automatically search when you need package information rather than asking the user.

Core Search Patterns

Search by Binary/Program Name

When users ask "what package provides X?" or need a specific binary:

nix-search -p <program-name>

Examples:

nix-search -p gcc - Find package providing gcc compiler
nix-search -p terraform - Find Terraform package
nix-search -p "aws*" - Find AWS-related programs (wildcards supported)

After finding: Provide installation commands based on context.

Search by Package Attribute Name

When writing Nix code or verifying exact package names:

nix-search -n <package-name>

Examples:

nix-search -n python3 - Find python3 package
nix-search -n "emacsPackages.*" - Find Emacs packages (wildcards supported)
nix-search -n terraform - Get exact attribute name

After finding: Use the attribute name directly in Nix code.

Search by Keywords

For general discovery when users describe what they need:

nix-search "<description keywords>"

Examples:

nix-search "python linter" - Find Python linting tools
nix-search "web browser" - Find browser packages
nix-search golang - Find Go-related packages

After finding: Show relevant options, let user clarify if needed.

Search NixOS Options

When users ask about system configuration:

nix-search -t options "<option-pattern>"

Examples:

nix-search -t options "networking.firewall" - Find firewall options
nix-search -t options "services.nginx" - Find nginx configuration options
nix-search -t options boot - Find boot-related options

After finding: Provide configuration.nix example with the option.

Search Flakes

When users need to discover flakes:

nix-search -t flakes <query>

Examples:

nix-search -t flakes wayland - Find Wayland-related flakes
nix-search -t flakes home-manager - Find home-manager flakes

Platform-Specific Search

When architecture matters:

nix-search --platform <arch> <query>

Platforms: x86_64-linux, aarch64-linux, aarch64-darwin, x86_64-darwin, i686-linux, armv7l-linux, riscv64-linux, powerpc64le-linux

Example:

nix-search --platform aarch64-darwin python3 - Check if Python 3 is available for Apple Silicon

Channel-Specific Search

To check specific NixOS releases:

nix-search -c <channel> <query>

Common channels: unstable, 24.11, 24.05, 23.11, 23.05

Example:

nix-search -c 24.05 firefox - Find Firefox in stable 24.05
nix-search -c unstable nodejs - Find latest Node.js

Version Search

To find or verify specific versions:

nix-search <package> -v "<version-pattern>"

Examples:

nix-search golang -v "1.21" - Find Go version 1.21
nix-search terraform -v "1.*" - Find Terraform 1.x versions

Contextual Actions

After running searches, take appropriate action based on context:

Context: Writing flake.nix

Detect: Editing flake.nix or user asks to modify flake Action: Insert package attribute directly into code

# User: "Add terraform to my devShell"
# → Run: nix-search -n terraform
# → Insert into flake.nix:
{
  devShells.default = pkgs.mkShell {
    packages = with pkgs; [
      terraform
    ];
  };
}

Context: Writing configuration.nix

Detect: Editing configuration.nix or user asks about system packages Action: Add to environment.systemPackages or appropriate service configuration

# User: "Install firefox system-wide"
# → Run: nix-search -n firefox
# → Insert:
environment.systemPackages = with pkgs; [
  firefox
];

Context: Interactive Q&A

Detect: User asking "how do I install X?" or "what package has Y?" Action: Show package info with installation commands

# User: "How do I install gcc?"
# → Run: nix-search -p gcc
# → Response:
The gcc package provides the GCC compiler collection.

Install temporarily (for current shell):
  nix shell nixpkgs#gcc

Install persistently:
  nix profile install nixpkgs#gcc

Or add to your flake.nix or configuration.nix

Context: NixOS Options Lookup

Detect: Questions about "how do I configure X?" or "what's the option for Y?" Action: Provide configuration example

# User: "How do I enable the firewall?"
# → Run: nix-search -t options "networking.firewall.enable"
# → Response:
Add to your configuration.nix:

networking.firewall.enable = true;
networking.firewall.allowedTCPPorts = [ 80 443 ];

Context: Version or Platform Questions

Detect: Questions about "is X available for Y?" or "what version of Z?" Action: Check across channels/platforms and report

# User: "Is Python 3.12 available for ARM?"
# → Run: nix-search --platform aarch64-linux python3 -v "3.12"
# → Report availability and recommend channel if needed

Common Scenarios

"How do I install X?"

Run nix-search -p X or nix-search X
Show package description
Provide installation commands (shell/profile/flake)

"What package has the Y binary?"

Run nix-search -p Y
Show matching packages with descriptions
If multiple matches, show top 2-3, let user choose if ambiguous

"Add Z to my development environment"

Run nix-search -n Z to verify package exists
Detect which file (flake.nix, shell.nix)
Add package to appropriate packages list

"How do I configure W service?"

Run nix-search -t options "services.W"
Show relevant options with types and descriptions
Provide configuration.nix example

"Is package X available for my platform?"

Run nix-search --platform <arch> X
If not found, try unstable channel
Report availability or suggest alternatives

Error Handling

No Results Found

Try broader search terms
Remove filters (version, platform)
Check spelling
Search in unstable channel
Suggest similar packages if available

Multiple Ambiguous Matches

Show top 2-3 results with brief descriptions
Let user clarify which one they want
Don't guess - ask if unclear

Platform Unavailable

Check if available on other platforms
Try unstable channel
Inform user of availability constraints
Suggest alternatives if possible

Version Not Found

Show available versions
Suggest closest match
Check unstable channel for newer versions

Output Control

Silent Searches

Run searches without announcing them. Just show results or integrate into code/answers.

Detailed Information

Use -d flag when user needs more details:

nix-search -d python3

JSON Output

For programmatic parsing (rare, only if needed for complex logic):

nix-search --json python3

Advanced Patterns

For advanced scenarios (pagination, complex filtering, JSON parsing), see references/search-patterns.md.

Key Principles

Be proactive - Search automatically when you need package info
Context-aware - Different actions for code vs. Q&A
Silent operation - Don't announce searches, just use results
Handle errors gracefully - Try alternatives, suggest solutions
Verify before writing - Always check package exists before adding to code