From edd10b61508759c3a522548f786c28e62787e59a Mon Sep 17 00:00:00 2001 From: Isaac Karrer Date: Fri, 18 Sep 2026 11:30:12 -0500 Subject: [PATCH] docs(builds): correct where a Nix expression build's nixpkgs comes from MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The page said Flox would "attempt to produce a build that is compatible with any packages in the 'toplevel' package group", which stopped being true in flox/flox#4708: a Nix expression build now resolves the catalog's current stable revision, or the one named with --stability, and the environment's own packages play no part in it. Say what decides the revision now, and name the consequence that replaces the old compatibility promise — an environment holding both kinds of build builds them against two different package sets, which `flox build` warns about and `flox upgrade` resolves. ECO-59 --- concepts/nix-expression-builds.mdx | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/concepts/nix-expression-builds.mdx b/concepts/nix-expression-builds.mdx index aa0e9c6..325628e 100644 --- a/concepts/nix-expression-builds.mdx +++ b/concepts/nix-expression-builds.mdx @@ -9,7 +9,11 @@ See the [builds concept](/concepts/builds) page for an overview of the different Nix expression builds are defined by creating files in the `.flox/pkgs/` directory of a Flox environment. These expressions are written in the Nix language, which is incredibly powerful and results in truly reproducible builds. -The environment that contains the builds doesn't need to have any packages installed because all of the build's dependencies are defined within the expression, but if there are any packages installed then Flox will attempt to produce a build that is compatible with any packages in the "toplevel" [package group](/man/manifest.toml#package-descriptors). +The environment that contains the builds doesn't need to have any packages installed, because all of the build's dependencies are defined within the expression. + +The base package set a Nix expression build resolves against comes from the catalog: the current `stable` revision of nixpkgs, or the revision named with [`--stability`](/man/flox-build#options). The environment's own packages don't determine it, so installing or upgrading packages never changes which nixpkgs your expressions build against. + +Manifest builds work the other way around — they build inside the environment, against the package set the [lockfile](/concepts/environments#manifestlock) pins. An environment containing both kinds of build therefore builds them against two different package sets, which matters when a Nix expression build and a manifest build are expected to link against the same libraries. `flox build` warns you when the two have diverged; run `flox upgrade` to move the environment's packages to the current revision. ## Defining builds