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. With Python Environments enabled, registers the nearest pyproject.toml folder as a project and assigns its interpreter independently of other projects.
• Python Environments extension support — works with both the classic Python extension API and the new Python Environments extension. Regular projects keep their own environments, standalone scripts share an environment selection that follows the active script, without adding per-script settings entries.
• 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 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.

Projects and standalone scripts in a monorepo

Regular projects keep independent environments and are added to python-envs.pythonProjects when first opened, with one settings entry per project. PEP 723 scripts share an environment that follows the active script, without per-script entries. Keep scripts outside regular projects, or register a dedicated scripts subfolder once using Add as Python Project. Otherwise script switching is skipped to protect the project's environment.

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,
  "python.analysis.usePerProjectEnvironments": true
}

Classic Python extension only

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

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 for the shared script scope. To save time on large files, only the first 4KB are checked. A missing script environment leaves the current selection intact.
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 selection for that scope, and tab-switching is debounced by 300ms. Results from obsolete tab selections are discarded and interpreter updates are serialized.
4. When python.useEnvironmentsExtension is enabled, regular projects are registered at their nearest pyproject.toml folder within the workspace and assigned the uv-discovered interpreter through the python-envs API. Files without a project marker use their existing owning scope. If environment resolution or assignment fails, the extension logs the error and keeps the current selection instead of falling back to workspace-wide switching. Pylance uses project assignments with the recommended setting above.
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).