PyPilot for VS Code

⭐ Enjoying PyPilot? If it saved you from a broken environment, please star it on GitHub or leave a rating. It's free and it helps other Python developers find it.

PyPilot inspects Python projects, figures out which Python versions your dependencies actually support, and creates a working virtual environment. It resolves driver and CUDA compatibility for PyTorch or TensorFlow, checks package wheels on PyPI, and flags broken imports directly in the editor without external API calls.

This extension runs the same native Rust engine as PyPilot for Zed, integrated with VS Code surfaces: the command palette, status bar, progress indicators, interactive doctor report panel, and workspace tasks.

Documentation: https://pypilot-dev.github.io/pypilot/ (VS Code guide, commands, settings, pixi).

Features

• Environment setup: Runs uv init and uv add when no pyproject.toml exists. In pip mode, records installations using pip freeze > requirements.txt.
• Python version resolution: Evaluates PyPI wheel availability against requires_python to find an interpreter version that satisfies all dependencies.
• Hardware matching: Inspects host NVIDIA drivers via nvidia-smi and aligns torch or tensorflow with the correct CUDA runtime wheel.
• Import diagnostics: Flags missing or incompatible package imports in open files, with quick fixes to install or resolve them.
• Onboarding prompt: Scans opened folders and displays an actionable alert when environment issues need attention.
• Status bar: Displays the environment state with quick access to the report. Its tooltip shows the Python version, the environment path, the package manager PyPilot uses (uv, uv-pip, pip or pixi) and, in pixi projects, the pixi environment, read from files on disk without starting any process.
• Task integration: Provides workspace task definitions for environment bootstrap, health checks, and package maintenance.
• Report panel: Renders the doctor report in an interactive webview panel with fix buttons, Copy as Markdown and Save as HTML (a standalone page with inline styles in your current theme colors, no scripts).
• Multi-root workspaces: Each workspace folder with a Python project gets its own language server, settings and interpreter selection (see below).
• Relevant commands only: Project-specific commands are hidden from the Command Palette where they cannot apply (see the table below).

Requirements

• VS Code 1.85 or later.
• Network access during initial startup to download the native pypilot helper binary (approximately 3 MB), unless pypilot is already on PATH or pypilot.helperPath is set. Behind a proxy, VS Code's http.proxy (or the system proxy) is used; with http.proxySupport set to off, the HTTPS_PROXY / NO_PROXY environment variables are.
• Python does not need to be installed beforehand when using uv mode; uv downloads required interpreters directly.

Getting started

1. Open a Python project directory in VS Code.
2. PyPilot activates and scans the environment.
3. If an issue is found, a prompt appears with options to run the automatic fix or inspect the report.
4. The environment is configured for the Python version supported by your project dependencies.

The same steps are in the Get started with PyPilot walkthrough (Help > Welcome).

pixi

pixi installs packages from conda-forge and PyPI into a per-project environment, with a lock file. It helps where pip and uv stop:

• System libraries (GDAL, PROJ, GEOS, libGL...): pip and uv cannot install them; conda-forge ships them next to the Python bindings.
• No wheel for your platform or Python: conda-forge often has a prebuilt build, so no compiler is needed.
• The CUDA toolkit: pip wheels carry only the CUDA runtime, not nvcc; conda-forge provides it per project.
• One manifest for Python together with R, C++ or Rust, one lock file (pixi.lock) covering native dependencies on every listed OS, and several environments (for example default and cuda) in one project.

Guide: pixi and PyPilot.

pixi projects

A folder with a pixi.toml, or a pyproject.toml with [tool.pixi.workspace], is treated as a pixi project, whatever pypilot.packageManager says:

• The environment lives in .pixi/envs/<name>, where <name> is pypilot.pixiEnvironment (default unless set).
• PyPilot never creates a .venv there, never runs uv and never writes pixi.lock.
• Setup runs pixi install, package installs go through pixi add --pypi, and changing Python runs pixi add python=X.Y. When pixi fails, the report names the package to blame and the fix.
• With an engine newer than 1.2.2, the doctor report lists every pixi environment and warns about environments on different Pythons, a pixi.lock that no longer matches the manifest (a read-only check) and PyPI dependencies with no wheel for one of the manifest's platforms.

When PyPilot suggests pixi

With an engine newer than 1.2.2, PyPilot recognises problems pip and uv cannot solve in a pip or uv project and suggests pixi: a dependency with no wheel whose build needs native libraries, a failed build missing a header such as gdal.h, CUDA sources without nvcc, or a repository that mixes Python with R, Rust or C++. For a requirements.txt with numpy, requests and gdal on Windows, the report says:

[WARN ] GDAL 3.13.3 needs native libraries pip cannot install
        GDAL 3.13.3 has no wheel for Windows x64, so pip and uv build it from source. [...] pixi installs gdal 3.13.3 from conda-forge with its native libraries (libgdal, proj, geos), built for win-64 and Python 3.15. Run `pypilot migrate-to-pixi` to set the project up with pixi.

It only suggests. Nothing changes until you choose Initialize pixi project, on the notification or in the Command Palette. See the advisory.

