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.
\nBefore creating or changing a pixi environment, ask these questions unless the answer is already known from repo files, user context, or error logs:
\nRequired versions
\npython, cuda, pytorch, domain packages, model libraries, analysis frameworks.Environment scope
\npixi.toml.pixi global for reusable CLI tools, not complex project workflows.Package source priority
\nMultiple environments or kernels
\nMirror and network policy
\npypi.org, files.pythonhosted.org, prefix.dev, or internal mirrors?Non-registry packages
\nCache and storage
\nValidation
\nFor analysis projects, put environment definition in the repo:
\n[workspace]\nname = \"project-name\"\nchannels = [\"conda-forge\"]\nplatforms = [\"linux-64\"]\nUse user/global environments mostly for standalone tools.
\nChoose one owner for each important package family.
\nPrefer conda for:
\nPrefer PyPI for:
\nopencv-python-headlessAvoid this pattern:
\n[dependencies]\nscanpy = \"*\"\nanndata = \"*\"\nscipy = \"*\"\n\n[pypi-dependencies]\nsome-framework-that-also-depends-on-scanpy = \"*\"\nThis can make conda pin versions before PyPI solves, causing conflicts.
\nDo not mechanically copy an entire old conda environment. Start from:
\nAdd transitive pins only when solver output or runtime validation proves they are needed.
\nWhen migrating an existing conda/mamba environment:
\nconda list -p /path/to/env\nconda env export -p /path/to/env --no-builds\nrg -n \"^(import|from) \" scripts src notebooks tests --glob '*.py' --glob '*.ipynb'\nrg -n \"Version:|__version__|import \" notebooks scripts --glob '*.ipynb'\nClassify packages:
\nPreserve known compatibility anchors:
\nLeave unrelated transitive packages out of pixi.toml.
Use multiple named environments when the user needs isolation or parallel notebooks.
\nUse one solve group when environments should have identical package versions:
\n[environments]\nworker-1 = { solve-group = \"analysis\" }\nworker-2 = { solve-group = \"analysis\" }\nworker-3 = { solve-group = \"analysis\" }\nUse separate features when environments differ:
\n[feature.gpu.dependencies]\npytorch-cuda = \"*\"\n\n[feature.r.dependencies]\nr-base = \"*\"\n\n[environments]\ncpu = []\ngpu = [\"gpu\"]\nr-analysis = [\"r\"]\nFor VS Code/Jupyter kernels, add explicit kernel tasks:
\n[tasks]\nkernel-1 = \"python -m ipykernel install --user --name worker-1 --display-name 'Python (worker-1)'\"\nkernel-2 = \"python -m ipykernel install --user --name worker-2 --display-name 'Python (worker-2)'\"\nkernels = \"pixi run -e worker-1 kernel-1 && pixi run -e worker-2 kernel-2\"\nTell VS Code users: after registration, select the kernel in VS Code; they do not need to launch notebooks through pixi run.
Use mirrors deliberately. Do not assume a mirror works for all package types.
\nRecommended checks:
\npixi config list\nsed -n '1,120p' ~/.config/uv/uv.toml 2>/dev/null\nsed -n '1,120p' ~/.config/pip/pip.conf 2>/dev/null\nenv | rg \"PIP|UV|PIXI|RATTLER|HTTP|HTTPS|PROXY\"\nFor PyPI, prefer setting only the index URL in pixi.toml:
[pypi-options]\nindex-url = \"https://example-mirror/simple\"\nAvoid 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.
\nFor conda, use .pixi/config.toml mirrors when needed:
[mirrors]\n\"https://conda.anaconda.org/conda-forge\" = [\n \"https://your-conda-mirror/anaconda/cloud/conda-forge\",\n \"https://conda.anaconda.org/conda-forge\"\n]\nPixi 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]\nconda-pypi-map = { \"conda-forge\" = \"config/conda-pypi-map.json\" }\nExample config/conda-pypi-map.json:
{\n \"scikit-learn\": \"scikit-learn\",\n \"matplotlib-base\": \"matplotlib\",\n \"pytorch\": \"torch\",\n \"torchvision\": \"torchvision\",\n \"torchaudio\": \"torchaudio\"\n}\nValidate it:
\npython -m json.tool config/conda-pypi-map.json\nKeep this mapping small and project-specific. Add entries only for packages relevant to mixed solving.
\nIf a package is not found on PyPI or conda, inspect how it was installed before guessing.
\nCheck old environment metadata:
\nfind /path/to/env/lib/python*/site-packages -maxdepth 3 \\\n \\( -iname '*dist-info' -o -path '*dist-info/direct_url.json' \\)\nUse local path dependency when reproducible on this machine:
\n[pypi-dependencies]\nmy-package = { path = \"/absolute/path/to/source\" }\nUse Git dependency when portability matters:
\n[pypi-dependencies]\nmy-package = { git = \"https://github.com/org/repo.git\", rev = \"commit-sha\" }\nPrefer a fixed commit/tag for reproducibility.
\nRoot cause: package is unpublished, private, named differently, or only installed from source.
\nActions:
\ndirect_url.json.Root cause: conda pinned a transitive package version that conflicts with PyPI requirements.
\nActions:
\nRoot cause: inaccessible PyPI index, file host, proxy, or mirror.
\nActions:
\n[pypi-options] index-url.pixi clean cache --pypi -y\npixi install --all\nRoot cause: simple index mirror works but wheel metadata/file mirror is incomplete.
\nActions:
\nfiles.pythonhosted.org mirror rewrites.Root cause: conda opencv pulls GUI/Qt/Python ABI-specific builds.
Server/headless fix:
\n[pypi-dependencies]\nopencv-python-headless = \">=4.10,<5\"\nUse conda opencv only when GUI functionality is required.
Root cause: CUDA runtime, driver, PyTorch build, and channel priorities disagree.
\nActions:
\nnvidia-smi.torch.cuda.is_available().Pixi has default cache. Do not create custom cache directories unless the user requests shared cache, has permission errors, or needs a specific storage path.
\nUseful commands:
\npixi clean cache --pypi -y\npixi clean cache --repodata -y\npixi clean cache --mapping -y\nIf custom cache is needed:
\nPIXI_CACHE_DIR=/path/to/pixi-cache \\\nRATTLER_CACHE_DIR=/path/to/rattler-cache \\\npixi install --all\nAdd a check task for complex environments. It should verify the actual success criteria, not just installation.
Examples:
\n[tasks]\ncheck = \"python -c \\\"import sys; print(sys.version)\\\"\"\nFor GPU Python environments:
\ncheck = \"python -c \\\"import torch; print(torch.__version__); print(torch.version.cuda); print(torch.cuda.is_available()); print(torch.cuda.get_device_name(0) if torch.cuda.is_available() else 'NO GPU')\\\"\"\nRun:
\npixi run -e <environment> check\nFor Jupyter/VS Code workflows, verify kernel registration separately:
\npixi run kernels\njupyter kernelspec list\nconda-forge r-base ships with OpenBLAS, but when OPENBLAS_NUM_THREADS is unset on a\nhigh-core server, the default thread scheduling is extremely poor — SVD on 96 cores\nwithout explicit thread count is slower than single-threaded. This directly impacts\nSeurat RunPCA() (backed by irlba() randomized SVD).
OPENBLAS_NUM_THREADS and OMP_NUM_THREADS are both unsetPREFIX=$(pixi info --manifest-path pixi-workspaces/<env>/pixi.toml 2>/dev/null | grep \"Prefix location\" | awk '{print $NF}')\nreadlink -f \"$PREFIX/lib/libblas.so.3\"\nlibopenblasp-*.so → OpenBLAS, this section applieslibflexiblas.so → different approach needed (FlexiBLAS backend switching)pixi run --manifest-path pixi-workspaces/<env>/pixi.toml \\\n Rscript -e '\n cat(\"OPENBLAS_NUM_THREADS =\", Sys.getenv(\"OPENBLAS_NUM_THREADS\"), \"\\n\")\n set.seed(42); n <- 3000; X <- matrix(rnorm(n*n), n, n)\n t <- system.time({ svd(X, nu=10, nv=0) })\n cat(\"SVD(3000) time:\", round(t[\"elapsed\"], 3), \"sec\\n\")\n cat(\"Detected cores:\", parallel::detectCores(), \"\\n\")\n '\nfor threads in 1 8 16 32 64; do\n echo \"=== OPENBLAS_NUM_THREADS=$threads ===\"\n OPENBLAS_NUM_THREADS=$threads OMP_NUM_THREADS=$threads \\\n pixi run --manifest-path pixi-workspaces/<env>/pixi.toml \\\n Rscript -e '\n set.seed(42); n <- 3000; X <- matrix(rnorm(n*n), n, n)\n t <- system.time({ svd(X, nu=10, nv=0) })\n cat(\"SVD(3000) time:\", round(t[\"elapsed\"],3), \"sec\\n\")\n ' 2>/dev/null\ndone\nBenchmark results on AMD EPYC 7K62 (96 cores, Zen2):
\n| Threads | \nSVD(3000) Time | \nSpeedup | \n
|---|---|---|
| Default (unset) | \n~20 sec | \n1x (baseline) | \n
| 1 | \n~12 sec | \n1.6x | \n
| 8 | \n~3.8 sec | \n5.2x | \n
| 16 | \n~3.2 sec | \n6.2x | \n
| 32 | \n~2.9 sec | \n6.8x (optimal) | \n
| 64 | \n~3.3 sec | \n6.0x (overhead degrades) | \n
Rule of thumb: optimal thread count ≈ 1/3 of total cores (96→32, 64→16-24, 32→8-16).\nBeyond the sweet spot, thread synchronization overhead degrades performance.
\nAdd [activation.env] to the workspace pixi.toml:
[activation.env]\nOPENBLAS_NUM_THREADS = \"32\"\nOMP_NUM_THREADS = \"32\"\nTakes effect on every pixi run or environment activation. Jupyter kernels (IRkernel)\nregistered via pixi run kernel also inherit these variables.