Pixi Cheat Sheet

Overview

Pixi is a fast, cross-platform package manager built on top of the conda ecosystem. It provides project-level dependency management with lockfiles, task running, and multi-environment support. Pixi uses the conda-forge and other conda channels to install packages, supporting Python, R, C/C++, and system-level dependencies in a unified workflow.

Pixi is written in Rust for speed and provides a modern CLI experience similar to Cargo or npm. It creates reproducible environments using pixi.toml for configuration and pixi.lock for exact dependency pinning, making it ideal for data science, scientific computing, and cross-language projects.

Installation

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

# Windows (PowerShell)
iwr -useb https://pixi.sh/install.ps1 | iex

# Homebrew
brew install pixi

# Verify
pixi --version

Core Commands

Command	Description
`pixi init`	Initialize a new project
`pixi add <pkg>`	Add a dependency
`pixi remove <pkg>`	Remove a dependency
`pixi install`	Install all dependencies
`pixi run <cmd>`	Run command in environment
`pixi shell`	Activate environment shell
`pixi task add <name> <cmd>`	Add a task
`pixi task list`	List all tasks
`pixi list`	List installed packages
`pixi update`	Update dependencies
`pixi search <pkg>`	Search for packages
`pixi global install <pkg>`	Install tool globally

Project Setup

Initialize Project

# Create new project
pixi init my-project
cd my-project

# Initialize in existing directory
pixi init

# Initialize with specific channels
pixi init --channel conda-forge --channel bioconda

pixi.toml Configuration

[project]
name = "my-project"
version = "0.1.0"
description = "My data science project"
channels = ["conda-forge"]
platforms = ["linux-64", "osx-arm64", "osx-64", "win-64"]

[tasks]
start = "python src/main.py"
test = "pytest tests/"
lint = "ruff check src/"
notebook = "jupyter lab"

[dependencies]
python = ">=3.11"
numpy = ">=1.26"
pandas = ">=2.1"
scikit-learn = ">=1.3"
matplotlib = ">=3.8"

[feature.dev.dependencies]
pytest = ">=7.0"
ruff = ">=0.3"
jupyter = ">=1.0"

[environments]
dev = ["dev"]

Dependency Management

# Add conda packages
pixi add numpy pandas scikit-learn

# Add with version constraint
pixi add "python>=3.12"
pixi add "numpy>=1.26,<2.0"

# Add PyPI packages
pixi add --pypi requests flask

# Add to specific feature
pixi add --feature dev pytest ruff mypy

# Add platform-specific dependency
pixi add --platform linux-64 cuda-toolkit

# Remove dependency
pixi remove pandas

# Update all
pixi update

# Update specific package
pixi update numpy

# List installed packages
pixi list
pixi list --sort-by name

Tasks

# pixi.toml
[tasks]
start = "python src/main.py"
test = "pytest tests/ -v"
lint = "ruff check src/"
format = "ruff format src/"
check = { depends-on = ["lint", "test"] }
serve = { cmd = "uvicorn app:main --reload", env = { PORT = "8000" } }
train = { cmd = "python train.py", cwd = "ml/" }

# Run tasks
pixi run start
pixi run test
pixi run check

# Add tasks via CLI
pixi task add build "python -m build"
pixi task add clean "rm -rf dist/ build/"

# List tasks
pixi task list

Configuration

Multi-Environment Setup

[project]
name = "ml-pipeline"
channels = ["conda-forge"]
platforms = ["linux-64", "osx-arm64"]

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

[feature.train.dependencies]
pytorch = ">=2.1"
cuda-toolkit = "12.1.*"

[feature.serve.dependencies]
fastapi = ">=0.100"
uvicorn = ">=0.24"

[feature.dev.dependencies]
pytest = ">=7.0"
jupyter = ">=1.0"

[environments]
train = ["train"]
serve = ["serve"]
dev = ["dev", "train", "serve"]

# Run in specific environment
pixi run -e train python train.py
pixi run -e serve uvicorn app:main
pixi run -e dev pytest

Global Tools

# Install tools globally (not per-project)
pixi global install ruff
pixi global install jupyter
pixi global install pre-commit
pixi global install awscli

# List global tools
pixi global list

# Remove global tool
pixi global remove ruff

Channel Configuration

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

# Channel priority (first = highest)
# conda-forge packages preferred over defaults

Advanced Usage

PyPI Integration

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

[pypi-dependencies]
my-private-pkg = { version = ">=1.0", index = "https://private.pypi.org/simple/" }
my-local-pkg = { path = "./packages/my-pkg", editable = true }
my-git-pkg = { git = "https://github.com/user/repo.git", branch = "main" }

System Requirements

[system-requirements]
linux = "4.18"
cuda = "12.1"
glibc = "2.31"

Activation Scripts

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

[activation.env]
PYTHONPATH = "src"
DATA_DIR = "/data/datasets"

CI/CD Integration

# GitHub Actions
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: prefix-dev/setup-pixi@v0.8.0
        with:
          pixi-version: latest
          cache: true
      - run: pixi run test

Troubleshooting

Issue	Solution
Package not found	Check channel configuration; try `pixi search <pkg>`
Platform not supported	Add platform to `platforms` in pixi.toml
Lock file conflict	Delete `pixi.lock` and run `pixi install`
Slow resolution	Reduce number of channels; pin versions more tightly
PyPI package conflicts	Check conda vs PyPI version compatibility
Environment activation fails	Run `pixi install` first; check pixi.toml syntax

# Debug info
pixi info

# Clean cache
pixi clean

# Verbose install
pixi install -v

# Show resolved environment
pixi list --json | python -m json.tool

# Recreate environment
rm -rf .pixi/ pixi.lock
pixi install