Pixi Environment Builder

Pixi Environment Builder

Overview

Use this skill to design, migrate, and debug pixi-managed environments. The core principle is to clarify environment intent before editing pixi.toml: version constraints, project scope, package source priority, mirror/network policy, special packages, cache location, and validation tasks.

Pixi can solve dependencies automatically, but mixed conda + PyPI environments need deliberate package ownership. Most hard failures come from unclear ownership, unconstrained top-level packages, inaccessible mirrors, or non-registry packages.

Preflight Questions

Before creating or changing a pixi environment, ask these questions unless the answer is already known from repo files, user context, or error logs:

1. Required versions

   • Are any package versions fixed by previous results, notebooks, papers, models, CUDA drivers, or collaborators?
   • Examples: python, cuda, pytorch, domain packages, model libraries, analysis frameworks.

2. Environment scope

   • Is this project-level, user/global-level, or temporary?
   • Project-level: create or edit repo pixi.toml.
   • User/global-level: prefer pixi global for reusable CLI tools, not complex project workflows.

3. Package source priority

   • Should conda or PyPI own the main dependency graph?
   • Which packages should be installed from conda, PyPI, Git, local path, or system modules?
   • Avoid specifying the same package unconstrained in both conda and PyPI.

4. Multiple environments or kernels

   • Does the user need separate named environments, solve groups, or Jupyter/VS Code kernels?
   • Clarify whether they need identical packages in separate prefixes or different feature sets.

5. Mirror and network policy

   • Which conda channels and mirrors are reachable?
   • Which PyPI index is reachable?
   • Can the machine access GitHub, pypi.org, files.pythonhosted.org, prefix.dev, or internal mirrors?

6. Non-registry packages

   • Are any packages installed from local source, private Git repos, wheels, editable paths, or unpublished projects?

7. Cache and storage

   • Use pixi defaults unless there is a permissions, quota, or sharing requirement.
   • If custom cache is needed, ask where writable shared cache should live.

8. Validation

   • What imports, version checks, CLI commands, GPU checks, or kernel registration prove the environment works?

Design Rules

Prefer project-level manifests for project workflows

For analysis projects, put environment definition in the repo:

[workspace]
name = "project-name"
channels = ["conda-forge"]
platforms = ["linux-64"]

Use user/global environments mostly for standalone tools.

Assign package ownership

Choose one owner for each important package family.

Prefer conda for:

• Python interpreter
• compiled libraries and hard-to-build scientific packages
• CUDA/PyTorch stacks when conda binaries are desired
• R, rpy2, system libraries, CLI bioinformatics tools
• packages requiring consistent native ABI

Prefer PyPI for:

• packages whose canonical release is PyPI
• fast-moving Python-only libraries
• packages unavailable or stale on conda
• top-level frameworks that expect pip-style dependency resolution
• headless/server variants such as opencv-python-headless

Avoid this pattern:

[dependencies]
scanpy = "*"
anndata = "*"
scipy = "*"

[pypi-dependencies]
some-framework-that-also-depends-on-scanpy = "*"

This can make conda pin versions before PyPI solves, causing conflicts.

Start minimal, then add constraints only when evidence requires them

Do not mechanically copy an entire old conda environment. Start from:

• interpreter/runtime
• top-level packages the user directly uses
• hardware/runtime packages
• Jupyter/kernel tooling if needed
• non-registry packages

Add transitive pins only when solver output or runtime validation proves they are needed.

Migrating From Conda

When migrating an existing conda/mamba environment:

1. Inspect by path if env-name lookup is unreliable:

conda list -p /path/to/env
conda env export -p /path/to/env --no-builds

2. Identify direct imports and notebook evidence:

rg -n "^(import|from) " scripts src notebooks tests --glob '*.py' --glob '*.ipynb'
rg -n "Version:|__version__|import " notebooks scripts --glob '*.ipynb'

3. Classify packages:

   • direct user dependencies
   • transitive dependencies
   • runtime/system dependencies
   • local/Git/private packages
   • packages only needed for old experiments

