name: pixi
description: Comprehensive guide for using Pixi, a fast and reproducible package management tool for Python, Rust, C/C++, and other languages. Use when (1) Managing Python project dependencies and environments, (2) Setting up reproducible development environments with conda and PyPI packages, (3) Creating cross-platform task runners and build pipelines, (4) Managing multiple isolated environments for testing and development, (5) Installing and managing global CLI tools, (6) Building and packaging conda packages, (7) Working with mixed conda and PyPI dependencies, (8) Setting up CI/CD pipelines with reproducible environments
metadata:
short-description: Fast and reproducible package management tool

Pixi Package Manager

Pixi is a fast, modern, and reproducible package management tool that combines conda and PyPI package management with built-in task running and environment management.

Quick Start

Installation

# Linux & macOS
curl -fsSL https://pixi.sh/install.sh | sh

# Windows
powershell -ExecutionPolicy Bypass -c "irm -useb https://pixi.sh/install.ps1 | iex"

Restart your terminal after installation.

Create a Project

# Initialize a new workspace
pixi init my-project
cd my-project

# Add dependencies
pixi add python
pixi add numpy
pixi add --pypi requests

# Run commands
pixi run python -c "import numpy; print(numpy.__version__)"

# Enter environment shell
pixi shell

Core Workflows

Project Management

Initialize workspace:

pixi init [project-name]
pixi init --format pyproject  # Use pyproject.toml format

Add dependencies:

pixi add python ">=3.11"
pixi add numpy pandas
pixi add --pypi requests flask  # Add PyPI packages
pixi add --feature test pytest  # Add to specific feature
pixi add --platform linux-64 glibc  # Platform-specific

Remove dependencies:

pixi remove numpy
pixi remove --feature test pytest

Update dependencies:

pixi update              # Update within constraints
pixi upgrade             # Upgrade to latest versions
pixi lock                # Regenerate lockfile only

Install environment:

pixi install                    # Install default environment
pixi install --environment test # Install specific environment
pixi install --frozen           # Install from lockfile only (no updates)
pixi install --locked           # Install only if lockfile is up-to-date

Running Commands

Execute tasks or commands:

pixi run python script.py
pixi run --environment test pytest
pixi run task-name
pixi run --environment dev task-name

Activate shell:

pixi shell
pixi shell --environment test

One-off commands:

pixi exec python --version
pixi exec --spec "python=3.12" python --version

Task Management

Define tasks in pixi.toml:

[tasks]
# Simple task
hello = "echo Hello World"

# Task with dependencies
build = { cmd = "cargo build", depends-on = ["fmt", "lint"] }

# Task with environment variables
run = { cmd = "python main.py", env = { DEBUG = "true" } }

# Task with caching
compile = { 
    cmd = "gcc -o output input.c", 
    inputs = ["input.c"], 
    outputs = ["output"] 
}

# Task with arguments
greet = { 
    cmd = "echo Hello, {{ name }}!", 
    args = [{ arg = "name", default = "World" }] 
}

Manage tasks:

pixi task add build "cargo build"
pixi task add test "pytest" --depends-on build
pixi task add lint "ruff check ." --feature dev
pixi task list
pixi task remove build

Run tasks with arguments:

pixi run greet Alice
pixi run build production linux-64

Multiple Environments

Using features and environments:

# Default dependencies
[dependencies]
python = ">=3.11"

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

[feature.lint.dependencies]
ruff = "*"
mypy = "*"

[feature.dev.dependencies]
ipython = "*"

# Define environments
[environments]
default = []                    # Just default feature
test = ["test"]                 # default + test
dev = ["test", "lint", "dev"]   # Combine multiple features

Work with environments:

pixi add --feature test pytest
pixi run --environment test pytest
pixi shell --environment dev
pixi list --environment test
pixi install --environment prod

Solve groups (ensure shared versions):

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

Global Tools

Install global CLI tools:

pixi global install gh nvim ipython btop ripgrep
pixi global install terraform ansible k9s

Manage global installations:

pixi global list
pixi global add nvim ripgrep  # Add to existing global environment
pixi global update
pixi global uninstall gh
pixi global sync  # Sync with global manifest

Manifest Structure

Basic pixi.toml:

[project]
name = "my-project"
version = "0.1.0"
channels = ["conda-forge"]
platforms = ["linux-64", "osx-64", "win-64"]

[dependencies]
python = ">=3.11"
numpy = ">=1.21"

[pypi-dependencies]
requests = ">=2.25"
fastapi = { version = ">=0.100", extras = ["all"] }

[tasks]
test = "pytest"
dev = "uvicorn main:app --reload"

[environments]
default = ["test"]

Package specifications:

# Version constraints
python = ">=3.11,<3.13"     # Range
numpy = "==1.21.0"          # Exact
pytorch = "2.0.*"           # Wildcard

# Channel specification
pytorch = { version = "2.0.*", channel = "pytorch" }

