The engine

pypilot is a single native binary, written in Rust, that is both a command-line tool and a language server. The Zed extension, the VS Code extension and the pypilot-cli package all run it; nothing else holds logic.

pypilot <MODE> [ARG] [--path <dir>]

Mode	Changes things?	Does
doctor	no	Environment and compatibility report (the default mode); --fix 1.3 then runs setup
check <package>	no	Can this package run on this project's Python?
explain [package] 1.3	no	Why these Pythons: requires_python vs wheels per platform
setup	yes	Build the environment on the recommended Python
install <package>	yes	Install one package and record it in the manifest
fix python	yes	Rebuild the environment on the right Python
fix cuda	yes	Re-pin torch/tensorflow to the build for your driver
update-data	cache only	Refresh the bundled data tables now; --check 1.3 only compares
migrate-conda	writes a file	environment.yml to pyproject.toml (or pixi.toml 1.3)
migrate-to-pixi 1.3	with --write	Preview or write a pixi.toml
install-pixi 1.3	installs pixi	Run pixi's official installer
logs 1.3	no	The local log's path, or its last entries
completions <shell> 1.3	no	Shell completion script
version 1.3	no	Version, commit, target and data-table state
lsp	none	Language server over stdio

Modes marked 1.3 are new in engine 1.3.0; older releases have the others. doctor, check and explain only read. setup, fix and install share their code with the matching editor actions, so the terminal and the editor cannot disagree, and 1.3 each takes --dry-run to show its plan first.

~/src/gpu

$ pypilot doctor
PyPilot doctor: C:\src\gpu
  package manager : Auto

── Environment ──────────────────────────────────────────
  uv              : present (v0.13.5, on PATH)
  virtualenv      : none
  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           : pyproject.toml
  requires-python : >=3.10
  dependencies    : torch, transformers

── Compatibility ────────────────────────────────────────
  supported Python: 3.11–3.15
  recommended     : Python 3.15
    • torch                3.11–3.15
    • transformers         3.11–3.15

── Findings ─────────────────────────────────────────────
  [WARN ] No environment set up yet
          Dependencies support Python 3.11–3.15. Recommended: 3.15 (upper bound set by torch, which supports 3.11–3.15).
  [INFO ] torch build matched to your driver: cu132
          NVIDIA RTX A5000 Laptop GPU's driver (596.86) supports CUDA up to 13.2. NVIDIA RTX A5000 Laptop GPU (Ampere, sm_86) needs a build against CUDA 11.1 or newer. Recommended: pip install torch==2.15.0 --index-url https://download.pytorch.org/whl/cu132

Everyday use

pypilot                      # same as pypilot doctor
pypilot doctor --path ../api # another folder
pypilot check torch          # will torch run here?
pypilot check "numpy<2"      # requirements work too
pypilot explain              # what blocks each Python in this project
pypilot setup                # build .venv (or the pixi env) on the right Python
pypilot install httpx        # add a dependency through uv, pip or pixi
pypilot setup --dry-run      # (1.3) what setup would run, changing nothing
pypilot doctor --json        # (1.3) the whole report for a script or an issue

The full reference with every flag is on Command reference. For scripting, see Machine-readable output; for previews, Dry runs; for the local log and tab completion, Logs, version & completions.

Where things live

What	Where
Global config	config.toml in the platform config directory (for example ~/.config/pypilot/config.toml on Linux)
Project config	.zed/pypilot.toml, else pypilot.toml, in the project root
PyPI metadata cache, refreshed data tables, the local log 1.3	the platform cache directory: %LOCALAPPDATA%\PyPilot\pypilot\cache on Windows, ~/Library/Caches/dev.PyPilot.pypilot on macOS, ~/.cache/pypilot on Linux (the log is in logs/)

See Configuration.