Skip to main content

Documentation Index

Fetch the complete documentation index at: https://flox.dev/docs/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

Catalog imports allow your Nix expression builds to depend on packages provided by external sources: FloxHub users and organizations that publish reusable packages, or remote repositories containing Nix expression definitions. Nix expression builds already support vendoring existing packages by copying their expressions into your .flox/pkgs/ directory. Catalog imports extend this model by allowing expression sharing through a central registry at the granularity of catalogs, which correspond to FloxHub user or organization namespaces, or to external repositories. You declare catalogs in a configuration file and access their packages via the catalogs argument in your expressions; this keeps your build inputs explicit, lockable, and reproducible. Catalog imports are a feature of Nix expression builds specifically; they do not apply to manifest-based builds. You should be familiar with defining packages in .flox/pkgs/ before using catalog imports.

​
Configuring catalogs

Catalog imports use two files:
  • .flox/nix-builds.toml, the user-authored configuration file where you declare which catalogs to use.
  • .flox/nix-builds.lock, a generated lockfile that pins each catalog to a specific revision for reproducibility.
Both files must be tracked by Git (git added) and should be committed to version control. The TOML file is authored by hand; the lockfile is generated and updated by the flox build update-catalogs command.

​
Catalog types

​
FloxHub catalogs

A FloxHub catalog references packages published to FloxHub via flox publish. The catalog name corresponds to the FloxHub user or organization that published them.
.flox/nix-builds.toml
version = 1

[catalogs.my-org]
type = "floxhub"
Or with dotted key syntax:
.flox/nix-builds.toml
version = 1

[catalogs]
my-org.type = "floxhub"
Your own catalog is always accessible after authenticating with flox auth login. Organization catalogs are accessible to all members of the organization. Cross-user catalog sharing is not yet available on public FloxHub; for now, catalog imports between users require Flox on-prem.

​
Nix source-ref catalogs

A source-ref catalog points at any Nix source reference: a Git repository, tarball, or other supported source type. The most common case is a Git repository that contains Flox package definitions (a .flox/pkgs/ directory). You can declare a source-ref catalog in structured form, specifying the type and additional fields:
.flox/nix-builds.toml
version = 1

[catalogs.my-packages]
type = "git"
url = "https://github.com/flox/flox-build-examples"
As a shorthand, you can provide a single url field using Nix source reference syntax (the git+ prefix encodes the type):
.flox/nix-builds.toml
version = 1

[catalogs.my-packages]
url = "git+https://github.com/flox/flox-build-examples"
You can also use TOML dotted key syntax under a [catalogs] header for simple cases:
.flox/nix-builds.toml
version = 1

[catalogs]
my-packages.type = "git"
my-packages.url = "https://github.com/flox/flox-build-examples"
The supported source types and their fields are documented in the Nix manual.

​
Common fields for git sources

FieldDescription
refGit ref to track (branch, tag). Defaults to the repository’s default branch.
dirSubdirectory containing the .flox/pkgs/ tree. Useful for monorepos.
shallowIf true, perform a shallow clone. Defaults to false.
Other source types (github, gitlab, tarball, etc.) accept their own fields; for example, github and gitlab support a host field for self-hosted instances. See the Nix source types reference for the full list. These fields are written as separate TOML keys when using the structured form (type + url). When using the URL shorthand, encode them as query parameters instead:
.flox/nix-builds.toml
version = 1

[catalogs.flox-demo]
url = "git+https://github.com/flox/flox-build-examples?dir=quotes-app-rust"
For example, to point at a subdirectory within a monorepo using the structured form:
.flox/nix-builds.toml
version = 1

[catalogs.flox-demo]
type = "git"
url = "https://github.com/flox/flox-build-examples"
dir = "quotes-app-rust"

​
Using catalogs in expressions

Once catalogs are declared in .flox/nix-builds.toml and the lockfile is generated, you access imported packages through the catalogs argument in your Nix expressions.
The argument name must be catalogs (plural). Using catalog (singular) will not work.
Access packages by catalog name and package name: 
catalogs.<catalog-name>.<package-name>
For example, an expression that uses a package from a catalog:
.flox/pkgs/demo.nix
{ catalogs }:

catalogs.flox-demo.quotes-app-rust-nix
The catalogs argument can be combined with other arguments from nixpkgs:
.flox/pkgs/my-app.nix
{ catalogs, rustPlatform, lib }:

rustPlatform.buildRustPackage {
  pname = "my-app";
  version = "0.1.0";
  src = ../../.;
  cargoLock.lockFile = ../../Cargo.lock;
  buildInputs = [ catalogs.shared-libs.common-utils ];
  meta.license = lib.licenses.mit;
}

​
Updating catalog locks

Before you can build with catalog imports, you must generate the lockfile. Run: 
flox build update-catalogs
This resolves each catalog declaration in .flox/nix-builds.toml and writes the pinned revisions to .flox/nix-builds.lock. Re-run this command whenever you:
  • Add or change a catalog entry in .flox/nix-builds.toml
  • Want to pick up newer versions of packages from a catalog
After updating, git add and commit both .flox/nix-builds.toml and .flox/nix-builds.lock.
If you run flox build without a lockfile, you will see:
error: `nix-builds.lock` not found, run `flox build update-catalogs` to generate it
and add it to version control.
If the lockfile exists but is stale (you added or changed a catalog in .flox/nix-builds.toml without re-running flox build update-catalogs), the error will be:
error: attribute 'flox-demo' missing
In either case, run flox build update-catalogs to resolve catalog entries and regenerate the lockfile.

​
Examples

​
Example: FloxHub catalog

This example uses a package published to FloxHub by the organization my-org. 1. Declare the catalog:
.flox/nix-builds.toml
version = 1

[catalogs]
my-org.type = "floxhub"
2. Write an expression that uses it:
.flox/pkgs/demo.nix
{ catalogs }:

catalogs.my-org.my-package
3. Update the lockfile and build: 
flox build update-catalogs && flox build demo

​
Example: Git catalog

This example imports a Rust application from the flox-build-examples repository. 1. Declare the catalog:
.flox/nix-builds.toml
version = 1

[catalogs.flox-demo]
type = "git"
url = "https://github.com/flox/flox-build-examples"
dir = "quotes-app-rust"
2. Write an expression that uses it:
.flox/pkgs/demo.nix
{ catalogs }:

catalogs.flox-demo.quotes-app-rust-nix
3. Update the lockfile and build: 
flox build update-catalogs && flox build demo

​
Example: Combining catalogs with nixpkgs

A realistic expression might use both catalog imports and standard nixpkgs helpers:
.flox/pkgs/my-tool.nix
{ catalogs, rustPlatform, lib }:

rustPlatform.buildRustPackage rec {
  pname = "my-tool";
  version = "0.1.0";

  src = ../../.;
  cargoLock.lockFile = "${src}/Cargo.lock";

  buildInputs = [
    catalogs.shared-libs.crypto-utils
  ];

  meta = with lib; {
    description = "A tool that uses shared crypto utilities";
    license = licenses.mit;
  };
}
Here rustPlatform and lib come from nixpkgs, as with any standard Nix expression build. The catalogs.shared-libs.crypto-utils dependency is resolved from the declared catalog.