> ## Documentation Index
> Fetch the complete documentation index at: https://flox-docs-secrets-manifest-plugins.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Catalog imports

> Import packages from external catalogs for Nix expression builds

## Overview

Catalog imports allow your [Nix expression builds](/concepts/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`](/concepts/publishing). Catalog imports are how you consume those packages in a build.

[Nix expression builds](/concepts/nix-expression-builds) already support [vendoring](/concepts/nix-expression-builds#example-vendor-an-existing-package) 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](/concepts/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`](/concepts/publishing). 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.

<Warning>
  The argument name must be `catalogs` (plural). Using `catalog` (singular) will not work.
</Warning>

Access packages by catalog name and package name:

```nix theme={null}
catalogs.<catalog-name>.<package-name>
```

For example, an expression that uses a package from a catalog:

```nix title=".flox/pkgs/demo.nix" theme={null}
{ catalogs }:

catalogs.my-org.my-package
```

The `catalogs` argument can be combined with other arguments from nixpkgs:

```nix title=".flox/pkgs/my-app.nix" theme={null}
{ 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;
}
```

<Warning>
  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.
</Warning>

## 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:**

```nix title=".flox/pkgs/demo.nix" theme={null}
{ catalogs }:

catalogs.my-org.my-package
```

**2. Build it:**

```bash theme={null}
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:

```nix title=".flox/pkgs/my-tool.nix" theme={null}
{ 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.