pixi

Pixi — reproducible environments and tasks for agents

Use Pixi to manage conda and PyPI dependencies, multi-language environments, and workspace tasks. Select instructions by the current goal; load only the workflow and reference sections needed for that step.

Load only the current workflow

Resolve links relative to this skill directory, not the user's workspace. Load another workflow when the task reaches it.

Current goal	Read	Scope
Initialize or import a workspace	initialize	Manifest format, channels, platforms, existing Python projects
Add, remove, update, or upgrade packages	dependencies	Conda/PyPI specs, feature ownership, lock policy
Compose features and environments	environments	Default feature, isolated environments, solve groups
Run code or manage tasks	run	Project execution, task definitions, temporary execution
Inspect packages or troubleshoot	inspect	Diagnostics, reverse dependencies, targeted repair
Install or manage global CLI tools	global	Isolated global tools, exposure, update, uninstall

Examples of staged loading:

• Run an existing script: read run; load dependencies only if a package change is needed.
• Add a package to a named environment: read dependencies; load environments if its feature composition needs changing.
• Inspect a failure: read inspect; reinstall or update only when the diagnosis calls for it.

Shared rules

• Read the existing manifest and relevant project instructions before changing configuration. Preserve its format, channels, supported platforms, and toolchain unless the task requires changing them. Use --manifest-path when discovery could select another workspace.
• Declare dependencies through Pixi. Use pixi add or pixi add --pypi, rather than making undeclared installs with pip, conda, or mamba inside a Pixi environment.
• Features own dependencies; environments compose features. Use --feature with add/remove; use --environment with run/install/list. Check the composition before changing a feature shared by multiple environments.
• Prefer pixi run for project commands. It installs/synchronizes the selected environment as needed, so a separate install step is usually unnecessary. Use pixi exec only for an intentionally temporary, workspace-independent setup.
• Pixi generates pixi.lock; do not edit it by hand. Keep the manifest and lock file together in version control for reproducible application/research workspaces. Review their diff after dependency changes.
• Choose lock behavior deliberately: normal execution may refresh a stale lock; --locked requires agreement with the manifest; --frozen uses the lock without checking that agreement. Do not combine locked and frozen.
• Prefer human-readable output; use JSON when a program must parse it. Diagnose the selected environment before broad updates, cache clearing, or reinstalling.
• Examples were checked with Pixi 0.71.1. Use pixi --version and the installed command's --help to resolve version-specific options.

Common usage guide (few-shot)

Names beginning with example- or example_ are fictional placeholders for packages, features, environments, and paths. Replace them with the actual names after reading the workspace manifest.

1. Run existing project code directly

User: “Run the tests in the existing example-analysis environment.”

Response: “I'll use the project environment directly; run prepares it when needed, so a separate install step is normally unnecessary.”

pixi run -e example-analysis python -m unittest discover -s tests -p 'test_*.py' -v

Why: Run accepts executables as well as tasks. Quote the test pattern so the outer shell does not expand it. Use an explicit install when installation itself is the step being checked.

2. Resolve a package-source mismatch

User: “Our conda channels have no example-package 1.2.3 candidate. Use that version in example-analysis.”

Response: “I'll verify that PyPI provides the requested version, identify the feature owning the dependency, and replace its conda declaration. Here the example-tools feature belongs to the example-analysis environment.”

pixi remove --feature example-tools example-package
pixi add --feature example-tools --pypi 'example-package==1.2.3'
pixi run -e example-analysis python -c 'from importlib.metadata import version; print(version("example-package"))'
git diff -- pixi.toml pixi.lock

Why: A missing candidate calls for checking package availability, source, and constraints. Select a verified source and review the resulting changes.

3. Declare a named editable requirement

User: “Use the local example-local-package checkout as an editable dependency in example-analysis.”

Response: “I'll add a named local requirement to example-tools, the feature used by that environment.”

pixi add --feature example-tools --pypi --editable 'example-local-package @ ./packages/example-local-package'
pixi run -e example-analysis python -c 'import example_local_package; print(example_local_package.__file__)'

Why: A local PyPI requirement needs the package name before @. Add selects a feature; run selects an environment. The distribution name and import name come from the local package's metadata and source.

4. Select an isolated workspace explicitly

User: “Run the comparison in the existing temporary workspace without changing the main project's dependencies.”

Response: “I'll select its manifest explicitly and check its interpreter.”

pixi run --manifest-path temp/example-comparison/pixi.toml python -c 'import sys; print(sys.executable)'

Why: Explicit manifest selection scopes the command to the intended workspace. Use the reported interpreter path, including when environments are detached. Normal run can update that selected workspace's lock and installation.

5. Preserve a lock or require agreement with the manifest

User: “Run validation using the existing lock without refreshing it.”

Response: “I'll use frozen to preserve that lock. Use locked instead if you also require it to match the manifest.”

pixi run --frozen -e example-analysis python scripts/example_validate.py

Why: Locked checks manifest/lock agreement; frozen uses the existing lock without that check. Either can still install packages when the selected environment needs them.

6. Use exec intentionally for a one-off dependency

User: “Run this one-off helper with example-helper-package without adding it to the project.”

Response: “I'll use a separate temporary environment with Python and the helper's dependency.”

pixi exec --spec python --spec example-helper-package -- python scripts/example_helper.py

Why: Exec supplies temporary dependencies independently of the project lock. For maintained project code, declare the dependency in a feature and use run. Diagnose exceptions raised by the helper as application errors.

When a dependency-change chain fails

An earlier add may already have succeeded; && does not roll it back. Inspect git diff -- pixi.toml pixi.lock before retrying. Distinguish an unsatisfiable solve from an installation failure or an exception raised by the executed script. A successful pixi lock establishes lock state, not an installed environment.

Command help worth consulting

Run the installed command's help when choosing unfamiliar options. For nested commands, request help at the subcommand you will use.

Decision	Help command
Initialize or import a workspace	pixi init --help, pixi import --help
Choose dependency source and feature	pixi add --help, pixi remove --help
Run project code	pixi run --help
Install or resolve dependencies	pixi install --help, pixi lock --help
Update versions or requirements	pixi update --help, pixi upgrade --help
Compose an environment	pixi workspace environment add --help
Define a task	pixi task add --help
Run a one-off tool	pixi exec --help
Repair or clean an environment	pixi reinstall --help, pixi clean --help
Manage global tools	pixi global --help, then the relevant subcommand's help

Official reference documents

Start with the reference map for readable topic names, local snapshots, and upstream sources. The unmodified official llms.txt supplies the wider documentation index.

Read manifest for schema details, multi-environment for feature composition, lock file for reproducibility, conda/PyPI for mixed dependencies, and tasks for advanced task behavior, only as needed.

For less common commands, run pixi <command> --help. Build, publishing, authentication, editor, and CI instructions are indexed in the official llms.txt; consult their specific pages when the task needs them.