/pixi-environment-builder

name: pixi-environment-builder
description: Use when creating, migrating, or debugging pixi environments, especially for scientific Python, bioinformatics, single-cell analysis, CUDA/PyTorch, Jupyter/VS Code kernels, conda-to-pixi migration, or conda + PyPI mixed dependency issues.

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