pixi

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Pixi Package Manager

Pixi包管理器

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.

Pixi是一款基于Rattler（Rust实现的conda）构建的快速、现代包管理器，可提供可复现的跨平台环境。它整合了conda与PyPI生态系统，支持多种语言，并内置任务管理功能。

Quick Start

快速开始

Check Installation

检查安装

Before working with pixi, verify it's installed:

bash

bash scripts/check_pixi.sh

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

在使用pixi之前，请先验证它是否已安装：

bash

bash scripts/check_pixi.sh

如果未安装，请按照脚本提供的安装说明进行操作。

Common Workflows

常见工作流

Initialize new project:

bash

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

Add packages:

bash

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

Run commands:

bash

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

Manage environments:

bash

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

初始化新项目：

bash

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

添加包：

bash

pixi add <package>              # Conda包
pixi add --pypi <package>        # PyPI包
pixi add --feature dev pytest    # 添加到指定特性

运行命令：

bash

pixi run <task>                  # 运行已定义的任务
pixi exec <command>              # 在环境中执行命令
pixi shell                       # 激活环境Shell

管理环境：

bash

pixi shell --environment <name>  # 激活指定环境
pixi run -e <name> <task>        # 在指定环境中运行任务

Core Capabilities

核心功能

1. Project Initialization

1. 项目初始化

Initialize new pixi projects with automatic manifest creation:

bash

undefined

初始化新的pixi项目并自动创建清单文件：

bash

undefined

Standard pixi.toml format

标准pixi.toml格式

pixi init my-project

Use pyproject.toml format

使用pyproject.toml格式

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)

pixi init --format pyproject my-project


清单文件（`pixi.toml`或`pyproject.toml`）定义了：
- 项目元数据（名称、版本、描述）
- 依赖项（conda与PyPI包）
- 任务（要运行的命令）
- 特性（可选依赖集）
- 环境（特性的组合）
- 通道（包源）
- 平台（目标操作系统）

2. Package Management

2. 包管理

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

bash

undefined

从conda-forge和PyPI添加、移除和管理包：

bash

undefined

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)

pixi update # 更新所有包 pixi update numpy # 更新指定包 pixi upgrade # 升级清单中的依赖


**包类型：**
- 常规依赖项：运行时所需
- `--pypi`：PyPI包（通过uv集成）
- `--host`：宿主依赖项（运行时可用）
- `--build`：构建依赖项（仅构建期间需要）

3. Environment Management

3. 环境管理

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:

toml

[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:

bash

undefined

Pixi支持在单个项目中创建多个隔离环境。每个环境都是多个特性的组合。

核心概念：

默认特性：自动包含在每个环境中
自定义特性：命名的依赖、任务和配置集
环境：为不同用途组合的特性集合

配置示例：

toml

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

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

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

[environments]
test = ["test"]                  # 包含：默认 + test
dev = ["dev", "test"]            # 包含：默认 + dev + test

环境操作：

bash

undefined

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](references/features-guide.md).

pixi list --environment test


有关环境和特性的详细模式，请参阅[references/features-guide.md](references/features-guide.md)。

4. Feature Management

4. 特性管理

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:

toml

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

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

Python version features:

toml

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

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

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

Hardware features:

toml

