pixi

name

pixi

description

Comprehensive package and environment management using pixi - a fast, modern, cross-platform package manager. Use when working with pixi projects for (1) Project initialization and configuration, (2) Package management (adding, removing, updating conda/PyPI packages), (3) Environment management (creating, activating, managing multiple environments), (4) Feature management (defining and composing feature sets), (5) Task execution and management, (6) Global tool installation, (7) Dependency resolution and lock file management, or any other pixi-related operations. Supports Python, C++, R, Rust, Node.js and other languages via conda-forge ecosystem.

Pixi Package Manager

Overview

Pixi is a fast, modern package manager built on Rattler (Rust-based conda implementation) that provides reproducible, cross-platform environments. It combines conda and PyPI ecosystems, supports multiple languages, and includes built-in task management.

Quick Start

Check Installation

Before working with pixi, verify it's installed:

bash scripts/check_pixi.sh

If not installed, follow the installation instructions provided by the script.

Common Workflows

Initialize:

Current project:

pixi init --format pyproject

New project:

pixi init my-project --format pyproject
cd my-project
pixi add python numpy pandas

The --format pyproject flag creates a pyproject.toml manifest instead of the default pixi.toml. Always prioritize pyproject.toml unless specifically required to use pixi.toml. Use the prefix tool.pixi in pyproject.toml for pixi configuration.

Add packages:

pixi add <package>              # Conda package
pixi add --pypi <package>        # PyPI package
pixi add --feature dev pytest    # Add to specific feature

Run commands:

pixi run <task>                  # Run defined task
pixi exec <command>              # Execute command in environment
pixi shell                       # Activate environment shell

Manage environments:

pixi shell --environment <name>  # Activate specific environment
pixi run -e <name> <task>        # Run task in environment

Core Capabilities

1. Project Initialization

Initialize new pixi projects with automatic manifest creation:

# Standard pixi.toml format
pixi init my-project

# Use pyproject.toml format
pixi init --format pyproject my-project

The manifest file (pixi.toml or pyproject.toml) defines:

• Project metadata (name, version, description)
• Dependencies (conda and PyPI packages)
• Tasks (commands to run)
• Features (optional dependency sets)
• Environments (combinations of features)
• Channels (package sources)
• Platforms (target operating systems)

2. Package Management

Add, remove, and manage packages from conda-forge and PyPI:

# Add packages
pixi add numpy pandas matplotlib
pixi add "python>=3.11,<3.12"
pixi add --pypi requests flask

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

# Remove packages
pixi remove numpy
pixi remove --feature dev pytest

# Update packages
pixi update                      # Update all
pixi update numpy                # Update specific package
pixi upgrade                     # Upgrade in manifest

Package types:

• Regular dependencies: Runtime requirements
• --pypi: PyPI packages (via uv integration)
• --host: Host dependencies (available at runtime)
• --build: Build dependencies (only during build)

3. Environment Management

Pixi supports multiple isolated environments within a single project. Each environment is a combination of features.

Key concepts:

• Default feature: Always included automatically in every environment
• Custom features: Named sets of dependencies, tasks, and configurations
• Environments: Combinations of features for different purposes

Example configuration:

[dependencies]
python = "3.11.*"
numpy = "*"

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

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

[environments]
test = ["test"]                  # Includes: default + test
dev = ["dev", "test"]            # Includes: default + dev + test

Working with environments:

# Activate environment
pixi shell --environment test

# Run task in environment
pixi run --environment test pytest

# Install specific environment
pixi install --environment dev

# List packages in environment
pixi list --environment test

For detailed environment and feature patterns, see references/features-guide.md.

4. Feature Management

Features are building blocks that define sets of packages and configurations. They enable:

• Separating development from production dependencies
• Supporting multiple Python versions
• Creating platform-specific configurations
• Managing hardware-specific dependencies (CUDA vs CPU)

Common patterns:

Development features:

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

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

Python version features:

[feature.py310.dependencies]
python = "3.10.*"

[feature.py311.dependencies]
python = "3.11.*"

[environments]
py310 = ["py310"]
py311 = ["py311"]

Hardware features:

[feature.cuda.dependencies]
pytorch-cuda = { version = "*", channel = "pytorch" }

[feature.cpu.dependencies]
pytorch-cpu = { version = "*", channel = "pytorch" }

[environments]
cuda = ["cuda"]
cpu = ["cpu"]

For comprehensive feature patterns and best practices, see references/features-guide.md.

5. Task Management

Define and run tasks within the pixi environment:

# Add tasks
pixi task add test "pytest tests/"
pixi task add format "black ."
pixi task add lint "ruff check ."

# Run tasks
pixi run test
pixi run format

# List tasks
pixi task list

Task configuration in manifest:

[tasks]
start = "python app.py"
test = "pytest tests/"
format = "black ."

# Task with dependencies
build = { cmd = "python setup.py build", depends-on = ["install"] }

# Feature-specific tasks
[feature.dev.tasks]
dev = "python app.py --reload"

6. Command Execution

Execute commands within the pixi environment:

# Run command in activated environment
pixi exec python script.py
pixi exec pytest tests/

# Temporary package installation and execution
pixi exec --spec ruff ruff check .
pixi exec --spec black black .

