uv Auto venv

Stop switching venvs manually. Automatically activates uv Python environments the moment you switch tabs in VS Code.

Designed for monorepos with multiple Python projects, when working with scripts that use PEP 723 inline metadata, or in workspaces containing a mix of Python projects and scripts.

The Python extension's built-in venv discovery works well for single-project repositories, but falls short in these scenarios. For PEP 723 inline scripts it doesn't work at all.

Features

• Automatic venv activation — detects and activates the correct Python interpreter every time you change the active editor tab.
• PEP 723 inline scripts — recognises # /// script metadata and resolves the interpreter with uv python find --script <file>.
• Standard uv projects — runs uv python find from the active file's directory, letting uv resolve the project root automatically.
• Python Environments extension support — works with both the classic Python extension API and the new Python Environments extension, with per-file environment scoping for inline scripts.
• Manual trigger — use the command palette: uv Auto venv: Reload Virtual Environment.

Note: This extension does not create virtual environments for you. It only detects and activates the correct interpreter for the active file. Use uv sync or uv run to create environments as needed.

Requirements

• uv must be installed and available on your PATH.
• The Python extension for VS Code.

Installing uv

Follow the official installation guide, then verify:

uv --version

Compatibility with Python Environments Extension

Starting with VS Code 2026, Microsoft is rolling out a new Python Environments extension that replaces parts of the classic Python extension's environment management. When enabled via python.useEnvironmentsExtension, tools like debugpy and Pylance read the active interpreter from this new extension instead of the classic API.

uv Auto venv v1.5.0+ supports both modes automatically:

The extension detects which mode is active at startup and routes interpreter changes through the correct API. If the Python Environments extension is not installed, it falls back to the classic API automatically.

Recommended Settings

Add the following to your .vscode/settings.json. Choose the section that matches your setup:

With Python Environments extension (recommended for new setups)

{
  "python.terminal.activateEnvironment": false,
  "python.createEnvironment.contentButton": "hide",
  "python.useEnvironmentsExtension": true
}

Classic Python extension only

{
  "python.terminal.activateEnvironment": false,
  "python.createEnvironment.contentButton": "hide",
  "python.useEnvironmentsExtension": false
}

These settings prevent the Python extension's built-in environment management from interfering with this extension.

Extension Settings

How It Works

1. When you open or switch to a .py file that contains PEP 723 inline script metadata (# /// script), the extension runs uv python find --script <file> and sets the returned interpreter. (To save time on large files, only the first 4KB are checked).
2. For all other Python files (detected via VS Code's language ID, supporting .pyw and shebangs) it runs uv python find from the active file's directory, which respects pyproject.toml, .python-version, and uv's own resolution rules.
3. The interpreter is only updated when it differs from the currently active one, and tab-switching is debounced by 300ms to avoid unnecessary churn during rapid tab switching.
4. When python.useEnvironmentsExtension is enabled, the extension resolves the uv-discovered interpreter path into a Python Environment object and sets it via the python-envs API. This ensures debugpy, Pylance, and the status bar all reflect the correct interpreter.
5. The manual reload command forces a refresh and reapplies the interpreter, which can help when the language server does not pick up environment changes immediately.

Troubleshooting

If environments are not activating as expected, you can check the uv Auto venv output channel in VS Code (View -> Output, then select uv Auto venv from the dropdown) to see diagnostic logs and uv command errors. The log will also indicate which API path is being used (classic or python-envs).