Pixi

Pixi Helper

Expert guidance for using Pixi, a fast conda-based package manager for Python projects.

Purpose

Help developers effectively use Pixi for managing conda/PyPI dependencies, running commands in isolated environments, and configuring multi-environment projects.

When to Use

• Working with pixi.toml or pixi.lock files
• Installing or managing packages
• Running commands or tasks in pixi environments
• Setting up development/production environments
• Debugging pixi configuration errors

---

Quick Command Reference

Essential Commands

# Initialize & install
pixi init [project-name]
pixi install                         # install default environment
pixi install -e dev                  # install dev environment

# Add dependencies
pixi add python=3.11 pytorch pandas  # conda packages
pixi add --pypi transformers         # PyPI packages
pixi add --feature dev pytest ruff   # to dev feature

# Run commands
pixi run python script.py            # use default env
pixi run -e dev pytest               # use dev env
pixi shell                           # interactive shell
pixi shell -e dev                    # dev shell

# Tasks
pixi task add lint "ruff check ."
pixi task list
pixi run lint

# Production
pixi run --frozen --no-install train.py

Key Flags

• -e <env>: Use specific environment
• --frozen: Don't update lock file (reproducible)
• --no-install: Skip installation
• --feature <name>: Target specific feature

---

Core Concepts

Workspace

Directory with:

