Installing Dependencies with Nix

Basic Usage

To install binary dependencies during the prepare or run stage of your CI pipeline, Codesphere supports the Nix Package Manager. Nix is chosen over traditional Linux Package Managers like apt or yum for a number of reasons:

• Nix does not require root privileges to install packages, since it does not modify the root file system.
• Nix allows you to have multiple versions of a package installed at the same time, which is useful for testing and development.
• Nix provides a declarative way to specify your dependencies and their versions, which makes it ideal to use in CI pipelines where reproducibility is important.
• Nix uses Channels to manage package versions, which allows you to easily switch between different versions of a package or update to the latest version.

Nix offers a large collection of pre-built packages at search.nixos.org/packages.

The easiest way to install a package via Nix is to use the nix-env command.

nix-env -iA nixpkgs.<PACKAGE_NAME>

For example, to install the cowsay tool into your Workspace, search for cowsay in the Nix packages and copy the nix-env command for non NixOS systems, i.e.

nix-env -iA nixpkgs.cowsay

Nix installs packages into the /nix/store directory in a versioned path, which is isolated from the rest of the filesystem. When you install a package, it creates a symlink to the executable in the /nix/store directory. In Codesphere, the Nix store is shared between all Reactives automatically, so when installing Nix packages in the prepare stage, they are also available in the run stage of every service without needing to install them again.

You can list installed packages with the -q option:

nix-env -q

To update a specific package, use the -u option:

nix-env -uA nixpkgs.cowsay

To update all packages installed via Nix, simply run:

nix-env -u '*'

If needed, you can remove packages with the -e option:

nix-env -e cowsay

Nix Documentation

Find the full documentation for nix-env in the Nix Manual

Nix Channels and Package Versions

Nix manages the version of each package through Nix channels. If you need to install a specific version of a package, you can specify the channel in your nix-env command. For example, to install a package from the nixos-25.11 channel, you can run:

nix-channel --add https://nixos.org/channels/nixos-25.11 nixos-25_11
nix-channel --update nixos-25_11

Then, you can install the package from that channel:

nix-env -iA nixos-25_11.<PACKAGE_NAME>

You can verify which channels you have added with the following commands:

nix-channel --list

Nix Channels

Codesphere uses the nixos-unstable channel by default, which is a rolling release, updated frequently with the latest package versions. It's fine to use this channel for most use cases, but if you require more stability or specific package versions, you can switch to a different channel as described above.

Creating Dev Environments with Nix Shells

When using nix-env, dependencies are installed "globally" in the scope of a Codesphere Workspace. As a signature feature, Nix also allows to create isolated environments using the nix-shell command. When using Nix shells, the dependencies installed are ephemeral and specific to the shell session, which allows for better reproducibility and co-existence of different environments.

The simplest way to create a Nix shell is to run nix-shell with the -p option followed by the packages you want to include in the shell environment. For example, to create a Nix shell with Python 3 and the NumPy package, you can run:

nix-shell -p python3 python3Packages.numpy

For more reproducible environments, you can define a shell.nix file. This file specifies the dependencies and environment variables needed for your project. For example, to create a Nix shell with the same packages, you can create a shell.nix file with the following content:

# shell.nix
{ pkgs ? import (fetchTarball "https://channels.nixos.org/nixos-25.11/nixexprs.tar.xz") {} }:

pkgs.mkShell {
  nativeBuildInputs = [ 
    pkgs.python3 
    pkgs.python3Packages.numpy 
  ];
}

To enter the Nix shell, run the following command in the directory containing the shell.nix file:

nix-shell

Pinning Channels in Nix Shells

The fetchTarball command "pins" your environment to a specific version of all Nix packages, ensuring that your build is highly reproducible. The URL can point to a specific commit on GitHub or a Nix channel URL on nixos.org.

Alternatively, you can use <nixpkgs> to refer to the channel configured on the system, which is more portable but less reproducible:

# shell.nix
{ pkgs ? import <nixpkgs> {} }:

pkgs.mkShell {
  buildInputs = [ pkgs.python3 ];
}

The Nix language allows you to define complex environments with multiple dependencies and custom configurations, which goes beyond the scope of this introduction. For more information on how to create and customize Nix shells, refer to the Nix Manual.

Nix shells in CI Pipelines

You can invoke nix-shell in your CI pipeline by using the --run option to execute a command within the shell environment. For example:

nix-shell --run "python3 my_script.py"

This will execute my_script.py with the dependencies defined in the shell.nix file available in the environment.

Usage of Native Linux Package Managers

While the Nix approach covers a large amount of popular packages, in some cases, it might not be possible to install dependencies using Nix. One reason could be that the maintainer of the package offers apt repositories but does not publish the source code so that the Nix project could rebuild them.

In Codesphere Private Cloud Installations, you can still use native Linux package managers like apt by creating custom base images that include the necessary packages without installing them on a Workspace level. See Install Guide for more details.