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.
• 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

Recommended Python Settings

To avoid conflicts with the Python extension's built-in environment management, add the following to your .vscode/settings.json:

{
  "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.
2. For all other files 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 to avoid unnecessary churn during tab switching.
4. 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.