pixi.toml Reference

Complete reference for the pixi.toml manifest file

The pixi.toml manifest file is the heart of a pixi workspace. It defines workspaces, packages, dependencies, tasks, environments, and more.

Overview

A pixi.toml manifest must have one of:

• [workspace] - For workspace definitions
• [project] - For workspace definitions (alias for [workspace])
• [package] - For buildable packages

Schema Validation

Add schema validation to your pixi.toml:

"$schema" = "https://pixi.sh/v0.65.0/schema/manifest/schema.json"

This enables autocompletion and validation in editors that support JSON schemas.

Workspace Configuration

[workspace]

Defines a pixi workspace (also available as [project]).

[workspace]
name = "my-workspace"
version = "0.1.0"
description = "My pixi workspace"
authors = ["Jane Doe <[e-mail]>"]
channels = ["conda-forge", "pytorch"]
platforms = ["linux-64", "osx-64", "win-64"]

name · string · required

The name of the workspace.

[workspace]
name = "my-workspace"

version · string

The version of the workspace. Should follow SemVer.

[workspace]
version = "1.2.3"

description · string

A short description of the workspace.

[workspace]
description = "A machine learning workspace"

authors · array

List of workspace authors in “Name <email>” format.

[workspace]
authors = [
  "Jane Doe <[e-mail]>",
  "John Smith <[e-mail]>"
]

channels · array · required

Conda channels to use for dependency resolution.

[workspace]
channels = ["conda-forge", "bioconda", "https://prefix.dev/my-channel"]

With priorities:

[workspace]
channels = [
  { channel = "conda-forge", priority = 0 },
  { channel = "pytorch", priority = -1 }
]

platforms · array · required

Target platforms for the workspace.

Valid platforms:

• linux-64, linux-32, linux-aarch64, linux-armv6l, linux-armv7l, linux-ppc64, linux-ppc64le, linux-riscv32, linux-riscv64, linux-s390x
• osx-64, osx-arm64
• win-64, win-32, win-arm64
• emscripten-wasm32, wasi-wasm32
• noarch

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

license · string

License identifier (SPDX format recommended).

[workspace]
license = "MIT"

license-file · path

Path to the license file.

[workspace]
license-file = "LICENSE"

readme · path

Path to the README file.

[workspace]
readme = "README.md"

homepage · url

Homepage URL.

[workspace]
homepage = "https://example.com"

repository · url

Repository URL.

[workspace]
repository = "https://github.com/example/repo"

documentation · url

Documentation URL.

[workspace]
documentation = "https://docs.example.com"

Dependencies

[dependencies]

Conda dependencies for the default environment.

[dependencies]
python = ">=3.11,<3.12"
numpy = ">=1.20"
pandas = "*"

# Table format for advanced options
pytorch = { version = ">=2.0", channel = "pytorch" }

Simple string format

[dependencies]
python = "3.11.*"
numpy = ">=1.20,<2.0"
pandas = "*"  # Any version

Table format (MatchSpec)

[dependencies]
pytorch = { version = ">=2.0", channel = "pytorch", build = "*cuda*" }
custom = { version = "1.0", channel = "https://my-channel.com" }
local = { path = "./local-package.tar.bz2" }
git = { git = "https://github.com/org/repo", branch = "main" }

Available fields:

• version - Version constraint (MatchSpec format)
• channel - Override channel for this package
• build - Build string constraint
• build-number - Build number constraint
• file-name - Exact file name
• subdir - Platform subdirectory
• md5 / sha256 - Hash verification
• path - Local package path
• url - Package URL
• git - Git repository URL
• branch / tag / rev - Git reference

[pypi-dependencies]

PyPI dependencies installed with pip.

[pypi-dependencies]
requests = ">=2.31"
flask = "==3.0.*"

# Git dependencies
mypackage = { git = "https://github.com/user/repo", branch = "main" }

# Local dependencies
local-pkg = { path = "./packages/local-pkg", editable = true }

# With extras
scikit-learn = { version = ">=1.3", extras = ["tests", "docs"] }

Version strings

[pypi-dependencies]
requests = "~=2.31.0"
flask = ">=3.0,<4.0"
django = "==4.2.*"

Follows PEP 440 version specifiers.

Git dependencies

[pypi-dependencies]
# Branch
mylib = { git = "https://github.com/user/mylib", branch = "develop" }

# Tag
other = { git = "https://github.com/user/other", tag = "v1.0.0" }

# Commit
pkg = { git = "https://github.com/user/pkg", rev = "abc123" }