• pixi.toml: Configuration (commit this)
• pixi.lock: Lock file (commit this)
• .pixi/: Environment cache (DON'T commit)

Environments

Named dependency sets. Use -e flag to select:

pixi run python script.py       # default
pixi run -e dev pytest           # dev
pixi run -e prod train.py        # prod

Features

Reusable dependency groups that compose into environments.

Tasks

Predefined commands in pixi.toml. Run with pixi run <task-name>.

---

Command Patterns

When to Use What

Adding Dependencies

Prefer conda first (better compatibility, faster):

pixi add numpy pytorch

Use PyPI when needed:

pixi add --pypi transformers

Why conda first? Pixi resolves conda deps first, then PyPI.

---

pixi.toml Configuration

Project Metadata

[project]
name = "my-project"
channels = ["conda-forge", "pytorch"]  # order matters
platforms = ["linux-64", "osx-arm64"]

Dependencies

[dependencies]
python = ">=3.10"
numpy = "*"
pytorch = ">=2.0,<3"

[pypi-dependencies]
transformers = "*"
my-pkg = { path = "./local", editable = true }

Tasks

Simple:

[tasks]
test = "pytest tests/"

With environment variables:

[tasks.train]
cmd = "python train.py"
env = { CUDA_VISIBLE_DEVICES = "0,1" }

With dependencies:

[tasks]
clean = "rm -rf __pycache__"
test = { cmd = "pytest", depends-on = ["clean"] }

Multi-line:

[tasks.submit]
cmd = """
python train.py \
  --config config.yaml \
  --output results/
"""

Features

[feature.dev.dependencies]
pytest = "*"
ruff = "*"

[feature.cuda.dependencies]
pytorch-cuda = "12.1"

[environments]
default = []
dev = ["dev"]
gpu = ["cuda"]
dev-gpu = ["dev", "cuda"]

Activation Environment

[activation.env]
CUDA_HOME = "/usr/local/cuda"
PROJECT_ROOT = "$PIXI_PROJECT_ROOT"

---

Common Workflows

Your Patterns (susser-tod)

Dev testing:

pixi run -e dev pytest ./tests

Type checking:

pixi run typecheck

Profiling:

pixi run -e dev nsys profile python train.py

---

Troubleshooting

1. Package Not Found

Checks: 1. Channel specified in channels = [...]? 2. Package name correct? Try: pixi search <pkg> 3. Try PyPI: pixi add --pypi <pkg>

2. Environment Not Activated

❌ Wrong: python script.py (bare python) ✅ Correct: pixi run python script.py

4. Lock File Conflicts

After merge conflicts:

pixi install              # regenerate lock
# or
rm pixi.lock && pixi install

5. Environment Variables Not Set

Variables from [activation.env] only work with:

• pixi run <cmd>
• Inside pixi shell

NOT with bare python outside pixi.

6. Dependency Version Conflicts

Use solve-group to isolate environments:

[environments]
default = { solve-group = "group1" }
dev = { features = ["dev"], solve-group = "group1" }  # shared
prod = { solve-group = "group2" }                     # isolated

---

Best Practices

Dependencies

✅ Conda first, PyPI when needed ✅ Pin critical versions: pytorch = "2.1.*" ✅ Version constraints: python = ">=3.10,<3.12" ❌ Don't mix conda + PyPI for same package

Lock Files

✅ Commit pixi.lock ✅ Use --frozen in CI/production

Environments

✅ Use features to organize deps ✅ Share solve-groups when possible ✅ 2-4 environments is ideal

---

Reference

• Detailed pixi.toml schema: See REFERENCE.md
• Official docs: https://pixi.sh/latest/
• pixi.toml spec: https://pixi.sh/latest/reference/pixi_toml/

---

Practical guidance for Pixi. For project-specific patterns, check your CLAUDE.md.

Pixi Configuration Reference

Comprehensive reference for pixi.toml configuration file structure.

Table of Contents

• Project Section
• Dependencies
• PyPI Dependencies
• Features
• Environments
• Tasks
• System Requirements
• Activation
• Target

---

Project Section

Defines project metadata and global settings.

[project]
name = "my-project"                    # Required: project name
version = "0.1.0"                      # Optional: version
description = "Project description"    # Optional: description
authors = ["Name <email@example.com>"] # Optional: list of authors
channels = ["conda-forge", "pytorch"]  # Required: conda channels
platforms = ["linux-64", "osx-arm64"]  # Required: target platforms
license = "MIT"                        # Optional: license
license-file = "LICENSE"               # Optional: license file path
readme = "README.md"                   # Optional: readme file
homepage = "https://example.com"       # Optional: homepage URL
repository = "https://github.com/..."  # Optional: repo URL
documentation = "https://docs..."      # Optional: docs URL

Channels

Order matters! Pixi searches channels in order listed.

Common channels:

• conda-forge: General Python packages
• pytorch: PyTorch and related
• nvidia: CUDA packages
• rapidsai: GPU data science
• bioconda: Bioinformatics

Custom channels:

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

Platforms

Supported platforms:

• linux-64: Linux x86_64
• linux-aarch64: Linux ARM64
• osx-64: macOS Intel
• osx-arm64: macOS Apple Silicon
• win-64: Windows x86_64

---

Dependencies

Conda packages for the default environment.

[dependencies]
python = ">=3.10,<3.12"           # Version range
numpy = "*"                        # Any version
pytorch = "2.1.*"                  # Minor version lock
pandas = ">=2.0"                   # Minimum version
scikit-learn = "~=1.3.0"          # Compatible release
cuda = { version = "12.1", build = "h12345_0" }  # Specific build

Version Specifiers

Build Specification

[dependencies]
package = { version = "1.0", build = "py310_0" }

---

PyPI Dependencies

Python packages from PyPI (when not available in conda).

[pypi-dependencies]
transformers = ">=4.30"
my-package = "*"

# Editable local package
my-local-pkg = { path = "./packages/my-pkg", editable = true }

# From git
my-git-pkg = { git = "https://github.com/user/repo.git" }
my-git-pkg-branch = { git = "https://github.com/user/repo.git", branch = "main" }
my-git-pkg-tag = { git = "https://github.com/user/repo.git", tag = "v1.0.0" }
my-git-pkg-rev = { git = "https://github.com/user/repo.git", rev = "abc123" }

# From URL
my-wheel = { url = "https://example.com/package.whl" }

# With extras
my-pkg = { version = "*", extras = ["dev", "test"] }

PyPI Version Syntax

Same as pip:

• ==X.Y.Z: Exact version
• >=X.Y.Z: Minimum version
• ~=X.Y.Z: Compatible release
• >=X,<Y: Version range

---

Features

Reusable dependency groups that can be combined.

[feature.dev.dependencies]
pytest = ">=7.0"
ruff = "*"
pyright = "*"

[feature.dev.pypi-dependencies]
jupyter = "*"
ipython = "*"

[feature.dev.tasks]
test = "pytest tests/"
lint = "ruff check ."

[feature.cuda.dependencies]
pytorch-cuda = "12.1"
cuda-toolkit = "12.1"

[feature.cuda.activation.env]
CUDA_VISIBLE_DEVICES = "0,1,2,3"

Features can contain:

• dependencies: Conda packages
• pypi-dependencies: PyPI packages
• tasks: Feature-specific tasks
• activation.env: Environment variables
• system-requirements: System constraints

---

Environments

Named combinations of features.

[environments]
default = { solve-group = "default" }
dev = { features = ["dev"], solve-group = "default" }
prod = { features = ["prod"], solve-group = "prod" }
gpu = ["cuda"]
dev-gpu = { features = ["dev", "cuda"], solve-group = "default" }

Solve Groups

Environments in same solve-group share dependency resolution.

Benefits:

• Faster solving (reuses solutions)
• More consistent (same base dependencies)
• Less disk space (shared cache)

When to separate:

• Conflicting dependencies
• Different Python versions
• Isolated production environment

Example:

[environments]
# Dev and test share solutions
default = { solve-group = "dev-group" }
dev = { features = ["dev"], solve-group = "dev-group" }
test = { features = ["test"], solve-group = "dev-group" }

# Prod is isolated
prod = { features = ["prod"], solve-group = "prod-group" }

---

Tasks

Predefined commands that can be run with pixi run <task>.

Simple Task

[tasks]
test = "pytest tests/"
lint = "ruff check ."

Task with Options

[tasks.train]
cmd = "python train.py"                    # Command to run
cwd = "scripts/"                           # Working directory
depends-on = ["install-deps"]              # Run these tasks first
inputs = ["src/**/*.py"]                   # Input files (for caching)
outputs = ["models/**/*"]                  # Output files (for caching)
env = { CUDA_VISIBLE_DEVICES = "0" }      # Environment variables

Full Task Schema

[tasks.my-task]
cmd = "command to run"                     # Required: command
cwd = "relative/path"                      # Optional: working directory
depends-on = ["other-task", "another"]    # Optional: task dependencies
inputs = ["src/**/*.py", "data/*.csv"]    # Optional: input glob patterns
outputs = ["output/**/*", "result.txt"]   # Optional: output glob patterns

[tasks.my-task.env]
VAR1 = "value1"
VAR2 = "value2"

Task Dependencies

Tasks can depend on other tasks:

[tasks]
clean = "rm -rf build/"
build = { cmd = "python setup.py build", depends-on = ["clean"] }
test = { cmd = "pytest", depends-on = ["build"] }

Running pixi run test will execute: clean → build → test

Multi-line Commands

[tasks.train]
cmd = """
python train.py \
  --config config.yaml \
  --epochs 100 \
  --batch-size 32
"""

Feature-Specific Tasks

[feature.dev.tasks]
test = "pytest tests/"
lint = "ruff check ."

[feature.prod.tasks]
deploy = "bash deploy.sh"

Task Environment Variables

Available variables:

• $PIXI_PROJECT_ROOT: Absolute path to project root
• $PIXI_ENVIRONMENT_NAME: Current environment name
• $PIXI_PROJECT_NAME: Project name from pixi.toml
• $PIXI_PROJECT_VERSION: Project version
• Any variables from [activation.env]

---

System Requirements

Specify system constraints.

[system-requirements]
linux = "5.10"              # Minimum kernel version
cuda = "12.1"               # CUDA version
libc = { family = "glibc", version = "2.28" }

Available Requirements

• linux: Linux kernel version
• cuda: CUDA version
• macos: macOS version
• libc: C library (glibc or musl)
• archspec: CPU architecture

---

Activation

Environment variables and scripts to run when environment is activated.

Environment Variables

[activation.env]
CUDA_HOME = "/usr/local/cuda"
TORCH_CUDA_ARCH_LIST = "8.0;9.0"
PROJECT_ROOT = "$PIXI_PROJECT_ROOT"
DATA_PATH = "$HOME/data"
PYTHONPATH = "$PIXI_PROJECT_ROOT/src:$PYTHONPATH"

Variables are set when:

• Running pixi run <cmd>
• Inside pixi shell

Activation Scripts

[activation.scripts]
env_setup.sh = """
#!/bin/bash
echo "Environment activated!"
export CUSTOM_VAR="value"
"""

Or reference external file:

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

---

Target

Platform-specific configuration.

[target.linux-64.dependencies]
nvidia-cuda-toolkit = "12.1"

[target.osx-arm64.dependencies]
tensorflow-macos = "2.13"

[target.win-64.dependencies]
pytorch-cuda = { version = "12.1", channel = "pytorch" }

Use when:

• Different packages per platform
• Platform-specific versions
• OS-specific configuration

---

Complete Example

[project]
name = "ml-project"
version = "0.1.0"
channels = ["conda-forge", "pytorch", "nvidia"]
platforms = ["linux-64", "osx-arm64"]

[dependencies]
python = ">=3.10,<3.12"
pytorch = "2.1.*"
numpy = "*"
pandas = ">=2.0"

[pypi-dependencies]
transformers = ">=4.30"
wandb = "*"

[feature.dev.dependencies]
pytest = "*"
ruff = "*"
jupyter = "*"

[feature.dev.tasks]
test = "pytest tests/"
lint = "ruff check ."
format = "ruff format ."

[feature.cuda.dependencies]
pytorch-cuda = "12.1"
cuda-toolkit = "12.1"

[feature.cuda.activation.env]
CUDA_VISIBLE_DEVICES = "0,1,2,3"
CUDA_HOME = "/usr/local/cuda"

[environments]
default = { solve-group = "main" }
dev = { features = ["dev"], solve-group = "main" }
gpu = { features = ["cuda"], solve-group = "main" }
dev-gpu = { features = ["dev", "cuda"], solve-group = "main" }

[tasks]
train = { cmd = "python train.py", env = { EPOCHS = "100" } }
evaluate = "python eval.py"

[tasks.train-distributed]
cmd = "torchrun --nproc_per_node=8 train.py"
depends-on = ["validate-config"]
env = { MASTER_PORT = "29500" }

[tasks.validate-config]
cmd = "python validate_config.py"

[activation.env]
PROJECT_ROOT = "$PIXI_PROJECT_ROOT"
DATA_DIR = "$PROJECT_ROOT/data"
MODEL_DIR = "$PROJECT_ROOT/models"

[system-requirements]
cuda = "12.1"

[target.linux-64.dependencies]
nvidia-cuda-toolkit = "12.1"

---

Tips & Tricks

Keep Dependencies Organized

# Base ML dependencies
[dependencies]
python = ">=3.10"
pytorch = "2.1.*"
numpy = "*"

# Development tools
[feature.dev.dependencies]
pytest = "*"
ruff = "*"

# Optional features
[feature.cuda.dependencies]
pytorch-cuda = "12.1"

[feature.distributed.dependencies]
horovod = "*"

Use Solve Groups Wisely

Same group = faster, shared dependencies:

[environments]
default = { solve-group = "dev" }
dev = { features = ["dev"], solve-group = "dev" }

Different groups = isolated:

[environments]
dev = { solve-group = "dev" }
prod = { solve-group = "prod" }

Task Composition

[tasks]
clean = "rm -rf build/ dist/"
build = { cmd = "python -m build", depends-on = ["clean"] }
test = { cmd = "pytest", depends-on = ["build"] }
publish = { cmd = "twine upload dist/*", depends-on = ["test"] }

Conditional Platform Configuration

# Linux: use CUDA
[target.linux-64.dependencies]
pytorch-cuda = "12.1"

# macOS: use CPU or Metal
[target.osx-arm64.dependencies]
pytorch = "2.1.*"

---

Troubleshooting Configuration

Validate pixi.toml

pixi install --dry-run  # Check for errors without installing

Debug Dependency Resolution

pixi tree                # Show dependency tree
pixi list                # List installed packages

Check Environment Setup

pixi info                # Project info
pixi project info        # Detailed project info
pixi environment list    # List environments

---

External Resources

• Official Reference: https://pixi.sh/latest/reference/pixi_toml/
• Configuration Examples: https://pixi.sh/latest/examples/
• Community Examples: https://github.com/prefix-dev/pixi/tree/main/examples