UV Manager for VS Code
A Visual Studio Code extension that brings the full uv Python toolchain into your editor — built to complement the tools from Astral.
UV Manager gives you a full graphical interface for uv inside VS Code. Manage Python packages, virtual environments, Python versions, and the uv cache — all without leaving your editor.
✦ Features
|
|
| 📦 Package Management |
View, add, remove, and update packages with a single click |
| 🐍 Python Versions |
Install and pin Python versions using uv |
| 🌐 Virtual Environments |
Create and manage venvs directly from the sidebar |
| 🔗 Dependency Graph |
Interactive D3 force graph of every installed package — hover to trace what a package uses / is used by, drag to pin, search to spotlight |
| 🧬 Venv Anatomy |
Zoomable sunburst of a venv by size on disk, grouped by top-level package (exclusive deps) vs shared deps, plus a "heaviest packages" list |
| 🐍 Interpreter Matrix |
Python-logo grid of CPython / free-threaded / PyPy / GraalPy versions — see what's installed, your venv's interpreter and pin at a glance; click to install or pin |
| 🩺 Project Health |
Live uv → pyproject.toml → uv.lock → .venv pipeline on the Actions tab: spots a stale lockfile, a missing venv, a Python version that doesn't match .python-version, and packages that drifted from uv.lock — with a one-click fix |
| 🔎 Searchable Actions |
Type (or press /) to filter, arrow keys + Enter to run, hover to preview/copy the exact uv command, recent actions on top, collapsible groups |
| ▶️ Scripts panel |
[project.scripts], poe and taskipy tasks, and PEP 723 inline scripts as one-click buttons — with exit code, duration and a run-history timeline. Also available in Tasks: Run Task (type uv) for keybindings |
| 📜 PEP 723 inline scripts |
CodeLens above # /// script blocks: Run script · Add dependency · Lock · dependency list. UV: Add Inline Script Metadata turns any .py into a self-contained script |
| 🔢 Dependency hints |
In pyproject.toml and script blocks: locked and latest version after every dependency, a hover card (summary, release date, Python support), one-click / quick-fix bump that keeps your specifier style, and completion for package names and versions |
| 🖍️ TOML highlighting |
Full TOML grammar, plus PEP 508 colouring inside dependency strings (package, extras, versions, markers, URLs) and highlighted # /// script blocks in Python |
| 🎨 Follows your theme |
Every colour comes from your active VS Code theme — light, dark, high contrast or any custom theme — and updates live when you switch |
| 🗺️ Environment Explorer |
Open all of the above full-size in an editor tab |
| ⚡ Command Palette |
Run any uv command without leaving your keyboard |
| 🚀 One-click Install |
Installs uv for you if it's not already present |
| 🖥️ Cross-platform |
Works on macOS, Linux, and Windows |
⚡ Getting Started
1. Install uv — or let the extension do it for you:
# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
# Windows
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
2. Open the UV Manager sidebar from the VS Code Activity Bar.
3. Use the sidebar or Command Palette to manage packages, environments, and Python versions.
🛠 Requirements
- uv — the extension can install it automatically
- Python — for virtual environment and package management
📋 Commands
All commands are available via the Command Palette (Ctrl+Shift+P / Cmd+Shift+P) or the sidebar UI.
| Command |
Description |
UV: Refresh |
Reload package and environment info |
UV: Add Package |
Add a new package to your project |
UV: Remove Package |
Remove a package and its dependencies |
UV: Sync Environment |
Sync your environment with the lockfile |
UV: Run Script |
Run a script using uv |
UV: Install UV |
Install uv on this machine |
UV: Show Package Details |
View details and dependencies for a package |
UV: Open Environment Explorer |
Open the interactive venv / Python / package visualisations in an editor tab |
⚙️ Extension Settings
| Setting |
Default |
|
uv.dependencyHints.enabled |
true |
Locked / latest hints next to dependencies |
uv.dependencyHints.checkLatest |
true |
Look up latest versions on PyPI (cached 3 h). Turn off for fully offline use |
uv.pypiUrl |
https://pypi.org |
PyPI-compatible JSON API for lookups and completions |
No custom settings yet — UV Manager works out of the box.
Settings support is planned for a future release.
⚠️ Known Issues
- Some features may require the latest version of uv — keep uv updated for best results
- Only supports projects using uv for Python package management
📦 Release Notes
0.0.1 — Initial Release
First release of UV Manager for VS Code.
1.0.1 — Bug Fixes
Fixed issue #.
1.4.0 — Scripts, inline scripts, dependency hints, TOML highlighting
- Scripts tab: every
[project.scripts] entry, [tool.poe.tasks] / [tool.taskipy.tasks] task and PEP 723 script in the workspace, runnable with one click (or Enter), with arguments, stop, and go-to-definition. Runs are real VS Code tasks, so exit codes and durations are recorded: a D3 timeline of recent runs (height = duration, colour = result), per-script sparklines, pass rate and median time. Scripts are also exposed as uv tasks for Tasks: Run Task and keybindings.
- PEP 723: CodeLens on
# /// script blocks — Run script, Add dependency (uv add --script), Lock / re-lock (uv lock --script), and a dependency list with remove. New command UV: Add Inline Script Metadata inserts a block (Python version taken from your pin).
- Dependency hints in
pyproject.toml and script blocks: locked 2.32.3 · ↑ 2.33.0 minor after each dependency (click to bump), hover card with PyPI summary, latest release date and links, quick fix Bump X to … and Bump all outdated, completion of package names (from your venv, lockfile, uv cache and the most-downloaded PyPI projects) and versions. Bumps keep your specifier style (==, >=, ~=) and only drop an upper cap when the new version would violate it; afterwards you're offered uv sync / uv lock.
- Syntax highlighting: TOML grammar for
pyproject.toml, uv.lock etc.; PEP 508 requirement strings are coloured (package, extras, operators, versions, environment markers, URLs) only inside dependency arrays; # /// script blocks are highlighted as TOML in Python files. If you use another TOML extension, the requirement colouring is injected into its grammar too.
1.3.0 — Matches your theme
- All charts use your theme's own chart colours (
charts.*); extra categories are blends of them, so a theme switch recolours everything instantly with no reload.
- Graph lines and labels use
charts.lines / charts.foreground; tooltips use the hover-widget and shadow colours; the Environment Explorer tab uses the editor background instead of the sidebar's.
- High-contrast themes (dark and light): contrast borders on buttons, cards, tooltips and chart marks, stronger focus outlines, and no faint low-opacity states.
- The "Run in venv" button and CodeLens use a new
$(uv-run) product icon, so they're tinted like every other icon in your theme (was a fixed pink image).
- Fixed: the health pipeline could fail to draw if it refreshed while the Actions tab was hidden.
1.2.0 — Actions tab: project health & faster workflow
- Project health pipeline (D3):
uv → pyproject → uv.lock → venv, each stage coloured by status with a flowing link when healthy. Hover for details (e.g. which dependencies changed since the last lock); click to fix (lock, sync, init, recreate venv) or to open pyproject.toml / uv.lock.
- Lock vs installed drift bar: in sync / wrong version / not installed / not in lock. Click a segment to list the packages and sync. Platform-specific and optional dependencies in
uv.lock are not counted as missing.
- Recommended action: the single most important fix is shown as a banner and badged in the list.
- Health refreshes automatically when
pyproject.toml, uv.lock, .python-version or the venv change — including commands you run by hand in a terminal.
- Actions are searchable (
/ to focus, ↑/↓, Enter, Esc), show the exact uv command on hover with a copy button, remember your recent actions, and groups can be collapsed (remembered).
- "Install UV" shows the installed version; "uv cache size" shows the size inline when your uv supports it.
1.1.0 — Interactive visualisations
- Packages → Graph view: force-directed dependency graph (D3). Node size = install size; hover highlights dependencies (green) and dependents (orange); click opens details; drag to pin, double-click to release; filter box spotlights matches.
- Python → Interpreter matrix: every interpreter
uv python list knows about, drawn as Python logos by implementation × minor version. Your venv's interpreter glows, the .python-version pin is marked; click to pin an installed one or install a missing one.
- Venvs → Anatomy sunburst: click any venv card to see what's inside it by size on disk. Each top-level package owns its exclusive dependencies (what
uv remove would free); deps used by several packages are grouped as shared. Click to zoom, centre to go back.
- UV: Open Environment Explorer command (and title-bar button) opens everything full-size.
- Fixed: venv cards showed
Python ? for uv-created venvs (version_info in pyvenv.cfg).
- Fixed: package names are now PEP 503–normalised when building the tree, so
typing_extensions / typing-extensions are matched correctly.
🔗 Resources
Built with ♥ to complement the Astral ecosystem.
| |
