Skip to content

flox publish command


flox-publish - build and publish project to flox channel


flox [ <general-options> ] publish [ <options> ] [<package>]


Adds metadata to a catalog for the package identified by <package> or dynamically selected from a choice of packages in the current directory.

Prior to to submitting the metadata, it will verify that the package can be built from its upstream location and optionally sign and cache the resulting binary.

The package must be defined in a remote git repository and be referred to either directly by a git+ssh://<url>[#<package>] url or another url that can be resolved to an upstream git resource. Packages in local repositories are resolved to the current branch’s upstream branch. Packages referred to by a github:<user>/<owner>[#<package>] URL are resolved to ssh://[email protected] by default or, if --prefer-https is provided. Packages in a local repository will be built from the upstream branch. The local branch must be clean (i.e. have no uncommited changes) and must be at the same revision as its upstream.

The metadata will be published in a catalog/<system> branch on the upstream repository.


General Options

Many flox commands wrap Nix commands of the same name, and will correspondingly pass on options and arguments directly to the underlying nix invocation. For more information on the options supported by specific Nix commands please invoke flox nix <command> help.

The following options are used specifically by flox and must be specified before the <command> argument.

-v, --verbose
Verbose mode. Invoke multiple times for increasing detail.

Debug mode. Invoke multiple times for increasing detail.

-V, --version
Print flox version.

Print flox installation prefix / Nix store path. (flox internal use only.)

Force execution in flox-bash (flox internal use only.)

Development Options

The following options are supported by all Development Commands:

[(-A|--attr) <package>]
Selects package (aka “attrPath”) to be used. If not provided flox will prompt for you to select from the list of known packages.

[--stability <stability>]
Selects the set of nixpkgs to be used as a basis

Publish Options

[ --cache-url <URL> | -c <URL> ]
The URL of a binary cache location to which built package(s) should be copied.

If not provided will attempt to read the cache_url config value.

[ --public-cache-url <URL> | -s <URL> ]
The URL of a cache from which built packages will be served at installation time. This URL typically refers to the same underlying resource as specified by the --cache-url argument, but using a different transport. For example, to upload packages to a (writable, authenticated) s3:// URL, but download these packages from an (read-only, unauthenticated) endpoint.

If not provided the --public-cache-url argument will default to the public_cache_url config value, or same value as provided for the --cache-url argument.

[ --max-retries <number> ]
Number of retries if the binary is not found in the cache

If not provided, defaults to 3 retries

[ --signing-key <file> | -k <file> ]
Used for identifying the path to the private key to be used to sign packages before upload. If not provided, defaults to the signing_key config value.

Resolve github: urls to, instead of ssh://[email protected].

When invoked without arguments, will prompt the user for the required values.


Once published to a channel repository, you can then search for and use your package with the following:

  • subscribe to the channel: flox subscribe <channel> <URL>
  • search for a package: flox search -c <channel> <package>
  • install a package: flox install <channel>.<package>