Catalog imports

Overview

Catalog imports allow your Nix expression builds to depend on packages provided by external sources: FloxHub users and organizations that publish reusable packages. Packages are added to a catalog with flox publish. Catalog imports are how you consume those packages in a build. 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. You access their packages through the catalogs argument in your expressions. This keeps your build inputs explicit. 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.

Catalogs

A catalog references packages published to FloxHub via flox publish. The catalog name corresponds to the FloxHub user or organization that published them. 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.

Using catalogs in expressions

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.my-org.my-package

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.my-org.common-utils ];
  meta.license = lib.licenses.mit;
}

Reference catalog packages with literal attribute names all the way down: catalogs.<catalog>.<package>. If Flox cannot statically determine which package you mean, it falls back to a wildcard import and locks the whole catalog (<catalog>.*), or the whole package set (<catalog>.<set>.*) for a nested selection. This pulls in far more than a single package.A wildcard import is triggered by:

a computed attribute anywhere in the path, such as catalogs.my-org.${name};
builtins.getAttr (or getAttr) with a non-literal key, such as getAttr name catalogs.my-org;
with catalogs.my-org; ..., which brings the catalog’s packages into scope.

A computed catalog name (the <catalog> segment itself), such as catalogs.${org}.pkg, is not supported at all. It cannot be locked, and the build fails to resolve.

Resolving and locking

Catalog references are resolved and locked automatically when you run flox build or flox publish. There is no declaration file to maintain and no separate lock step. Flox resolves each catalogs.<catalog>.<package> reference to the latest available sources for that package and its dependency closure. Locking happens at build time and is not written to a lockfile in your project. Because of this, two runs of flox build can resolve to different inputs as catalogs advance, and the transitive dependencies of a locked package may differ between builds. flox build on its own is not guaranteed to use the exact same dependencies each time. flox publish pins the inputs it used. A published build records its source, its nixpkgs revision, and its resolved dependency closure, so it can be rebuilt from the same inputs later. To pick up newer versions of a package from a catalog, re-run flox build (or flox publish).

Examples

Example: FloxHub catalog

This example uses a package published to FloxHub by the organization my-org. 1. Write an expression that uses it:

.flox/pkgs/demo.nix

{ catalogs }:

catalogs.my-org.my-package

2. Build it:

flox build demo

Flox resolves and pins the catalogs.my-org.my-package reference as part of the build.

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.my-org.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.my-org.crypto-utils dependency is resolved from the my-org catalog.

Introduction

Install Flox

Quickstart

Tutorials

Imageless Kubernetes

Concepts

Languages

Customer

Catalog imports

Overview

Catalogs

Using catalogs in expressions

Resolving and locking

Examples

Example: FloxHub catalog

Example: Combining catalogs with nixpkgs

​Overview

​Catalogs

​Using catalogs in expressions

​Resolving and locking

​Examples

​Example: FloxHub catalog

​Example: Combining catalogs with nixpkgs

Overview

Catalogs

Using catalogs in expressions

Resolving and locking

Examples

Example: FloxHub catalog

Example: Combining catalogs with nixpkgs