Skip to content
Get Started

Publish custom packages

We've previously learned how to share environments. In short: this is done by pushing your environment (with flox push) to your floxmeta repository.

We've also learned how to build a custom package and now it is time to share it. We can share a package by publishing it to a flox channel to which our friends and colleagues can subscribe.

Channels solve the unfortunate requirement of Nix to access and evaluate Nix source code in order to install a package. Like your floxmeta repository, a flox channel is simply a repository you push to. By convention, we call this repository floxpkgs. Whether channels are public or private depends on whether the repository is public or private.

Let's look at an example of how we can publish a package.

If you haven't already, please install flox before continuing.

flox publish command is experimental

While the flox publish command is working, we know that there is a lot we need to do to make it more appealing to use.

We wrote this tutorial with the intention to showcase the concept behind the command.

1. Example package

To be able to publish a package we need a repository with a flox package. For this example we will use the work we did in the previous tutorial (Custom package).

Let's clone the floxified branch from our hello-python example where the build recipe for our package already exists. 

$ git clone https://github.com/flox-examples/hello-python
$ cd hello-python

$ flox build # (1)!
warning: not writing modified lock file of flake 'git+file:///home/USER/dev/hello-python'
...
• Added input 'flox-floxpkgs/tracelinks/flox-floxpkgs':
    follows 'flox-floxpkgs'

$ ./result/bin/hello
Hello world!
  1. Let's build a package to make sure our example package is ready to be published.

2. flox publish - publish package to a channel

Once the package builds successfully, it can be published to a flox channel.

$ flox publish \ # (1)! \
    --attr packages.aarch64-linux.hello-python \ # (2)! \
    --build-repo git@github.com:flox-examples/hello-python.git \ # (3)! \
    --publish-system aarch64-linux  \ # (4)! \
    --channel-repo git@github.com:flox-examples/floxpkgs.git \ # (5)! \
    --upload-to s3://flox-examples \ # (6)! \
    --key-file /path/to/binary_cache_secret_key \ # (7)! \
    --download-from https://examples-cache.floxdev.com # (8)! \
    --stability unstable # (9)!

  1. If the flox publish command is run without any command line options, an interactive menu with open, asking you to provide the required options.

    For the purpose of this tutorial we will provide options via command line in order to describe them.

  2. The attribute path of the package we want to publish.

  3. The repository of the build recipe for the package we are publishing.

    The format is any valid git repository url or a Nix installable.

  4. The system / platform for which we are publishing.

  5. The flox channel repository to which we want to publish our package.

    The enduser will need to subscribe to this repository.

  6. (Optional) The binary cache to upload the build artifacts to.

  7. (Optional) The binary cache private signing key.

    Every build artifact can be signed to improve security.

  8. (Optional) The binary cache url to download the build artifacts, if it is different from the --upload-to.

  9. (Default: stable) The stability to publish under.

If the channel repository (flox-examples/floxpkgs) does not exist, it will be created for you.

3. flox channels - list subscribed channels

Before we subscribe to any channel let us first explore our existing channels. After a fresh flox installation these are the flox channels you are automatically subscribed to:

$ flox channels                                                                                                   \
                                                                                                                  \
      CHANNEL    │ TYPE │               URL                                                                       \
  ───────────────┼──────┼──────────────────────────────────                                                       \
    flox         │ flox │ github:flox/floxpkgs/master # (1)! \
    nixpkgs-flox │ flox │ github:flox/nixpkgs-flox/master # (2)!

  1. The channel where you can find latest releases of flox itself, including pre-releases.

  2. The channel where you can find all the packages from upstream NixOS/nixpkgs.

    nixpkgs-flox is a floxified version of nixpkgs.

4. flox subscribe - subscribe to a channel

To be able to use a package from a channel, we need to subscribe to that channel.

$ flox subscribe examples github:flox-examples/floxpkgs
subscribed channel 'examples'

When listing our channels we can now see that the examples channel is listed.

$ flox channels

      CHANNEL    │ TYPE │               URL
  ───────────────┼──────┼──────────────────────────────────
    examples     │ user │ github:flox-examples/floxpkgs
    flox         │ flox │ github:flox/floxpkgs/master
    nixpkgs-flox │ flox │ github:flox/nixpkgs-flox/master

Once a user subscribes to a channel, they can search for packages in that channel.

$ flox search hello-python
examples.hello-python - An example of a flox package.

We can also install it to a flox environment.

$ flox install examples.hello-python
Installed 'examples.hello-python' package(s) into 'default' environment.

$ flox activate -- hello-python
Hello world!

5. flox unsubscribe - unsubscribe from a channel

When you no longer wish to use packages from a certain channel you can always unsubscribe from that channel.

$ flox unsubscribe examples
unsubscribed from channel 'examples'

The package you installed to one of your environments from a channel you unsubscribed from will still continue to work. But upgrading that package will fail.

Where to next?