# Run in specific environment
pixi exec --environment test pytest

7. Global Tool Management

Install CLI tools system-wide, safely isolated:

# Install global tools
pixi global install gh ripgrep fd-find bat
pixi global install ruff black mypy

# List global tools
pixi global list

# Upgrade tools
pixi global upgrade ruff
pixi global upgrade-all

# Remove tools
pixi global remove bat

8. Project Information

Get information about the current project:

# Show project info
pixi info

# Detailed information
pixi info --extended

# JSON output
pixi info --json

# Use helper script
python scripts/pixi_info.py

9. Lock File Management

Pixi maintains a pixi.lock file for reproducible environments:

# Update lock file without installing
pixi lock

# Update lock for specific environment
pixi lock --environment test

# Install from lock file
pixi install --frozen

10. Maintenance

Clean up and maintain pixi projects:

# Remove environment directory
pixi clean

# Clean package cache
pixi clean cache

# Reinstall environment from scratch
pixi reinstall

Minimum Template

The generated pyproject.toml file must follow the template below.

[build-system]
requires = ["setuptools>=64", "wheel"]
build-backend = "setuptools.build_meta"

[project]
name = "project-name"
version = "0.0.0"
description = ""
readme = "README.md"
requires-python = ">=3.10,<3.13"
dependencies = []

[tool.pixi.workspace]
channels = [
    "https://mirrors.tuna.tsinghua.edu.cn/anaconda/cloud/conda-forge/",
    "conda-forge",
]
platforms = ["linux-64"]

[tool.pixi.pypi-options]
index-url = "https://mirrors.tuna.tsinghua.edu.cn/pypi/web/simple/"
extra-index-urls = ["https://mirrors.aliyun.com/pypi/simple/"]

[tool.pixi.pypi-dependencies]
project-name = { path = ".", editable = true }

[tool.pixi.feature.build.pypi-dependencies]
build = "*"

[tool.pixi.feature.build.task]

[tool.pixi.feature.publish.dependencies]
twine = "*"

[tool.pixi.environments]
build = ["build"]
publish = ["publish"]

[tool.pixi.tasks]
build = { cmd = "rm -rf dist && python -m build", default-environment = "build" }
publish-pypi = { cmd = "twine upload dist/*", depends-on = [
    "build",
], default-environment = "publish" }

[tool.setuptools]
packages = ["project_name"]

Reference Documentation

For detailed information, consult these references:

• cli-reference.md - Complete CLI command reference with all options and flags
• features-guide.md - Comprehensive guide to features and multi-environment setup
• examples.md - Real-world usage examples and common scenarios

Workflow Decision Guide

Starting a new project? → Use pixi init and add dependencies with pixi add

Adding packages? → Use pixi add for conda packages, pixi add --pypi for PyPI packages → Use --feature flag to add to specific features

Need multiple environments? → Define features in manifest, compose them into environments → See references/features-guide.md for patterns

Running commands? → Use pixi run for defined tasks → Use pixi exec for ad-hoc commands → Use pixi shell to activate environment interactively

Managing dependencies? → Use pixi update to update to newer compatible versions → Use pixi upgrade to upgrade and modify manifest → Use pixi lock to update lock file without installing

Need global tools? → Use pixi global install for system-wide CLI tools

Troubleshooting? → Run pixi info to check project status → Run python scripts/pixi_info.py for detailed information → Check references/examples.md for common solutions

Best Practices

1. Use features for optional dependencies - Keep default feature minimal with only production dependencies
2. Leverage solve groups - Ensure consistent versions across related environments
3. Define tasks in manifest - Make common operations easily repeatable
4. Use semantic versioning - Specify version constraints appropriately
5. Commit lock file - Ensure reproducible environments across team
6. Use global install for tools - Keep project dependencies clean
7. Document environment purposes - Add comments explaining each environment's use case

Common Scenarios

Data Science Project

pixi init data-project
pixi add python numpy pandas matplotlib jupyter scikit-learn
pixi add --feature dev pytest black
pixi task add notebook "jupyter lab"
pixi run notebook

Web Application

pixi init web-app
pixi add python
pixi add --pypi fastapi uvicorn sqlalchemy
pixi add --feature dev --pypi pytest httpx
pixi task add dev "uvicorn app:app --reload"
pixi run dev

Multi-Python Testing

[feature.py310.dependencies]
python = "3.10.*"

[feature.py311.dependencies]
python = "3.11.*"

[environments]
py310 = ["py310"]
py311 = ["py311"]

pixi run -e py310 pytest
pixi run -e py311 pytest

For more scenarios, see references/examples.md.

Resources

Scripts

• scripts/check_pixi.sh - Verify pixi installation
• scripts/pixi_info.py - Get detailed project information

References

• references/cli-reference.md - Complete CLI command reference
• references/features-guide.md - Features and multi-environment guide
• references/examples.md - Usage examples and common scenarios

Assets

• assets/pixi.toml.template - Basic project template

External Resources

• Official documentation: https://pixi.prefix.dev/latest/
• GitHub repository: https://github.com/prefix-dev/pixi
• Conda-forge packages: https://conda-forge.org/