LEARN / THE CATALOG, BUILDS AND PUBLISHING

The Catalog, builds and publishing

The Flox Catalog is the package source behind every environment: a Base Catalog Flox builds from a fork of nixpkgs, plus private custom catalogs you fill with flox publish. Versions resolve per package group, so you can pin an old library without freezing the rest, and flox build turns the same environment into a package.

What the Catalog is

“A Flox Catalog is a collection of package artifacts and associated metadata that can be consumed via a Flox Environment.” (https://flox.dev/docs/concepts/packages-and-catalog) There are two kinds (https://flox.dev/docs/concepts/packages-and-catalog):

Kind	Who maintains it	How it is filled	Source
Base Catalog	Flox, using nixpkgs as an input	Automated evaluation of a nixpkgs fork	https://flox.dev/docs/concepts/packages-and-catalog
Custom Catalog	The user or organization that owns it	`flox publish`	https://flox.dev/docs/concepts/packages-and-catalog

Custom catalogs can be public or private, and all catalogs are consumed with the same flox search, flox show and flox install commands (https://flox.dev/docs/concepts/packages-and-catalog). The catalog can also be browsed at https://hub.flox.dev/packages (https://flox.dev/docs/concepts/packages-and-catalog).

How big is it

The sources disagree, so quote the page, not a round number. The home page says “215k+prebuilt packages in the catalog” (https://flox.dev/). The secure-software page says a “versioned, curated collection of 215,000 packages” (https://flox.dev/secure-software-by-construction/). The CUDA page says “over190,000+ other packages in the Flox catalog” (https://flox.dev/cuda/). None of the three pages carries a date, so the as-of date is unsettled [verify]. Say: “Flox’s own site cites roughly 215,000 packages; I will confirm today’s count with flox search.” (the figures are from the three URLs above).

Search, show, pkg-path

flox search “queries the Flox Catalog and does not require a FloxHub account” (https://flox.dev/docs/man/flox-search). It is fuzzy, matching “some portion of the pkg-path or description”, returns at most 10 results by default, and -a returns all; --json gives structured output (https://flox.dev/docs/man/flox-search). The pkg-path is the package’s location in the catalog, for example ripgrep or python310Packages.pip, and it is what lands in the manifest [install] table (https://flox.dev/docs/man/flox-search).

flox show <pkg-path> prints the description, outputs (defaults marked by *) and available versions (https://flox.dev/docs/man/flox-show). Its documented example lists ripgrep@13.0.0 and ripgrep@14.1.0 (https://flox.dev/docs/man/flox-show).

A package carries this metadata: pkg-path, version, license, unfree, broken and outputs (https://flox.dev/docs/concepts/packages-and-catalog).

Versions and history

Constrain a version with version in the manifest: it takes an exact version or a semver range with qualifiers such as ^ and >=, and version = "1.2" selects the latest in that range (https://flox.dev/docs/man/manifest.toml). Old versions exist because the Base Catalog “contains historical metadata (such as versions and system support over time)” (https://flox.dev/docs/concepts/base-catalog).

Freshness: Flox ingests the equivalent of nixos-unstable daily, so a package that has landed on nixos-unstable should appear in the Base Catalog within a day (https://flox.dev/docs/concepts/base-catalog). Flox evaluates legacyPackages.<system>.* plus a few explicit paths (https://flox.dev/docs/concepts/base-catalog).

Stability levels

Flox keeps four branches of its nixpkgs fork (https://flox.dev/docs/concepts/base-catalog). Retention is from the same page.

Stability	Reset schedule	Tags retained
`unstable`	Reset to upstream `unstable` daily	180 (6+ months daily)
`staging`	Each Saturday	156 (3 years weekly)
`stable`	First Saturday of the month	60 (5 years monthly)
`lts`	First Saturday in January and July	12 (6 years bi-annual)

(All rows: https://flox.dev/docs/concepts/base-catalog.) Pick a stability per package group under [pkg-groups], or for all groups with options.stability; if neither is set the default is currently unstable (https://flox.dev/docs/concepts/package-groups).

Retention caveat: “Existing lockfiles save the metadata and will work forever”, but a later flox update on a pinned version “may” fail to resolve, which the page calls very unlikely in practice (https://flox.dev/docs/concepts/base-catalog). It also says weekly captures keep “every version in the past 3 years” available (https://flox.dev/docs/concepts/base-catalog).

Package groups and conflict resolution

Each package in a group resolves against the same nixpkgs Git commit, which Flox calls a catalog revision (https://flox.dev/docs/concepts/package-groups). Packages with no pkg-group fall into the implicit toplevel group (https://flox.dev/docs/concepts/package-groups).

The docs’ own example: pinning openssl v1.1.1q (June 2022) next to curl v8.18.0 (January 2026) fails with “resolution failed: constraints for group ‘toplevel’ are too tight”, and the fix is openssl.pkg-group = "legacy" (https://flox.dev/docs/concepts/package-groups).

[install]
openssl.pkg-path = "openssl"
openssl.pkg-group = "legacy"
curl.pkg-path = "curl"

The resolver walks catalog revisions of the group’s stability, newest first, until one satisfies every package across all target systems, then writes the result to manifest.lock (https://flox.dev/docs/concepts/package-groups). The lock priority field defaults to 5 and resolves file conflicts, where a lower value wins (https://flox.dev/docs/concepts/package-groups).

Say: “Start flat. When the resolver says a group is too tight, move the one stubborn package into its own group.” Ask: “Which package needs the old version, and does anything else link against it?”

CUDA

Flox “publishes pre-built CUDA packages under the flox-cuda namespace” (https://flox.dev/docs/concepts/cuda-catalog-and-cache). It names itself as one of the providers NVIDIA works with to redistribute CUDA libraries and runtime packages (https://flox.dev/docs/concepts/cuda-catalog-and-cache). Install with flox install flox-cuda/python3Packages.torch (https://flox.dev/docs/concepts/cuda-catalog-and-cache).

Why it matters: most cudaPackages are marked unfree, so nixpkgs does not normally publish them to cache.nixos.org, and PyTorch or MAGMA can “exhaust memory or disk space” when built from source (https://flox.dev/docs/concepts/cuda-catalog-and-cache). Nix users can use the same pre-built paths from https://cache.flox.dev (https://flox.dev/docs/concepts/cuda-catalog-and-cache). The page flags that the cache “depends on the voluntary work” of the nixpkgs CUDA maintainers, which is worth repeating to a risk-minded buyer (https://flox.dev/docs/concepts/cuda-catalog-and-cache). Tutorial: https://flox.dev/docs/tutorials/cuda.

flox build

Two ways to define builds (https://flox.dev/docs/concepts/builds):

Manifest builds: use “tools and commands you’re already familiar with”, with “a reasonable amount of reproducibility” (https://flox.dev/docs/concepts/builds).
Nix expression builds: “for truly reproducible builds” and for modifying existing packages (https://flox.dev/docs/concepts/builds).

flox build runs every build, or those you name, and leaves a result-<name> symlink in the project root (https://flox.dev/docs/concepts/builds). A build runs on your own machine, so it only produces your own system (aarch64-darwin, x86_64-linux, etc); for several platforms, run builds on several machines, for example in CI (https://flox.dev/docs/concepts/builds).

Sandbox modes

The manifest sandbox option for a build takes four values (https://flox.dev/docs/man/manifest.toml):

Mode	Behavior per the manifest reference	Source
`off`	Runs in a subshell, like running commands in `flox activate`	https://flox.dev/docs/man/manifest.toml
`warn`	As `off`, but warns on each file read outside the package closure	https://flox.dev/docs/man/manifest.toml
`enforce`	As `warn`, but access outside the closure is denied and the build fails	https://flox.dev/docs/man/manifest.toml
`pure`	No network, only files under version control, so git is required	https://flox.dev/docs/man/manifest.toml

The default is off, run in the repository root, which allows incremental builds (https://flox.dev/docs/man/flox-build). Gotcha: pure builds on Linux cannot reach the network, but on macOS “will be able to access the network” (https://flox.dev/docs/man/flox-build). sandbox-allow lists paths a warn or enforce build may read without complaint (https://flox.dev/docs/man/manifest.toml).

Nix expression builds

These are files in .flox/pkgs/ written in the Nix language, and the environment “doesn’t need to have any packages installed” (https://flox.dev/docs/concepts/nix-expression-builds). .flox/pkgs/hello.nix builds a package named hello (https://flox.dev/docs/concepts/nix-expression-builds). Files there must be tracked by git (git add is enough) (https://flox.dev/docs/concepts/nix-expression-builds). They use a catalog-supplied nixpkgs revision, the latest of the default stability unless --stability is passed (https://flox.dev/docs/concepts/nix-expression-builds).

import-nixpkgs

flox build import-nixpkgs <installable> copies a nixpkgs package definition to .flox/pkgs/<package>/default.nix so you can modify it, patch it or make variants (https://flox.dev/docs/man/flox-build-import-nixpkgs). --force overwrites an existing file (https://flox.dev/docs/man/flox-build-import-nixpkgs). Expressions can also depend on packages other people published through a catalogs argument; cross-user sharing on public FloxHub is “not yet available” and needs Flox on-prem (https://flox.dev/docs/concepts/catalog-imports).

flox publish

flox publish <name> uploads a build to your private catalog (https://flox.dev/docs/concepts/publishing). Preconditions (https://flox.dev/docs/concepts/publishing):

The environment is tracked in a git repository.
Tracked files are clean.
A remote exists and the current revision is pushed.
For a manifest build, at least one package in the toplevel group (https://flox.dev/docs/man/flox-publish).

Flox clones the repo to a temporary directory and runs a clean flox build before uploading (https://flox.dev/docs/concepts/publishing). Metadata goes to Flox servers; the package goes to a Catalog Store, which Flox provides by default, or an organization can bring “an S3-compatible storage provider” and then packages are never stored by Flox (https://flox.dev/docs/concepts/publishing). Published packages are prefixed with the owner, such as myuser/hello (https://flox.dev/docs/concepts/publishing). Sharing with colleagues needs an organization and flox publish --org <organization>, marked as a Flox for Teams paid feature (https://flox.dev/docs/concepts/publishing).

Say: “Your private build and the open-source catalog install with the same command.” Ask: “Who needs to consume the internal packages, and where must the artifacts live?”

← Environments and the manifest · CLI, services, CI and tokens →