# Subdirectory
sub = { git = "https://github.com/user/mono", subdirectory = "packages/sub" }

Local dependencies

[pypi-dependencies]
# Regular install
mypackage = { path = "./packages/mypackage" }

# Editable install
dev-pkg = { path = "../dev-package", editable = true }

With extras

[pypi-dependencies]
sqlalchemy = { version = ">=2.0", extras = ["postgresql", "asyncio"] }
requests = { version = "*", extras = ["security", "socks"] }

[host-dependencies] and [build-dependencies]

Dependencies for building packages. See Build System documentation.

[host-dependencies]
python = ">=3.8"
setuptools = "*"

[build-dependencies]
c-compiler = "*"
cmake = ">=3.20"

[dev]

Source packages whose dependencies should be installed without building the package itself.

[dev]
my-package = { path = "./my-package" }

Tasks

[tasks]

Define tasks that can be run with pixi run.

[tasks]
# Simple command
test = "pytest tests/"

# With options
lint = { cmd = "ruff check src/", cwd = "src", clean-env = false }

# Multiple commands
build = ["cargo build --release", "cp target/release/bin ."]  

# With dependencies
ci = { cmd = "echo 'CI complete'", depends-on = ["test", "lint", "build"] }

# With arguments
greet = { cmd = "echo 'Hello {{ name }}'", args = ["name"] }

# Task with default argument
serve = { cmd = "python -m http.server {{ port }}", args = [{ arg = "port", default = "8000" }] }

cmd · string | array

Command to execute. Can be a string or array of commands.

[tasks]
test = "pytest"
build = ["cargo build", "cargo test"]

cwd · path

Working directory for the task.

[tasks]
docs = { cmd = "mkdocs serve", cwd = "docs" }

depends-on · array

Tasks that must run before this task.

[tasks]
build = "cargo build"
test = { cmd = "cargo test", depends-on = "build" }
deploy = { cmd = "deploy.sh", depends-on = ["build", "test"] }

With arguments:

[tasks]
format = { cmd = "ruff format {{ path }}", args = ["path"] }
check = { depends-on = [{ task = "format", args = ["src/"] }] }

env · object

Environment variables to set.

[tasks]
test = { cmd = "pytest", env = { PYTHONPATH = "src:tests" } }

clean-env · boolean · default: "false"

Run in a clean environment (only pixi-set variables).

[tasks]
isolated = { cmd = "env", clean-env = true }

args · array

Task arguments that can be passed from the command line.

[tasks]
# Simple arguments
greet = { cmd = "echo 'Hello {{ name }}'", args = ["name"] }

# With defaults
serve = { cmd = "python -m http.server {{ port }}", args = [{ arg = "port", default = "8000" }] }

# With choices
deploy = { cmd = "deploy.sh {{ env }}", args = [{ arg = "env", choices = ["dev", "prod"] }] }

Environments

[environments]

Define multiple environments with different feature combinations.

[environments]
# Simple: list of features
default = ["default", "test"]
prod = ["default"]
dev = ["default", "test", "lint", "docs"]

# Advanced: with solve groups
test = { features = ["test"], solve-group = "test" }
lint = { features = ["lint"], solve-group = "test" }

# Without default feature
custom = { features = ["custom"], no-default-feature = true }

features · array

Features to include in this environment.

[environments]
dev = { features = ["default", "test", "docs"] }

solve-group · string

Solve multiple environments together to share dependencies.

[environments]
test = { features = ["test"], solve-group = "group1" }
lint = { features = ["lint"], solve-group = "group1" }

no-default-feature · boolean · default: "false"

Exclude the default feature from this environment.

[environments]
minimal = { features = ["core"], no-default-feature = true }

Features

[feature.<name>]

Define features that can be composed into environments.

[feature.test.dependencies]
pytest = "*"
pytest-cov = "*"

[feature.test.tasks]
test = "pytest tests/"
cov = "pytest --cov=src tests/"

[feature.docs.dependencies]
mkdocs = "*"
mkdocs-material = "*"

[feature.docs.tasks]
docs = "mkdocs serve"
build-docs = "mkdocs build"

Features can have:

• dependencies - Conda dependencies
• pypi-dependencies - PyPI dependencies
• tasks - Feature-specific tasks
• channels - Override channels
• platforms - Supported platforms
• system-requirements - Platform requirements
• activation - Activation scripts/environment
• target - Platform-specific configuration

See Next

• pyproject.toml - Using pixi with Python projects
• pixi.lock - Lock file format
• [Build Configuration(/build/getting-started) - Building packages