Moving a project to pixi

PyPilot: Initialize pixi project opens the pixi.toml PyPilot would write as a preview, then writes it (optionally running pixi install) only after you confirm. It writes a separate pixi.toml and leaves pyproject.toml, requirements.txt and environment.yml untouched, so pip and CI keep working. Dependencies that conda-forge builds for every target platform become conda dependencies (torch becomes pytorch); the rest stay on PyPI with the reason as a comment. PyPilot: Install pixi installs pixi with its official installer if it is missing, and setting pypilot.packageManager to pixi makes setup write the pixi.toml itself. From a terminal, pypilot migrate-to-pixi and pypilot migrate-conda --to pixi do the same. Step by step: Migrating to pixi.

These commands and settings are new since 1.2.1 and need an engine newer than 1.2.2; with an older engine, Initialize pixi project asks you to update it and Install pixi offers to run pixi's installer in a terminal.

Multi-root workspaces

In a window with several folders, PyPilot runs one language server per folder that holds a Python project (a pyproject.toml, requirements.txt, pixi.toml, environment.yml, setup.py, setup.cfg, Pipfile, or any .py / .ipynb file). A folder without one gets a server as soon as you open a Python file from it.

• Each server checks only its own folder's files and uses that folder's settings (pypilot.* settings can differ per folder) and environment. Interpreter selection (pypilot.autoSelectVenv) works per folder too.
• Commands act on the folder of the active editor. With no editor open, PyPilot asks which folder to use. Quick fixes in the editor go to the server of the file's folder.
• A folder nested inside another workspace folder is handled by the outer one.
• Tasks (Tasks: Run Task) are listed per folder.
• Each server checks its folder on startup, so you may see one notification per folder.

A single-folder window works as before: one server, which also checks Python files opened from outside the folder.

Commands

Commands marked "Only when..." are hidden from the Command Palette in workspaces where they do not apply. They still run from the walkthrough, keybindings and the report panel.

Settings

Architecture

The extension is a TypeScript client wrapping the native Rust pypilot helper binary. On startup it uses pypilot.helperPath when set; otherwise the newer of a pypilot on PATH and the copy in the extension's storage; otherwise it downloads the engine version pinned in package.json. The helper communicates over standard I/O via the Language Server Protocol.

Engine pin and verification

package.json carries the engine pin, which the engine's release workflow bumps on each release:

"pypilotEngine": { "version": "1.2.2", "sha256": { "pypilot-windows-x64.zip": "<hex>", "...": "..." } }

Every download is hashed before anything is extracted. The pinned version must match the SHA-256 in package.json; any other version (pypilot.engineUpdates: "latest") must match the release's SHA256SUMS asset (<sha256> <asset> per line). On a mismatch the archive is deleted and nothing is installed; a release without SHA256SUMS is refused. There is no switch to install unverified engines: build one yourself and use pypilot.helperPath instead. The "PyPilot" output channel logs which helper is used and which checksum each download matched.

Settings reach the helper two ways: initializationOptions at startup (pixiEnvironment, diagnosticsScope) and the whole pypilot settings section through workspace/didChangeConfiguration (settings.pypilot.<key>), sent once after startup and on every change. In multi-root windows both are read for the server's folder.

pypilot-vscode/
├── src/
│   ├── extension.ts        Activation and onboarding flow
│   ├── clients.ts          One language client per workspace folder, server command routing
│   ├── downloader.ts       Helper resolution, pinned/verified engine downloads, update offers
│   ├── engine.ts           Engine pin, versions, SHA-256 and SHA256SUMS checks (no vscode import)
│   ├── net.ts              HTTPS requests, redirects, proxy tunnel (no vscode import)
│   ├── statusBar.ts        Status bar indicator and environment tooltip
│   ├── commands.ts         Command palette actions
│   ├── project.ts          File-based project checks and the palette context keys
│   ├── report.ts           Feeds the server's report Markdown to the report panel
│   ├── tasks.ts            Workspace task provider
│   ├── venv.ts             .venv / pixi env auto-selection via the Python extension APIs
│   └── webview/
│       └── reportPanel.ts  Doctor report webview, Markdown copy and HTML export
├── build.ts                Bun build script
├── bunfig.toml
└── package.json

Development

Build and package scripts use Bun:

# Install dependencies
bun install

# Compile extension
bun run build

# Watch mode during development
bun run build --watch

# Build vsix package
bun run package

# Unit tests (engine pin, verification, HTTP, report HTML)
bun test

# End-to-end in a real VS Code 1.85 (downloads VS Code; Linux needs xvfb-run -a)
bun run e2e
# ... hiding any installed pypilot, so activation downloads the pinned engine
PYPILOT_E2E_FRESH=1 bun run e2e

Support the project

PyPilot is free and open source, built and maintained in spare time. If it helps you:

• ⭐ Star it on GitHub: it's the easiest way to show support.
• 📝 Rate it on the Marketplace: reviews help others decide to try it.
• 🐛 Report a bug or request a feature: reproducible environment problems are especially welcome.

License

Apache-2.0. See the project repository license for details.