# Pixi: Multi-Language Package and Workflow Manager


Pixi is a cross-platform package manager and workflow tool that manages both [conda-forge](https://pydevtools.com/handbook/reference/conda-forge.md) packages and PyPI packages from a single project manifest. It replaces [conda](https://pydevtools.com/handbook/reference/conda.md)'s global environment model with project-local environments and automatic lock files.

> [!NOTE]
> Pixi targets the same package ecosystem as conda but with a different workflow model. If you don't need conda-forge packages, [uv](https://pydevtools.com/handbook/reference/uv.md) is a simpler choice. See [When should I choose pixi over uv?](https://pydevtools.com/handbook/explanation/when-should-i-choose-pixi-over-uv.md) for a detailed comparison.

## When to use pixi

Use pixi when your project depends on native libraries that conda-forge packages more reliably than PyPI: CUDA toolkits, GDAL, HDF5, OpenCV, MKL, NetCDF. Some of these have PyPI packages, but conda-forge bundles the underlying C/C++/Fortran libraries so you don't need to install them separately. Pixi also works well for mixed-language projects (Python + R, Python + C++) and for teams that want reproducible cross-platform lock files covering both conda and PyPI dependencies.

For pure Python projects, [uv](https://pydevtools.com/handbook/reference/uv.md) provides a simpler workflow.

## Installation

```bash
curl -fsSL https://pixi.sh/install.sh | bash
```
```powershell
iwr -useb https://pixi.sh/install.ps1 | iex
```
This installs the `pixi` binary to `~/.pixi/bin` (macOS/Linux) or `%UserProfile%\.pixi\bin` (Windows). See the [official installation guide](https://pixi.sh/latest/getting_started/) for other methods.

## Project setup

Initialize a new project with `pixi init`:

```bash
pixi init my-project
cd my-project
```

This creates a `pixi.toml` manifest:

```toml
[workspace]
authors = ["Your Name <you@example.com>"]
channels = ["conda-forge"]
name = "my-project"
platforms = ["osx-arm64"]  # auto-detected from your system
version = "0.1.0"

[dependencies]

[tasks]
```

To use `pyproject.toml` instead (useful if you're building a Python package):

```bash
pixi init --format pyproject my-project
```

With `pyproject.toml`, pixi configuration lives under `[tool.pixi.*]` sections (e.g. `[tool.pixi.workspace]`, `[tool.pixi.dependencies]`), while standard `[project]` metadata remains portable to other Python tools.

## Managing dependencies

### Conda packages

```bash
pixi add python numpy pandas
```

### PyPI packages

```bash
pixi add --pypi requests
```

Pixi resolves conda dependencies first, then resolves PyPI packages against what conda already installed. It uses [uv](https://pydevtools.com/handbook/reference/uv.md) internally for PyPI resolution.

### Installing the environment

```bash
pixi install
```

This creates a `.pixi/` directory containing the project environment. The directory is local to the project and should be added to `.gitignore` (pixi does this automatically on `pixi init`).

## Running commands

```bash
# Run a command in the project environment
pixi run python main.py

# Start an interactive shell
pixi shell
```

## Tasks

Pixi includes a built-in task runner. Tasks are defined in `pixi.toml` and run within the project environment.

```bash
# Add tasks
pixi task add test "pytest -s"
pixi task add lint "ruff check ."

# Run a task
pixi run test
```

Tasks can also be defined directly in `pixi.toml` with dependencies on other tasks:

```toml
[tasks]
lint = "ruff check ."
test = { cmd = "pytest -s", depends-on = ["lint"] }
```

## Multi-environment support

Pixi can define multiple environments from composable "features." Each feature is a named set of dependencies; environments combine one or more features. Named environments include the default feature's dependencies unless you set `no-default-feature = true`.

```toml
[dependencies]
python = ">=3.12"
numpy = ">=2.0"

[feature.test.dependencies]
pytest = ">=8"

[feature.docs.dependencies]
sphinx = ">=7"

[environments]
test = ["test"]
docs = ["docs"]
```

Run commands in a specific environment:

```bash
pixi run --environment test pytest
pixi run --environment docs sphinx-build docs build
```

## Cross-platform lock files

Pixi resolves dependencies for all target platforms in a single `pixi.lock` file. Add platforms with:

```bash
pixi workspace platform add linux-64 win-64
```

The lock file captures the full dependency graph for every platform and environment combination. Each platform is solved separately, so exact builds may differ across OSes, but every collaborator gets a reproducible install for their platform.

## Tool management

Like [pipx](https://pydevtools.com/handbook/reference/pipx.md) or `uvx`, pixi can install CLI tools globally or run them in temporary environments:

```bash
# Install a tool globally
pixi global install ruff

# Run a tool without installing it
pixi exec black --check .

# List globally installed tools
pixi global list
```

## Other useful commands

```bash
# Search for a package on configured channels
pixi search opencv

# Show the dependency tree
pixi tree

# Show environment and system info
pixi info

# Update dependencies to latest compatible versions
pixi update
```

## Learn more

- [Create your first Python project with pixi](https://pydevtools.com/handbook/tutorial/create-your-first-python-project-with-pixi.md) (Tutorial)
- [Set up a GPU data science project with pixi](https://pydevtools.com/handbook/tutorial/set-up-a-gpu-data-science-project-with-pixi.md) (Tutorial)
- [How to migrate from conda to pixi](https://pydevtools.com/handbook/how-to/how-to-migrate-from-conda-to-pixi.md) (How To)
- [When should I choose pixi over uv?](https://pydevtools.com/handbook/explanation/when-should-i-choose-pixi-over-uv.md) (Explanation)
- [uv vs pixi vs conda for scientific Python](https://pydevtools.com/handbook/explanation/uv-vs-pixi-vs-conda-for-scientific-python.md) (Explanation)
- [Pixi documentation](https://pixi.sh/latest/)
- [Pixi GitHub repository](https://github.com/prefix-dev/pixi)
- [Switching from conda to pixi](https://pixi.sh/latest/switching_from/conda/)