Software environments and packages

When Trailer generates an image for you, the packages and environments you request are built with pixi, a fast package and environment manager. This page explains what pixi is, why Trailer uses it, and how the choices you make on the image form turn into software inside your workspace.

What pixi is

pixi is a package and environment manager that installs software from the conda-forge ecosystem (and other conda channels) as well as from PyPI. Two things make it a good fit for building images:

• Reproducible resolution. From the packages you ask for, pixi works out the complete set of dependencies, including everything they pull in, and installs exactly that. Pinning versions gives you the same result on every build.
• Multiple environments in one image. A single image can hold several named, isolated environments. For example a data environment with Python and numeric libraries alongside a web environment with a different toolchain, without the two interfering.
• Very fast. For PyPI packages pixi uses uv under the hood, a resolver and installer written in Rust that is dramatically faster than the traditional Python tooling. Resolving and installing even large scientific stacks stays quick, which keeps image builds short.

This is the same idea as a conda or virtual environment, resolved and installed for you.

Where it applies

pixi is used whenever Trailer generates the image for you. This covers both regular Linux images built in Generate Dockerfile mode and Windows VDI images. The difference is only in when the environments are installed:

• Linux images: pixi resolves and installs your environments while the image is being built, so they are already present the moment a workspace starts.
• Windows VDI images: the environments cannot be installed while the image is prepared, because that step runs on a Linux build host while the packages themselves are Windows packages. Instead your selections are placed inside the image, and pixi resolves and installs them the first time the Windows desktop boots. That first boot takes a little longer. Later boots are unaffected.

pixi does not apply to the Pull an image or Write Dockerfile modes, where you provide the image or its build steps yourself.

Defining environments and packages

On the Create Image form, the Python packages and environments section is where this happens. For each named environment you choose:

• Conda packages, from conda-forge or another conda channel.
• PyPI packages.

Each package can be left unconstrained or pinned to an exact version or a range. When the image builds, Trailer hands your selections to pixi, which resolves and installs every environment into the image.

Package versions

Every package has a version control next to it. It offers a specifier and a value. The specifier decides how the value is interpreted:

Specifier	Meaning	Result
Exact	Only this version	==1.2.3
Minimum	This version or newer	>=1.2.3
Maximum	This version or older	<=1.2.3
Exclude	Any version except this one	!=1.2.3
Compatible	This version up to the next minor	~=1.2.3 (that is, >=1.2.3, <1.3.0)
Unconstrained	Any version, usually the newest available	*
Custom	Whatever you type, passed through unchanged	your exact text

The value field is a combobox that lists the versions the package publishes, but it also accepts a value you type yourself. The list shows a batch of the most recent versions rather than the package’s entire history, so if the version you want is older than what appears, just type it in. If what you type is not one of the listed versions, it is kept as a Custom version and sent to the resolver exactly as written. This is how you express things the fixed specifiers do not cover, for example a wildcard like 3.12.* or a full range like >=1.2.3, <2.0.0.

Because a custom value is passed through verbatim, it must be valid version syntax for the package’s source (conda for conda packages, PyPI for PyPI packages). An invalid string is not corrected for you and surfaces as a resolve error when the image builds.

Using an environment at runtime

An image can hold more than one environment, so each command needs to know which one to run in. A startup application ties a command to an environment: the command then runs with that environment’s packages on its path. A workspace can run several commands at once, each in the environment it was assigned. This works the same way on Linux and Windows VDI images, even though a Windows image installs its environments on first boot rather than during the build.

If you open a shell in a workspace and want an environment active there too, run your command through the environment the same way its startup command does.

The glibc requirement

This applies to Linux images. Conda-forge packages are built against the standard GNU C library (glibc), so a pixi environment can only be activated on a glibc base image, such as an Ubuntu- or Debian-based image. On a base image that uses a different C library (Alpine and other musl-based images), environments cannot be activated. This is why an image that needs to run more than one startup command must use a glibc base image: keeping several commands running at once relies on an activated environment. See the note on the Create Image page.

Related pages

• Create Image - the form where environments and packages are defined
• Workspace Logs - output from the commands your environments run