Migrating to pixi 1.3

Two commands, one for each starting point:

From	Command
pip or uv: requirements.txt, [project.dependencies]	pypilot migrate-to-pixi
conda: environment.yml	pypilot migrate-conda --to pixi

Both are dry runs by default: they print the pixi.toml they would write as a diff and change nothing.

The rules

• A separate pixi.toml is written. pyproject.toml, requirements.txt and environment.yml are never edited or deleted, so CI and pip keep working. pixi prefers pixi.toml when both exist.
• Each PyPI dependency that is packaged on conda-forge (per prefix.dev's PyPI-to-conda mapping) and built for every target platform goes to [dependencies] under its conda name (torch becomes pytorch). The rest go to [pypi-dependencies], with the reason as a comment.
• Version specifiers carry over only when conda can express them exactly; otherwise the dependency stays on PyPI.
• python is the version PyPilot recommends, within what the conda-forge builds support.
• Platforms default to the current one; add more with --platform (repeatable), for example --platform linux-64 --platform osx-arm64.
• Environment markers, editable installs and -r includes are listed in the file as comments to add by hand.
• Offline, everything stays on PyPI. The mapping is cached for data_refresh_days.

Step by step: a pip project

1. Preview. In the project folder:

~/src/geo

$ pypilot migrate-to-pixi --platform linux-64
Dry run: nothing was written.

--- /dev/null
+++ b/pixi.toml
@@ -0,0 +1,13 @@
+# Written by `pypilot migrate-to-pixi` from requirements.txt (left untouched).
+# Review it, then run `pixi install`.
+
+[workspace]
+name = "geo"
+channels = ["conda-forge"]
+platforms = ["win-64", "linux-64"]
+
+[dependencies]
+python = "3.15.*"
+gdal = "*"
+numpy = "*"
+requests = "*"

Would write C:\src\geo\pixi.toml: python 3.15.*, 3 conda-forge and 0 PyPI dependencies.

Next: pypilot migrate-to-pixi --write

Every dependency was found on conda-forge for both platforms, so all three are conda dependencies and GDAL comes with its native libraries.

For a dependency conda-forge does not have, the preview says why it stays on PyPI:

[pypi-dependencies]
mediapipe = "==0.10.14"  # not on conda-forge

2. Write it, and optionally install in the same step:

pypilot migrate-to-pixi --write              # writes pixi.toml
pypilot migrate-to-pixi --write --install    # and runs pixi install

For a small project with requests and rich in requirements.txt, writing and installing takes a few seconds:

Wrote C:\src\px2\pixi.toml: python 3.15.*, 2 conda-forge and 0 PyPI dependencies.

  ✓ pixi install:             environment installed

The files it was made from were left untouched; CI and pip can keep using them.

Next: pixi run python

--install without --write is an error, because a dry run has nothing to install.

3. Check it.

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

── Environment ──────────────────────────────────────────
  uv              : present (v0.13.5, on PATH)
  pixi env        : C:\src\px\.pixi\envs\default (Python 3.15)
  pixi project    : C:\src\px\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.15.*
  dependencies    : conda: requests, rich · pypi: httpx>=0.28.1,<0.29

── pixi ─────────────────────────────────────────────────
  platforms       : win-64
  pixi.lock       : up to date
  environments    :
    • default (selected)  Python 3.15  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.15.*`)
    • httpx                3.8–3.15

── Findings ─────────────────────────────────────────────
  ✓ Everything looks good.

From now on PyPilot treats the folder as a pixi project: see PyPilot in pixi projects.

4. Commit pixi.toml and pixi.lock. Add .pixi/ to .gitignore.

Step by step: a conda project

# environment.yml
name: geo
channels:
  - conda-forge
dependencies:
  - python=3.11
  - numpy=1.26
  - gdal
  - pip
  - pip:
      - rich>=13

Dry run: nothing was written.

--- /dev/null
+++ b/pixi.toml
@@ -0,0 +1,16 @@
+# Written by `pypilot migrate-conda --to pixi` from environment.yml (left untouched).
+# Review it, then run `pixi install`.
+
+[workspace]
+name = "geo"
+channels = ["conda-forge"]
+platforms = ["win-64"]
+
+[dependencies]
+python = "3.11.*"
+numpy = "1.26.*"
+gdal = "*"
+pip = "*"
+
+[pypi-dependencies]
+rich = ">=13"

Would write C:\src\conda\pixi.toml: python 3.11.*, 3 conda-forge and 1 PyPI dependencies.

Next: pypilot migrate-conda --to pixi --write

Channels and conda packages are kept, conda pins become pixi specs (numpy=1.26 → 1.26.*), and the pip: section becomes [pypi-dependencies]. Then:

pypilot migrate-conda --to pixi --write --install

From the editor

How you confirm depends on where you start. Nothing is written before you choose.

• The Initialize pixi project button, on the workspace notification (the advisory) or on the toast after a pip/uv build failed on a system library: the same in Zed and VS Code, because the engine handles it. It runs a dry run and shows one message with the headline, PyPilot: Would write <path>/pixi.toml: python X.Y, N conda-forge and M PyPI dependencies. pyproject.toml and requirements.txt stay as they are; pypilot migrate-to-pixi shows the full preview. (with , K left for review when some lines could not be translated). The buttons are Write and install, Write pixi.toml and Cancel.
• VS Code: PyPilot: Initialize pixi project (palette): asks for the engine's preview (pypilot.migrateToPixi with { "write": false }), opens the full preview beside the editor, then asks in a modal write pixi.toml as shown in the preview? with Write pixi.toml and Write and run pixi install. Only then does it call the command again with { "write": true, "install": … }.
• CLI and Zed tasks: pypilot migrate-to-pixi previews (task pypilot: preview migration to pixi (pixi.toml)); --write writes and --write --install also runs pixi install (task pypilot: migrate to pixi (write pixi.toml and install)).
• Everywhere: package_manager = "pixi" makes setup write pixi.toml (as --write would) and run pixi install on a project without a pixi manifest.

Undo

Delete pixi.toml, pixi.lock and .pixi/. Nothing else was changed.