Pixi Cheat Sheet

The mental model

A workspace is a folder with a pixi.toml manifest (what you want) and a pixi.lock lockfile (exactly what was resolved, for every platform). Environments live in .pixi/envs/<name> and are created from the lockfile. You never activate anything by hand: pixi run puts the right environment on PATH for one command.

flowchart LR
  M["pixi.toml
(what you ask for)"] -- "pixi lock / pixi install" --> L["pixi.lock
(exact versions, all platforms)"]
  L -- "pixi install" --> E[".pixi/envs/default
(installed packages)"]
  E -- "pixi run / pixi shell" --> C["your command"]
  F["features"] --> M
    

Install and update Pixi

curl -fsSL https://pixi.sh/install.sh | sh
# or
brew install pixi

powershell -ExecutionPolicy ByPass -c "irm -useb https://pixi.sh/install.ps1 | iex"
# or
winget install prefix-dev.pixi

pixi --version              # check it is on PATH (restart the shell first)
pixi self-update            # upgrade pixi itself (not for brew/winget installs)
pixi completion --shell zsh # shell completion; also bash, fish, powershell

Create a workspace

pixi init hello && cd hello
pixi add "python=3.14.*"
pixi add numpy pytest
echo 'print("hi")' > app.py
pixi run python app.py

Add and remove dependencies

Pixi installs conda packages (from conda-forge by default) and PyPI packages in the same environment. Prefer conda-forge: its packages ship compiled libraries and work across languages. Use --pypi only for packages that are not on conda-forge.

[dependencies]                 # conda-forge packages, every environment
python = "3.14.*"
numpy = ">=2.3,<3"

[pypi-dependencies]            # PyPI packages (only when not on conda-forge)
my-app = { path = ".", editable = true }

[target.linux-64.dependencies] # platform-specific
libstdcxx-ng = "*"

Run code: run, shell, exec

Tasks

Tasks are named commands in pixi.toml. They run cross-platform (Pixi uses its own shell, so &&, pipes, and $VAR work on Windows too).

[tasks]
fmt  = "ruff format ."
lint = "ruff check ."
test = { cmd = "pytest tests/unit", description = "Fast unit tests" }

# run other tasks first
ci = { depends-on = ["fmt", "lint", "test"] }

# arguments with defaults:  pixi run greet   |   pixi run greet Ada
greet = { cmd = "echo hello {{ name }}", args = [{ arg = "name", default = "world" }] }

# environment variables and working directory
serve = { cmd = "python -m http.server 8000", cwd = "docs", env = { PYTHONUNBUFFERED = "1" } }

# caching: skipped when inputs and outputs are unchanged
build = { cmd = "python -m build", inputs = ["src/**/*.py", "pyproject.toml"], outputs = ["dist/*"] }

# run a dependency in another environment
test-315 = { depends-on = [{ task = "test", environment = "py315" }] }

[feature.docs.tasks]           # tasks that only exist in environments with this feature
docs = "mkdocs serve"

pixi task list                                   # what can I run?
pixi task add test "pytest tests" --description "All tests"
pixi task alias ci lint test                     # a task that only runs others
pixi task add --feature docs docs "mkdocs serve"
pixi task remove ci
pixi run greet Ada                               # pass a task argument

Features, environments, and solve groups

A feature is a named bundle of dependencies, tasks, and settings. An environment is a list of features (plus the default feature, which is everything at the top level). A solve group makes several environments share one resolution, so prod and test get identical versions of shared packages.

[dependencies]                  # the default feature: in every environment
numpy = ">=2.3,<3"

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

[feature.lint.dependencies]
ruff = "*"
mypy = "*"

[feature.py314.dependencies]
python = "3.14.*"
[feature.py315.dependencies]
python = "3.15.*"

[environments]
default = { features = ["py314", "test", "lint"], solve-group = "main" }
prod    = { features = ["py314"], solve-group = "main" }        # same numpy as default
py315   = ["py315", "test"]                                       # preview Python
lint    = { features = ["lint"], no-default-feature = true }    # tiny: no numpy

pixi install -e py315           # install one environment
pixi install --all              # install all of them
pixi run -e py315 pytest        # run in one
pixi workspace environment add docs --feature docs
pixi workspace environment list
pixi info                       # environments, features, platforms, cache paths

Platforms and system requirements

The lockfile is solved for every platform in platforms, even ones you are not on, so a Mac user's lockfile works on a Linux CI runner.

[workspace]
name = "my-app"
channels = ["conda-forge"]
platforms = ["osx-arm64", "osx-64", "linux-64", "win-64"]

[system-requirements]          # minimum system versions the packages may assume
macos = "13.0"
cuda = "12"

[target.win-64.tasks]          # per-platform tasks (and dependencies, activation)
open-docs = "start docs/index.html"

pixi workspace platform add linux-aarch64
pixi workspace platform remove osx-64
pixi workspace channel add bioconda

Lockfile, update, and upgrade

Global tools

pixi global installs command-line tools each into its own isolated environment and puts their executables on your PATH (in ~/.pixi/bin). Use it for tools you want everywhere (gh, git, ripgrep), never for a project's own dependencies.

pixi global install gh ripgrep
pixi global install --environment py python=3.14 ipython   # several packages in one env
pixi global list
pixi global update                # update all global environments
pixi global remove --environment py ipython
pixi global uninstall gh
pixi global edit                  # open ~/.pixi/manifests/pixi-global.toml
pixi global sync                  # make installed tools match that manifest

CI with GitHub Actions

The official prefix-dev/setup-pixi action installs Pixi, installs your environments from the lockfile, and caches them.

name: CI
on:
  push: { branches: ["main"] }
  pull_request: { branches: ["main"] }

jobs:
  test:
    runs-on: ${{ matrix.os }}
    strategy:
      fail-fast: false
      matrix:
        os: [ubuntu-latest, macos-latest, windows-latest]
    steps:
      - uses: actions/checkout@v4
      - uses: prefix-dev/setup-pixi@v0.8.1
        with:
          pixi-version: latest
          cache: true                 # cache .pixi keyed on pixi.lock
          environments: default py315 # which environments to install
      - run: pixi run ci
      - run: pixi run -e py315 test

Interactive pixi.toml explorer

pixi.toml is plain TOML, so the standard library can read it. Edit the manifest below (add a task, a feature, or an environment) and run the cell to see how Pixi would see it: tasks with their dependencies in execution order, and each environment's resolved feature list.

Configuration and activation

[activation.env]               # set whenever the environment is active
APP_ENV = "dev"
PYTHONWARNINGS = "default"

[pypi-options]
index-url = "https://pypi.org/simple"
no-build-isolation = ["my-legacy-package"]

pixi config list
pixi config set --local tls-root-certs system   # use the OS certificate store (corporate proxies)
pixi config set default-channels '["conda-forge"]'
pixi auth login prefix.dev --token $TOKEN       # private channels

Workspace-local settings live in .pixi/config.toml; user-wide ones in ~/.pixi/config.toml.

Troubleshooting

pip, venv, and conda → Pixi

Check yourself

Going further

• Pixi documentation and manifest reference
• setup-pixi GitHub Action
• In this course: M00 Setup, M08 Modules & Pixi Projects, M41 Packaging & Environments with Pixi, M42 Code Quality & Tooling