v1.4.0: Targeted Fixes & Known Breakages

✨ What's New

PyPilot 1.4.0 fixes what is actually wrong. Before, Fix environment and doctor --fix rebuilt the environment for every problem, and could move a project to another Python on the way. Now every finding brings its own fix. A healthy project is left alone, the Python moves only when a dependency forces it, and every file PyPilot edits is named.

We tested it on 54 deliberately broken environments: corrupted venvs, Python mismatches, dependency conflicts, pixi, conda and Poetry projects, and breakages collected from Stack Overflow and GitHub issues. 45 now get the right targeted fix (13 before), none get a wrong one (9 before) and none are missed (21 before). The rest are reported with what you need to change.

📖 New guide: What doctor --fix fixes

🎯 A fix for each problem

• Lock and environment drift: uv sync --locked for a missing or drifted package, uv lock for a stale lock, a reinstall of only the half-installed package.
• Damaged venvs (a missing interpreter or pyvenv.cfg, system site-packages leaking in) are rebuilt on the Python they had, in place, even in venv/ or env/.
• Python version: requires-python and .python-version are checked against the venv. An existing pin wins unless a dependency forces a change, the Python a fix picks is written to .python-version, and requires-python is raised when a dependency needs it. An impossible requires-python (>=3.16, >=3.10,<=3.9) is an error, and nothing is built.
• Honest results: a fix with a failed step no longer says "Done", and --dry-run lists exactly what the real run does. Running the fix twice changes nothing the second time.

🧩 Conflicts resolved before anything changes

• Unsatisfiable pins get a relaxed pin, checked with uv before it is offered. An edit that leaves the project unresolvable is rolled back.
• Typos get "did you mean", versions that do not exist get the nearest releases, and packages with no build for this OS get an environment marker (uvloop on Windows).
• Undeclared imports (notebooks included) are added with the right distribution: yaml becomes PyYAML and sklearn becomes scikit-learn. install and check accept import names too.

📚 Known breakages

A new data table, known_breakages.json, refreshed weekly like the others, covers breakages that package metadata does not show:

• numpy 2 breaking old compiled packages (pandas before 2.2.2).
• Uncapped dependencies that later removed an API: markupsafe and jinja2, werkzeug and flask, itsdangerous and flask, urllib3 and requests-toolbelt, sqlalchemy and flask-sqlalchemy, importlib-metadata and flake8, setuptools 82 and pkg_resources.
• Shadowing packages (jwt and PyJWT, enum34, typing) and yanked pins.
• Removed stdlib modules (distutils, imp, the 3.13 removals) and removed APIs in your own code (np.float, collections.Mapping, asyncio.coroutine, pydantic.BaseSettings, SQLAlchemy 2 engine.execute, pandas 2 DataFrame.append), reported by file and line with the replacement.
• Releases that break on a newer Python: SQLAlchemy 2.0.0 to 2.0.30 on 3.13+, Flask before 2.3.3 on 3.14+.

🧪 pixi, conda and Poetry

• pixi: doctor's pixi add python=X.Y is applied, and a broken prefix is repaired.
• A conda environment.yml moves to pixi and keeps its Python.
• Poetry projects are read (^ and ~ constraints, groups) and installed with Poetry.
• requirements.txt no longer overwrites pyproject.toml pins, lines with an obvious mistake are fixed, and the rest are reported by line number.

🛠️ Also

• New command: pypilot fix requirements. <mode> --help prints that mode's help.
• New fix.kind values in the JSON output; older kinds serialize as before. See the output reference.
• The Zed "fix environment" task now runs doctor --fix; a separate task keeps the full setup.
• Release builds moved off the retired macOS 14 runners.

---

📦 Installation

Via Zed (recommended): Install the PyPilot extension from the Zed extension registry

Via VS Code: PyPilot for VS Code

Via pip:

pip install --upgrade pypilot-cli

Verify a download:

sha256sum -c SHA256SUMS --ignore-missing
gh attestation verify pypilot-linux-x64.tar.gz -R pypilot-dev/pypilot

Full Changelog: v1.3.0...v1.4.0