nix-index: finding Nix packages by installed file path

Why nix-index targets missing files rather than missing package names

nix-index answers a question that ordinary Nix package-name search handles poorly: which nixpkgs package provides a particular file? The documented example searches for `bin/hello` and returns several matches, including `hello.out`, multiple `dpdk.examples` attributes, and `camlistore.out`. Each result associates a package attribute with a file size and a concrete `/nix/store/...` path.

This is useful when the user has a path, executable name, manual page, shared library, or shell script but does not know its package attribute. It is also relevant during shell recovery. The README documents a command-not-found script that turns an unresolved command into a suggested nixpkgs attribute and a one-time `nix-shell` command.

The database is not a general-purpose search engine over every possible nixpkgs build. The README says that nix-index indexes built derivations found in binary caches. Consequently, coverage depends on what the referenced caches contain. A missing result is not proof that no nixpkgs package provides the file. It may mean that the package was not built in an indexed cache or that the database was generated from different cache contents.

How nix-index turns binary-cache contents into searchable paths

The repository separates index creation from lookup. `nix-index` performs the indexing work, while `nix-locate` queries the resulting database. During creation, `src/hydra.rs` handles downloading file listings and references from binary caches. `src/nixpkgs.rs` gathers packages and attributes using `nix-env`, while `src/workset.rs` implements a recursive queue for fetching references.

The database layer sits between remote cache data and user queries. `src/database.rs` contains high-level database operations, and `src/files.rs` defines the file-listing data types. Path storage is handled through `src/frcode.rs`, described by the README as an efficient encoder for large collections of file paths. The Cargo configuration shows serialization through `bincode` and `serde`, with regular-expression support from `regex` and parallel processing through `rayon`.

The package representation in `src/package.rs` retains Nix store-path and attribute information. That combination allows a path match to produce a useful package attribute instead of only returning an opaque store path. The tradeoff is freshness. The database reflects derivations available at generation time, while nixpkgs attributes and binary-cache contents can change later. The README does not document an incremental refresh command or rollback behavior.

Creating a first index and searching for bin/hello with Nix flakes

nix run github:nix-community/nix-index#nix-locate -- bin/hello

The expected result is a list of matching package attributes, file sizes, and `/nix/store/...` paths. Multiple `dpdk.examples` results are normal because different Nix attributes can provide the same filename. Users who do not want to wait for local generation are directed to `nix-index-database`, which provides pre-generated databases and NixOS and home-manager modules.

Installing a checkout or the stable nixos.nix-index attribute

nix-env -iA nixos.nix-index

The README also says users can check out the latest tag before installing. `Cargo.toml` reports source version `0.1.12`, while the listed recent releases end at `v0.1.11`. That difference makes the checkout and stable attribute worth distinguishing rather than treating either route as automatically identical to the current `master` branch.

The repository is not archived, and the last push was on 2026-10-13. Release history includes `v0.1.11`, `v0.1.10`, and `v0.1.9`, with `v0.1.11` dated 2026-07-02. The README does not document a compatibility matrix across releases, so database compatibility should be checked before mixing tools and databases from different installations.

Using nix-index as a Bash, ZSH, Fish, or Nushell command fallback

programs.nushell = {
  enable = true;
  extraConfig = ''
    $env.config.hooks.command_not_found = source ${pkgs.nix-index}/etc/profile.d/command-not-found.nu
  '';
};

The README shows a missing `blender` command producing `nixpkgs.blender.out` as the install attribute and a `nix-shell -p blender.out --run ...` fallback. That output depends on the index containing the relevant derivation. The repository does not document behavior for ambiguous executable names, stale attributes, or shell-specific quoting beyond these examples.

Database freshness, cache coverage, and maintenance costs

The main operational cost is regenerating or obtaining an index. The README gives around five minutes for local creation, but does not publish machine requirements, storage size, or a refresh policy. Users who depend on changing nixpkgs attributes need a process for obtaining a newer binary-cache database. Those who want direct control can generate it from `nix-index`, while others are directed to `nix-index-database`.

The compact path representation is intended to store many paths efficiently, but the README does not state a performance benchmark. It also does not document exact resource consumption. Therefore, the five-minute creation estimate should not be converted into a promise about every cache size or host.

The Cargo manifest declares `license = "BSD-3-Clause"`, while repository metadata classifies the project license as a custom license that GitHub cannot categorize. That classification conflict makes the actual `LICENSE` file the source to inspect before redistribution or integration. This review does not interpret the license terms. Maintenance should also account for the Rust dependency set, including Nix-facing behavior in `reqwest`, `tokio`, `rusqlite`, and compression libraries.

Compared with querying known nixpkgs attributes, nix-index has higher setup and freshness costs, but it solves file-centric discovery. Compared with searching manually through online package repositories, it can query locally indexed binary-cache data and produce store paths, although the README does not claim that every result is current.

Editorial conclusion

Adopt nix-index when you repeatedly need to locate Nixpkgs packages by file path or need a shell fallback for missing commands. Do not choose it when package names already suffice or a fresh binary-cache database is not available, since it only indexes derivations already found in binary caches. Verify the selected database generation, your binary-cache coverage, and the exact terms in the repository's LICENSE file before adopting the current source version.

Frequently asked questions

Official sources

1. Issues
2. nix-community/nix-index on GitHub
3. README
4. Releases