[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.

特性是定义包集和配置的构建块，可实现：

分离开发与生产依赖
支持多个Python版本
创建平台特定配置
管理硬件特定依赖（CUDA vs CPU）

常见模式：

开发特性：

toml

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

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

Python版本特性：

toml

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

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

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

硬件特性：

toml

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

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

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

有关全面的特性模式和最佳实践，请参阅references/features-guide.md。

5. Task Management

5. 任务管理

Define and run tasks within the pixi environment:

bash

undefined

在pixi环境中定义并运行任务：

bash

undefined

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:**
```toml
[tasks]
start = "python app.py"
test = "pytest tests/"
format = "black ."

pixi task list


**清单中的任务配置：**
```toml
[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"

undefined

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

undefined

6. Command Execution

6. 命令执行

Execute commands within the pixi environment:

bash

undefined

在pixi环境中执行命令：

bash

undefined

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

undefined

pixi exec --environment test pytest

undefined

7. Global Tool Management

7. 全局工具管理

Install CLI tools system-wide, safely isolated:

bash

undefined

安全隔离地在系统范围内安装CLI工具：

bash

undefined

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

undefined

pixi global remove bat

undefined

8. Project Information

8. 项目信息

Get information about the current project:

bash

undefined

获取当前项目的信息：

bash

undefined

Show project info

显示项目信息

pixi info

Detailed information

详细信息

pixi info --extended

JSON output

JSON格式输出

pixi info --json

Use helper script

使用辅助脚本

python scripts/pixi_info.py

undefined

python scripts/pixi_info.py

undefined

9. Lock File Management

9. 锁文件管理

Pixi maintains a

pixi.lock

file for reproducible environments:

bash

undefined

Pixi维护一个

pixi.lock

文件以确保环境可复现：

bash

undefined

Update lock file without installing

更新锁文件但不安装

pixi lock

Update lock for specific environment

更新指定环境的锁文件

pixi lock --environment test

Install from lock file

从锁文件安装

pixi install --frozen

undefined

pixi install --frozen

undefined

10. Maintenance

10. 维护

Clean up and maintain pixi projects:

bash

undefined

清理和维护pixi项目：

bash

undefined

Remove environment directory

移除环境目录

pixi clean

Clean package cache

清理包缓存

pixi clean cache

Reinstall environment from scratch

从头重新安装环境

pixi reinstall

undefined

pixi reinstall

undefined

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

如需详细信息，请查阅以下参考资料：

cli-reference.md - 完整的CLI命令参考，包含所有选项与参数
features-guide.md - 特性与多环境设置的全面指南
examples.md - 实际使用示例与常见场景

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

启动新项目？ → 使用

pixi init

并通过

pixi add

添加依赖

添加包？ → 使用

pixi add

添加conda包，

pixi add --pypi

添加PyPI包 → 使用

--feature

参数添加到指定特性

需要多环境？ → 在清单中定义特性，将其组合为环境 → 参阅references/features-guide.md获取模式示例

运行命令？ → 使用

pixi run

运行已定义的任务 → 使用

pixi exec

执行临时命令 → 使用

pixi shell

交互式激活环境

管理依赖？ → 使用

pixi update

更新到兼容的新版本 → 使用

pixi upgrade

升级并修改清单 → 使用

pixi lock

更新锁文件而不安装

需要全局工具？ → 使用

pixi global install

安装系统级CLI工具

排查问题？ → 运行

pixi info

检查项目状态 → 运行

python scripts/pixi_info.py

获取详细信息 → 查阅references/examples.md获取常见解决方案

Best Practices

最佳实践

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

使用特性管理可选依赖 - 保持默认特性仅包含生产依赖，尽可能精简
利用求解组 - 确保相关环境的版本一致
在清单中定义任务 - 使常见操作易于重复执行
使用语义化版本 - 合理指定版本约束
提交锁文件 - 确保团队成员的环境可复现
使用全局安装工具 - 保持项目依赖干净
记录环境用途 - 添加注释说明每个环境的使用场景

Common Scenarios

常见场景

Data Science Project

数据科学项目

bash

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

bash

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

Web应用

bash

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

bash

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

多Python版本测试

toml

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

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

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

bash

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

For more scenarios, see references/examples.md.

toml

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

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

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

bash

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

更多场景请参阅references/examples.md。

Resources

资源

Scripts

脚本

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

```
scripts/check_pixi.sh
```
- 验证pixi安装
```
scripts/pixi_info.py
```
- 获取详细项目信息

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

```
references/cli-reference.md
```
- 完整CLI命令参考
```
references/features-guide.md
```
- 特性与多环境指南
```
references/examples.md
```
- 使用示例与常见场景

Assets

资源文件

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

```
assets/pixi.toml.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/

官方文档：https://pixi.prefix.dev/latest/
GitHub仓库：https://github.com/prefix-dev/pixi
Conda-forge包：https://conda-forge.org/