4. Preserve known compatibility anchors:

   • versions printed in notebook outputs
   • versions required by published workflow
   • CUDA/PyTorch compatibility
   • package versions known to affect results

5. Leave unrelated transitive packages out of pixi.toml.

Multiple Environments And Kernels

Use multiple named environments when the user needs isolation or parallel notebooks.

Use one solve group when environments should have identical package versions:

[environments]
worker-1 = { solve-group = "analysis" }
worker-2 = { solve-group = "analysis" }
worker-3 = { solve-group = "analysis" }

Use separate features when environments differ:

[feature.gpu.dependencies]
pytorch-cuda = "*"

[feature.r.dependencies]
r-base = "*"

[environments]
cpu = []
gpu = ["gpu"]
r-analysis = ["r"]

For VS Code/Jupyter kernels, add explicit kernel tasks:

[tasks]
kernel-1 = "python -m ipykernel install --user --name worker-1 --display-name 'Python (worker-1)'"
kernel-2 = "python -m ipykernel install --user --name worker-2 --display-name 'Python (worker-2)'"
kernels = "pixi run -e worker-1 kernel-1 && pixi run -e worker-2 kernel-2"

Tell VS Code users: after registration, select the kernel in VS Code; they do not need to launch notebooks through pixi run.

Mirrors And Network

Use mirrors deliberately. Do not assume a mirror works for all package types.

Recommended checks:

pixi config list
sed -n '1,120p' ~/.config/uv/uv.toml 2>/dev/null
sed -n '1,120p' ~/.config/pip/pip.conf 2>/dev/null
env | rg "PIP|UV|PIXI|RATTLER|HTTP|HTTPS|PROXY"

For PyPI, prefer setting only the index URL in pixi.toml:

[pypi-options]
index-url = "https://example-mirror/simple"

Avoid unnecessary files.pythonhosted.org mirror rewrites unless verified. Some mirrors serve simple index pages but fail wheel metadata URLs.

If official PyPI times out, switch to a reachable mirror. If a mirror gives 404 for metadata, try another mirror or the official file server directly.

For conda, use .pixi/config.toml mirrors when needed:

[mirrors]
"https://conda.anaconda.org/conda-forge" = [
  "https://your-conda-mirror/anaconda/cloud/conda-forge",
  "https://conda.anaconda.org/conda-forge"
]

Conda + PyPI Mapping

Pixi needs conda-to-PyPI name mapping when conda and PyPI dependencies are mixed. If fetching mapping from prefix.dev fails, use a local mapping file.

In pixi.toml:

[workspace]
conda-pypi-map = { "conda-forge" = "config/conda-pypi-map.json" }

Example config/conda-pypi-map.json:

{
  "scikit-learn": "scikit-learn",
  "matplotlib-base": "matplotlib",
  "pytorch": "torch",
  "torchvision": "torchvision",
  "torchaudio": "torchaudio"
}

Validate it:

python -m json.tool config/conda-pypi-map.json

Keep this mapping small and project-specific. Add entries only for packages relevant to mixed solving.

Non-Registry Packages

If a package is not found on PyPI or conda, inspect how it was installed before guessing.

Check old environment metadata:

find /path/to/env/lib/python*/site-packages -maxdepth 3 \
  \( -iname '*dist-info' -o -path '*dist-info/direct_url.json' \)

Use local path dependency when reproducible on this machine:

[pypi-dependencies]
my-package = { path = "/absolute/path/to/source" }

Use Git dependency when portability matters:

[pypi-dependencies]
my-package = { git = "https://github.com/org/repo.git", rev = "commit-sha" }

Prefer a fixed commit/tag for reproducibility.

Common Failure Patterns

Package not found in registry

Root cause: package is unpublished, private, named differently, or only installed from source.

Actions:

• Inspect old direct_url.json.
• Search project docs for install command.
• Use path or Git dependency.
• Do not keep retrying PyPI.