Python Venv Switcher

Automatic virtual environment switching for Python monorepos.

Venv Switcher automatically finds and activates the correct Python virtual environment in VS Code for the current file.

Features

Automatically detects virtual environments managed by:

• PDM
• Poetry
• Pipenv
• And more, with custom providers

Supports most project layouts:

• Locates virtual environments outside (and inside) of the VS Code workspace.
  
• Handles multiple environments per file.
  
• Updates the working directory used for test discovery based on the active file's Python project.

Settings

Create Workspace

Setting key: python.venv.switcher.createWorkspace

VS Code only allows a virtual environment to be set if a workspace is open. When an environment is detected for an open file but no workspace is open, this setting controls whether a new workspace is created to activate the virtual environment.

Custom Provider

Setting key: python.venv.switcher.customProvider

A command that returns the full path to the virtual environment's Python executable. If set, overrides the default environment resolution logic.

For example, use uv python find to resolve an environment managed by uv.

CWD Template

Setting key: python.testing.cwdTemplate

If set, update the python.testing.cwd setting used by the Python extension to discover tests based on the active project. Use ${projectRoot} as a placeholder for the root directory of the active project.

For example, use ${projectRoot} to locate tests in a tests directory:

project1/
    project1/
        __init__.py
        code.py
    tests/
        __init__.py
        test_code.py
    pyproject.toml

Commands

Activate Python Environment

Manually trigger the environment resolution for the current file. Run this command if the environment has changed, such as after running poetry env use.

Reset Venv Switcher Cache

Re-check for supported virtual environment providers and forget previously resolved environments. Run this command after installing a supported environment provider, such as Poetry. (Providers are checked when the extension is first activated, and when the Custom Provider setting is modified.)