ConfigurationLearn what you can do in the `pixi.toml` configuration.

The pixi.toml is the pixi project configuration file, also known as the project manifest.

A toml file is structured in different tables. This document will explain the usage of the different tables. For more technical documentation check crates.io.

The project table

The minimally required information in the project table is:

[project]
name = "project-name"
authors = ["John Doe <j.doe@prefix.dev>"]
channels = ["conda-forge"]
platforms = ["linux-64"]

name

The name of the project.

[project]
name = "project-name"

version (optional)

The version of the project. This should be a valid version based on the conda Version Spec. See the version documentation, for an explanation of what is allowed in a Version Spec.

[project]
version = "1.2.3"

authors

This is a list of authors of the project.

[project]
authors = ["John Doe <j.doe@prefix.dev>", "Marie Curie <mss1867@gmail.com>"]

channels

This is a list that defines the channels used to fetch the packages from. If you want to use channels hosted on anaconda.org you only need to use the name of the channel directly.

[project]
channels = ["conda-forge", "robostack", "bioconda", "nvidia", "pytorch"]

Channels situated on the file system are also supported with file paths:

[project]
channels = ["conda-forge", "file:///home/user/staged-recipes/build_artifacts"]

To access private or public channels on prefix.dev or Quetz use the url including the hostname:

[project]
channels = ["conda-forge", "https://repo.prefix.dev/channel-name"]

platforms

Defines the list of platforms that the project supports. Pixi solves the dependencies for all these platforms and puts them in the lockfile (pixi.lock).

[project]
platforms = ["win-64", "linux-64", "osx-64", "osx-arm64"]

The available platforms are listed here: link

description (optional)

This should contain a short description of the project.

[project]
description = "A simple description"

license (optional)

The license as a valid SPDX string (e.g. MIT AND Apache-2.0)

[project]
license = "MIT"

license-file (optional)

Relative path to the license file.

[project]
license-file = "LICENSE.md"

readme (optional)

Relative path to the README file.

[project]
readme = "README.md"

homepage (optional)

URL of the project homepage.

[project]
homepage = "https://pixi.sh"

repository (optional)

URL of the project source repository.

[project]
repository = "https://github.com/prefix-dev/pixi"

documentation

URL of the project documentation.

[project]
documentation = "https://pixi.sh"

The tasks table

Tasks are a way to automate certain custom commands in your project. For example, a lint or format step. Tasks in a pixi project are essentially cross-platform shell commands, with a unified syntax across platforms. For more in-depth information, check the Advanced tasks documentation. Pixi's tasks are run in a pixi environment using pixi run and are executed using the deno_task_shell.

[tasks]
simple = "echo This is a simple task"
cmd = { cmd="echo Same as a simple task but now more verbose"}
depending = { cmd="echo run after simple", depends_on="simple"}
alias = { depends_on=["depending"]}

You can modify this table using pixi task.

The system-requirements table

The system requirements are used to define minimal system specifications used during dependency resolution. For example, we can define a unix system with a specific minimal libc version. This will be the minimal system specification for the project. System specifications are directly related to the virtual packages.

Currently, the specified defaults are the same as conda-lock's implementation:

Only if a project requires a different set should you define them.

For example, when installing environments on old versions of linux. You may encounter the following error:

× The current system has a mismatching virtual package. The project requires '__linux' to be at least version '5.10' but the system has version '4.12.14'

This suggests that the system requirements for the project should be lowered. To fix this, add the following table to your configuration:

[system-requirements]
linux = "4.12.14"

The dependencies table(s)

This section defines what dependencies you would like to use for your project.

There are multiple dependencies tables. The default is [dependencies], which are dependencies that are shared across platforms.

Dependencies are defined using a VersionSpec. A VersionSpec combines a Version with an optional operator.

Some examples are:

# Use this exact package version
package0 = "1.2.3"
# Use 1.2.3 up to 1.3.0
package1 = "~=1.2.3"
# Use larger than 1.2 lower and equal to 1.4
package2 = ">1.2,<=1.4"
# Bigger or equal than 1.2.3 or lower not including 1.0.0
package3 = ">=1.2.3|<1.0.0"

dependencies

Add any conda package dependency that you want to install into the environment. Don't forget to add the channel to the project table should you use anything different than conda-forge.

[dependencies]
python = ">3.9,<=3.11"
rust = "1.72"

host-dependencies

This table contains dependencies that are needed to build your project but which should not be included when your project is installed as part of another project. In other words, these dependencies are available during the build but are no longer available when your project is installed. Dependencies listed in this table are installed for the architecture of the target machine.

[host-dependencies]
python = "~=3.10.3"

Typical examples of host dependencies are:

• Base interpreters: a Python package would list python here and an R package would list mro-base or r-base.
• Libraries your project links against during compilation like openssl, rapidjson, or xtensor.

build-dependencies

This table contains dependencies that are needed to build the project. Different from dependencies and host-dependencies these packages are installed for the architecture of the build machine. This enables cross-compiling from one machine architecture to another.

[build-depencencies]
cmake = "~=3.24"

Typical examples of build dependencies are:

• Compilers are invoked on the build machine, but they generate code for the target machine. If the project is cross-compiled, the architecture of the build and target machine might differ.
• cmake is invoked on the build machine to generate additional code- or project-files which are then include in the compilation process.

The activation table

If you want to run an activation script inside the environment when either doing a pixi run or pixi shell these can be defined here. The scripts defined in this table will be sourced when the environment is activated using pixi run or pixi shell

[activation]
scripts = ["env_setup.sh"]

The target table

The target table is a table that allows for platform specific configuration. Allowing you to make different sets of tasks or dependencies per platform.

The target table is currently implemented for the following sub-tables:

• activation
• dependencies
• tasks

The target table is defined using [target.PLATFORM.SUB-TABLE]. E.g [target.linux-64.dependencies] The platform can be any of the target platforms but must also be defined there. The sub-table can be any of the specified above.

To make it a bit more clear, let's look at an example below. Currently, pixi combines the top level tables like dependencies with the target-specific ones into a single set. Which, in the case of dependencies, can both add or overwrite dependencies. In the example below, we have cmake being used for all targets but on osx-64 a different version of python will be selected.

[dependencies]
cmake = "3.26.4"
python = "3.10"
 
[target.osx-64.dependencies]
python = "3.11"

Here are some more examples:

[target.win-64.activation]
scripts = ["setup.ps1"]
 
[target.win-64.dependencies]
msmpi = "~=10.1.1"
 
[target.win-64.build-dependecies]
vs2022_win-64 = "19.36.32532"
 
[target.win-64.tasks]
tmp = "echo $TEMP"
 
[target.osx-64.dependencies]
clang = ">=16.0.6"