# Build string
numpy = { version = ">=1.21", build = "py311*" }

# PyPI with extras
pandas = { version = ">=1.0", extras = ["dataframe", "sql"] }

# Git dependencies
package = { git = "https://github.com/user/repo.git", rev = "abc123" }

# Local editable
my-pkg = { path = ".", editable = true }

Configuration

Project configuration (.pixi/config.toml):

# Pin strategy
pinning-strategy = "semver"  # or "exact-version", "major", "minor", "latest-up"

# Shell behavior
[shell]
change-ps1 = true

Global configuration (~/.pixi/config.toml):

# Default channels for new projects
default-channels = ["conda-forge"]

# PyPI configuration
[pypi-config]
index-url = "https://pypi.org/simple"
extra-index-urls = ["https://custom-index.com/simple"]

# Proxy configuration
[proxy-config]
https = "http://proxy.example.com:8080"

Configure via CLI:

pixi config set pinning-strategy semver
pixi config set shell.change-ps1 false
pixi config list
pixi config edit

Lockfile Management

Understanding lockfiles:
- pixi.lock ensures reproducible environments
- Contains exact package versions and build info
- Should be committed to version control
- Automatically updated when dependencies change

Lockfile commands:

pixi lock                    # Generate/update lockfile
pixi install --frozen        # Use lockfile as-is (no updates)
pixi install --locked        # Install only if lockfile matches manifest

Common Patterns

Python Project Setup

[project]
channels = ["conda-forge"]
platforms = ["linux-64", "osx-64", "win-64"]

[dependencies]
python = ">=3.11"

[pypi-dependencies]
fastapi = "*"
uvicorn = { extras = ["standard"], version = "*" }
# Editable install
my-package = { path = ".", editable = true }

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

[tasks]
dev = "uvicorn main:app --reload"
test = "pytest"
lint = "ruff check . && mypy ."

[environments]
default = ["test", "lint"]

C/C++ Project

[dependencies]
cmake = "*"
ninja = "*"

[target.linux-64.dependencies]
gcc_linux-64 = "*"

[target.osx-64.dependencies]
clang_osx-64 = "*"

[tasks]
configure = "cmake -S . -B build -G Ninja"
build = { cmd = "cmake --build build", depends-on = ["configure"] }
test = { cmd = "ctest --test-dir build", depends-on = ["build"] }

Multi-Version Testing

[feature.py39.dependencies]
python = "3.9.*"
[feature.py310.dependencies]
python = "3.10.*"
[feature.py311.dependencies]
python = "3.11.*"

[environments]
py39 = ["py39", "test"]
py310 = ["py310", "test"]
py311 = ["py311", "test"]

Platform-Specific Configuration

[target.linux-64.dependencies]
glibc = "2.28"

[target.osx-arm64.dependencies]
mlx = "*"

[target.win-64.dependencies]
msmpi = "~=10.1.1"

[target.unix.tasks]
clean = "rm -rf build/"

[target.win.tasks]
clean = "rmdir /s /q build"

Environment Activation

Activation scripts:

[activation]
scripts = ["setup.sh"]
env = { 
    MY_VAR = "value",
    PATH = "$PIXI_PROJECT_ROOT/bin:$PATH"
}

[target.win-64.activation]
scripts = ["setup.bat"]

In shell:

pixi shell
# Environment is automatically activated
# Type 'exit' to leave

Utility Commands

# Information
pixi info                    # Show workspace info
pixi list                    # List installed packages
pixi list --environment test # List packages in environment
pixi tree                    # Show dependency tree
pixi tree --invert package   # Show reverse dependencies

# Search
pixi search numpy            # Search for packages

# Cleanup
pixi clean                   # Remove environments
pixi clean --environment test
pixi clean cache             # Clear package cache

# Authentication
pixi auth login              # Login to private channels
pixi auth logout

# Completion
pixi completion --shell bash > ~/.bash_completion
pixi completion --shell zsh > ~/.zsh_completion

Troubleshooting

Environment out of sync:

pixi install  # Automatically fixes and updates
pixi reinstall  # Force reinstall

Lockfile issues:

rm pixi.lock  # Delete and regenerate
pixi lock     # Regenerate lockfile

Clear cache:

pixi clean cache

Check configuration:

pixi info -vvv  # Show all configuration locations
pixi config list

Best Practices

1. Commit lockfiles: Always commit pixi.lock to version control
2. Use features: Organize dependencies by purpose (test, lint, dev)
3. Use solve-groups: When environments need shared versions
4. Task caching: Specify inputs and outputs for faster rebuilds
5. Platform-specific: Use target tables for cross-platform differences
6. Prefer conda: Use conda packages when available (more stable, binary deps)
7. Editable installs: Use editable = true for local packages

References

For detailed information, see:
- manifest.md - Complete manifest reference
- commands.md - Full command reference
- advanced.md - Advanced features and patterns