PyPilot in pixi projects

Detection

A project is a pixi project when it has:

• a pixi.toml, or
• a pyproject.toml with [tool.pixi.workspace].

pixi prefers pixi.toml when both exist, and so does PyPilot. Detection overrides package_manager: the environment of a pixi project belongs to pixi, and a .venv or uv.lock beside it would be a second, competing environment.

The environment

	Where it comes from
Environment	.pixi/envs/<name>, <name> = --pixi-env, else the pixi_environment setting (VS Code: pypilot.pixiEnvironment), else default
Python	the interpreter in that environment
Installed packages	conda and PyPI packages in that environment (conda packages count as installed for import diagnostics)
GPU checks	the torch/tensorflow builds in that environment
Recommended Python	the newest the dependencies support within the manifest's python spec

If the selected environment does not exist in the manifest, doctor says so, names the environments that do, and falls back to default.

Commands, translated

You run	PyPilot runs
pypilot setup, Fix environment	pixi install
pypilot install httpx, an import quick fix	pixi add --pypi httpx
pypilot fix python, the "recreate on Python X.Y" quick fix	pixi add python=X.Y
pypilot fix cuda	nothing: pixi projects are never re-pinned to a PyTorch index

PyPilot install: installing httpx...
── Steps ────────────────────────────────────────────────
  ✓ pixi add --pypi httpx:    added to the pixi manifest and installed

  ✓ Done. Successfully installed httpx.

When pixi install fails, PyPilot turns the error into the same plain explanation it gives elsewhere: which package has no wheel for the environment's Python, and the fix, for example pixi add python=3.11.

What doctor checks

Engine 1.2.2 and older report an environment that is not installed yet or has no Python. The checks below marked 1.3 are new in engine 1.3.0.

The pixi section lists the target platforms, the lock status, and every environment with its features, Python and dependencies (conda and PyPI separately).

• 1.3 Every environment. An environment is its features plus the default feature (unless it says no-default-feature = true); PyPilot merges them the way pixi does, so python = ">=3.11" at the top and python = "3.11.*" in a feature give 3.11, and 3.12.* with 3.11.* cannot be solved. Each environment's PyPI dependencies are checked against its Python.
• 1.3 Different Pythons. Environments on different Python versions get an Info finding, in case that was not a deliberate test matrix.
• 1.3 The lock. pixi lock --check --dry-run (which writes nothing) tells whether pixi.lock still matches the manifest. A stale lock gets a warning with the changes re-locking would make; a manifest that no longer solves gets an error with pixi's reason. A missing lock gets an Info finding.
• 1.3 Every platform. pixi solves the lock for every platform in [workspace] platforms, so a PyPI dependency with no wheel for one of them breaks pixi lock and pixi install on every machine, including yours. PyPilot catches that from PyPI metadata before pixi does.
• Not installed yet. An environment that was never installed gets a warning pointing at pixi install.

A project with a second environment pinned to 3.12, after editing the manifest:

PyPilot doctor: C:\src\px2
  package manager : Auto

── Environment ──────────────────────────────────────────
  uv              : present (v0.13.5, on PATH)
  pixi env        : C:\src\px2\.pixi\envs\default (Python 3.15)
  pixi project    : C:\src\px2\pixi.toml
  interpreters    : 3.15 (python3), 3.14 (C:\Python314\python.exe)
  data tables     : refreshed 3 hours ago (next in 6 days); 1 of 5 bundled

── Project ──────────────────────────────────────────────
  files           : requirements.txt, pixi.toml
  pixi python     : python >=3.12
  dependencies    : conda: requests, rich · pypi: httpx>=0.28.1,<0.29

── pixi ─────────────────────────────────────────────────
  platforms       : win-64
  pixi.lock       : out of date (42 changes)
  environments    :
    • default (selected)  Python 3.15  conda: requests, rich  pypi: httpx
    • py312  Python 3.12 (not installed)  features: py312  conda: requests, rich  pypi: httpx

── Compatibility ────────────────────────────────────────
  supported Python: 3.8–3.15
  recommended     : Python 3.15 (newest the dependencies support within pixi's `python >=3.12`)
    • httpx                3.8–3.15

── Findings ─────────────────────────────────────────────
  [INFO ] pixi environments run different Python versions
          `default` Python 3.15, `py312` Python 3.12. Code that works in one can fail in another; if that is not a deliberate test matrix, align the `python` pins in the features.
  [WARN ] pixi.lock is out of date with pixi.toml
          pixi.toml changed since pixi.lock was written, so the installed environments may not match it. Re-locking would change: py312: + (conda) _python_abi3_support 1.0 hd8ed1ab_3; py312: + (pypi) anyio 4.15.1; py312: + (conda) backports.zstd 1.8.0 py312h301c71d_1; py312: + (conda) brotli-python 1.2.1 py312ha763cb9_0; py312: + (conda) bzip2 1.0.8 h0ad9c76_10; and 37 more. Run `pixi lock` to update the lock, or `pixi install` to update it and the environment.

Choosing the environment 1.3

# pypilot.toml
pixi_environment = "cuda"

pypilot doctor --pixi-env cuda      # for one run

In VS Code, set pypilot.pixiEnvironment; the interpreter switches to .pixi/envs/<name> too. Install a non-default environment with pixi install -e <name>.