Pixi

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               # Conda package
pixi add --pypi         # PyPI package
pixi add --feature dev pytest    # Add to specific feature

Run commands:

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

Manage environments:

pixi shell --environment   # Activate specific environment
pixi run -e          # 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,=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](references/cli-reference.md) - Complete CLI command reference with all options and flags
• [features-guide.md](references/features-guide.md) - Comprehensive guide to features and multi-environment setup
• [examples.md](references/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](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](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](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/

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: OpenGHz
• Source: OpenGHz/AgentSkills
• License: MIT

Install and usage instructions live in the source repository linked above.