NAME
flox-run - run a command from a Flox Catalog packageSYNOPSIS
DESCRIPTION
Run a command from a Flox Catalog package without creating an environment.flox run is designed for one-off invocations. It resolves the
requested package from the Flox Catalog, downloads its store paths, and
executes the command directly — no flox init, flox install, or
environment cleanup needed.
Specifying the Package
When-p/--package is omitted, flox run looks up the command name
in the Flox Catalog and resolves the package automatically:
-p:
curl,
python3Packages.requests).
Disambiguation
When several packages provide the same command,flox run prompts for a
selection (up to 10 candidates are listed). The selection is stored as a
saved preference, so later runs of the same command resolve silently.
Only a selection made at the prompt is saved; silent resolutions and
-p overrides never write a preference. Use --reselect <command> to
forget the saved preference and choose again.
Without a terminal, flox run never prompts: it prints the candidate
list to stderr and exits, suggesting --package to specify the package.
Flags Before and After the Command
flox run uses POSIX stop-at-first-positional parsing: flags before
-- belong to flox run; everything after -- is passed to the
command verbatim.
Always use -- to separate the flox flags from the command:
--, flags that look like options could be claimed by the wrong
side of the boundary — for example,
flox run -p curl curl -sL http://example.com passes -sL to curl,
but in flox run curl -p curl -- curl ... the -p is consumed by
curl, leaving flox without a package of its own.
--version caveat: Flox intercepts --version from the full
argument list before parsing. Always use -- so --version reaches the
command:
Command Lookup
flox run looks up the command strictly inside the resolved package’s
output directories: bin/ first, then sbin/ (bin/ wins if both
contain the command). The file must be a regular file with an executable
bit set.
There is no fallback to the caller’s PATH. If the command is not found
in the package, flox run exits with an error.
Exec Semantics
flox run replaces the flox process with the invoked command via
exec. The caller’s PID becomes the command, signals go directly to it,
and the shell sees the command’s exit code. Stdin, stdout, and stderr
are inherited unmodified.
Caching
Downloaded store paths are registered as GC roots under$FLOX_CACHE_DIR/run-gc-roots/. Repeated invocations of the same
package skip the download step.
OPTIONS
Run Options
-p <package>, --package <package>The Flox Catalog package that provides the command. Optional: when omitted, the package is resolved from the command name (see “Specifying the Package”). Accepts plain package names (e.g.
curl, ripgrep) and
custom catalog packages (e.g. mycatalog/vim). Version constraints
(@) and output selectors (^) are not supported in this release.
--reselectForget the saved package preference for
<command>, resolve it again
(prompting when multiple packages provide it), and run it with any
<arguments>. Cannot be combined with --package, which bypasses the
prompt. Clearing a command that has no saved preference is not an error.
-- <command> [<arguments>]The command to run and any arguments to pass to it. Use
-- to separate
flox flags from the command and its arguments.
General Options
-h, --helpPrints help information. The following options can be passed when running any
flox subcommand
but must be specified before the subcommand.
-v, --verboseIncrease logging verbosity. Invoke multiple times for increasing detail.
-q, --quietSilence logs except for errors.
EXAMPLES
Run a command:LIMITATIONS
The following features are not yet supported and will be available in a future release:- Version constraints:
flox run -p curl@8.0 -- curl … - Output selectors:
flox run -p foo^dev …
Binary cache requirement
flox run fetches packages by store path using substitution only. It
does not evaluate Nix expressions or build packages from source unless
the binary cache does not have the package. A package must have a
pre-built binary available in the Nix binary cache, or be buildable from
source.
Packages that require building from source — including those with unfree
licenses that are not pre-cached — cannot be substituted directly.
flox run will build such packages from source automatically,
displaying a progress indicator while the build runs. Press Ctrl-C to
cancel if you do not want to wait. Built packages are stored in a
temporary GC root that is removed when the command exits. Use
flox install to add a package to a persistent environment instead.
SEE ALSO
flox-activate,
flox-install,
flox-search