How to Set Up a Python Virtual Environment in VS Code: Complete vscode venv Configuration Guide

Visual Studio Code automatically detects and activates Python virtual environments through the Python extension by scanning for standard folder patterns like .venv and injecting activation variables into new terminal sessions.

The microsoft/vscode repository reveals that VS Code does not bundle its own Python runtime; instead, the official Python extension handles vscode venv discovery and management. When you create a virtual environment in your workspace, the extension identifies the interpreter path and configures the integrated terminal for seamless activation.

How the Python Extension Detects Virtual Environments

Workspace Scanning in pythonEnvironments.ts

According to the microsoft/vscode source code, detection begins in extensions/python/src/pythonEnvironments.ts. The extension monitors workspace folders for standard virtual environment patterns including **/.venv/**, **/env/**, and **/venv/**.

When the extension identifies a candidate folder, it constructs a PythonEnvironment object representing the discovered interpreter.

Interpreter Resolution via pyvenv.cfg

The extensions/python/src/pythonEnvInfoService.ts file handles metadata parsing. For each detected environment, the extension reads the pyvenv.cfg file to determine the base Python version and validate the interpreter executable path at <env>/bin/python (or Scripts\python.exe on Windows).

Automatic Terminal Activation Mechanism

Environment Variable Injection

Before launching a terminal, VS Code injects platform-specific activation variables. The src/platform/terminal/common/environmentVariableCollection.ts defines variables such as VSCODE_PYTHON_BASH_ACTIVATE and VSCODE_PYTHON_PWSH_ACTIVATE. These variables store the path to the appropriate activation script for your shell environment.

Terminal Integration

When you open a new integrated terminal, the terminal service implemented in src/vs/workbench/contrib/terminal/browser/terminal.ts reads the injected variables. It automatically executes the activation command—such as source .venv/bin/activate on macOS/Linux or . .venv\Scripts\Activate.ps1 on Windows PowerShell—ensuring the session starts within the selected virtual environment.

Step-by-Step vscode venv Setup

Follow these steps to create and configure a Python virtual environment in VS Code:

1. Create the virtual environment in your workspace root:

python -m venv .venv

2. Open the folder in VS Code:

code .

3. Allow the Python extension to detect the environment. The extension scans the workspace and displays the discovered interpreter in the status bar (e.g., "Python 3.x.x .venv").

4. Select the interpreter using the Command Palette (Ctrl+Shift+P → "Python: Select Interpreter") and choose ".venv • Python 3.x.x".

5. Open a new integrated terminal (`Ctrl+``). VS Code automatically activates the environment by running the appropriate activation script for your platform and shell.

If automatic activation fails, you can manually activate the environment:

# macOS / Linux

source .venv/bin/activate

# Windows PowerShell

. .venv\Scripts\Activate.ps1

Summary

• VS Code relies on the Python extension to manage virtual environments rather than implementing native Python runtime support.
• Automatic detection occurs through pattern matching in pythonEnvironments.ts, which scans for folders like .venv, env, and venv.
• Metadata parsing in pythonEnvInfoService.ts reads pyvenv.cfg to resolve interpreter paths and versions.
• Terminal auto-activation uses environment variables (VSCODE_PYTHON_BASH_ACTIVATE, VSCODE_PYTHON_PWSH_ACTIVATE, etc.) defined in environmentVariableCollection.ts to source activation scripts automatically.
• Manual activation remains available by running the activation script directly when needed.

Frequently Asked Questions

Does VS Code create the virtual environment automatically?

No. According to the microsoft/vscode source code, VS Code only detects and manages existing environments. You must create the venv manually using python -m venv .venv or similar commands before the Python extension can discover it.

Why isn't my venv showing in the Python interpreter list?

The extension scans for specific folder patterns defined in extensions/python/src/pythonEnvironments.ts. Ensure your virtual environment folder is named .venv, env, or venv, or reload the window (Ctrl+Shift+P → "Developer: Reload Window") to trigger a rescan. The folder must also contain a valid pyvenv.cfg file readable by extensions/python/src/pythonEnvInfoService.ts.

How do I disable automatic venv activation in the terminal?

You can disable automatic activation by setting the python.terminal.activateEnvironment configuration to false in your settings.json. This prevents the terminal service from injecting the VSCODE_PYTHON_*_ACTIVATE variables and running activation scripts.

Can I use venv with WSL or remote containers?

Yes. The detection mechanism in pythonEnvironments.ts and the terminal activation variables in environmentVariableCollection.ts work across WSL, SSH, and Dev Containers. The extension resolves the interpreter path relative to the remote filesystem and injects the appropriate activation commands for the remote shell environment.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}