# Use Pixi

> Use when explaining, creating, or changing a Pixi workspace, including manifests, dependencies, platforms, targets, features, environments, tasks, lockfiles, editable Python packages, CI commands, or IDE interpreter setup.

- Skill: `moeru-ai/use-pixi` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add moeru-ai/use-pixi`
- Raw SKILL.md: https://api.skillmd.com/api/skills/moeru-ai/use-pixi/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: moeru-ai (https://skillmd.com/u/moeru-ai)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/moeru-ai/use-pixi

---


# Use Pixi

Use Pixi as the command and environment boundary for this repository.

## Inspect before editing

1. Run `pixi --version`, `pixi info`, and `pixi task list` when available.
2. Locate both `pixi.toml` and `pyproject.toml`. Pixi discovers an explicit `--manifest-path` first, then a local `pixi.toml`, then a local `pyproject.toml`, then parent manifests. A sibling `pixi.toml` therefore wins over `pyproject.toml`.
3. Read the selected manifest, its `workspace.platforms`, targets, features, environments, tasks, and editable path dependencies.
4. Read `pixi.lock` when reproducibility or CI behavior matters. Do not hand-edit the lockfile.

## Choose the dependency owner

- Put Python itself and command-line/system packages supplied by conda-forge under Pixi `dependencies`.
- Put Python distributions resolved from PyPI under `pypi-dependencies` or `[project.dependencies]`, according to the repository's existing ownership boundary.
- Represent a local Python project as `{ path = ".", editable = true }` or another relative editable path in Pixi.
- Use `target.<platform>` for dependencies limited to one supported platform.
- Use a feature when a dependency set is optional and reusable; compose features into named environments.
- Do not use bare `pip install` inside a Pixi-managed repository. Use `pixi add`, a manifest edit, and a new lock instead.

## Understand the model

- A workspace declares channels and every platform solved into `pixi.lock`.
- A target narrows configuration to a platform such as `linux-64`, `win-64`, or `osx-arm64`.
- A feature groups optional dependencies, tasks, activation, and targets.
- An environment selects features and produces an installable prefix under `.pixi/envs/` by default; named or detached configuration may select another prefix.
- A task is a reproducible command executed inside an environment.
- The lockfile records exact conda and PyPI resolutions for every declared platform.

## Make and verify changes

Use the smallest applicable commands:

```bash
pixi add PACKAGE
pixi add --pypi PACKAGE
pixi remove PACKAGE
pixi remove --pypi PACKAGE
pixi update PACKAGE
pixi install
pixi run TASK
pixi shell  # interactive use only
pixi task list
pixi lock --check
```

### Install an editable local Python project

From the workspace root, add a local PyPI project in editable mode with a PEP 508 file URL:

```bash
pixi add --pypi --editable \
  "DISTRIBUTION_NAME @ ./RELATIVE_PROJECT_PATH"
```

- Read `DISTRIBUTION_NAME` from the local project's `[project].name`; do not assume it matches the Python import name.
- Inspect the local project's `requires-python` first and select a compatible workspace Python version, for example `pixi add python=3.11`.
- Expect the command to update the manifest, lockfile, and current environment. Pixi may serialize the expanded file URL as an absolute path.
- For a manifest that must work across clones or machines, prefer or restore a relative declaration such as:

```toml
[tool.pixi.pypi-dependencies]
distribution_name = { path = "relative/project/path", editable = true }
```

After a manual relative-path edit, run `pixi lock` and `pixi install`. Verify against the actual import package:

```bash
pixi run python -c "import IMPORT_NAME; print(IMPORT_NAME.__file__)"
pixi lock --check
```

When adding or removing a dependency, use `--feature FEATURE` for a named feature and `--platform PLATFORM` for a platform-specific table. Combine the selectors only when both scopes apply.

For local, intentional manifest changes, run `pixi lock`, the relevant `pixi run` task, and `pixi lock --check`. Inspect the manifest diff and lockfile diff before reporting success.

Keep the lockfile immutable in CI:

```bash
pixi install --locked
pixi run --locked TASK
```

`--locked` prevents lockfile updates; it does not make environment installation or task execution read-only. Inspect task definitions before running them in any no-write workflow.

CI must not run `pixi lock`, because that command mutates the lockfile.

## IDE boundary

Run `pixi install` before selecting an interpreter. For this template, `.pixi/envs/default` is the conventional default prefix and may be used as the VS Code `python.defaultInterpreterPath` folder for analysis and debugging. Locate named or detached environments using the `prefix` reported by `pixi info --json`, but never commit the returned absolute machine path. Documentation, automation, and terminal commands should use `pixi run`; Windows and POSIX interpreter paths differ.

## Safeguards

- Keep all declared platforms solvable; do not validate only the current host.
- Do not add CUDA or another platform-only dependency to unconditional common dependencies.
- Do not remove or regenerate unrelated environments.
- Do not claim success until the lockfile is current and the requested task passes.