Python Virtual Environments in VS Code: The Complete Setup Guide

Set up Python virtual environments in VS Code the right way: interpreter selection, auto-activate, requirements.txt workflow, and common errors fixed.

Ekin Yalgın

April 18, 2026·5 min read

Python Virtual Environments in VS Code: The Complete Setup Guide

The 'activated environment is not the same as the selected Python interpreter' error in VS Code usually triggers when your terminal loads a default shell profile before the Python extension can inject the correct path. You end up installing packages globally by accident, and this breaks your project dependencies immediately. Let us fix this state mismatch and configure a robust virtual environment setup.

Key Configuration Details

Fastest setup: Command Palette > Python: Create Environment
Default environment folder name: .venv
Interpreter selection storage: Workspace internal state (not settings.json)
Key setting for terminal conflicts: python.terminal.activateEnvironment
Current standard: Python 3.13+ automatically adds a .gitignore inside new venv folders

How VS Code Discovers Python Environments

VS Code does not magically know where your packages live. The editor relies on a strict auto-discovery hierarchy to locate Python environments.

The Auto-Discovery Hierarchy

When you open a folder, the Python extension scans specific locations in a precise order. It looks at the workspace root for folders named .venv or venv first. If it finds one, it automatically flags it as the active environment for your project. This is exactly why sticking to standard naming conventions saves you hours of configuration headaches.

If the workspace root has no recognizable environment, the editor falls back to global installations or environments managed by tools like Conda or Poetry. You can always override this priority by manually selecting an interpreter.

Python 3.13 and the .gitignore Update

Creating a virtual environment with Python 3.13 or newer automatically generates a .gitignore file inside the environment folder. This small update prevents you from accidentally committing thousands of dependency files to your Git repository. It keeps your commits clean and your repository lightweight.

Setting Up a Virtual Environment

You have two reliable ways to create your environment. Both methods yield the exact same folder structure, but the editor integration differs slightly.

Using the Command Palette

This is the most seamless method available. Open the Command Palette using Ctrl+Shift+P (or Cmd+Shift+P on Mac) and type Python: Create Environment.

Select Venv as your environment type. The editor will ask you to choose a base interpreter from your system. Once selected, VS Code builds the .venv folder and automatically binds it to your current workspace session. You do not need to run any manual activation commands.

Manual Terminal Setup

Sometimes you need more control. Open your integrated terminal and run the standard creation command.

python -m venv .venv

After the command finishes, you will see a prompt in the bottom right corner asking if you want to select this new environment for the workspace folder. Always click Yes. If you miss the prompt, open the Command Palette and run Python: Select Interpreter manually.

To keep your pip installation current inside the new environment, run python -m pip install --upgrade pip right after activation. And if you want to hide the .venv folder and pycache from the VS Code file explorer, a two-line settings entry does the job cleanly.

Managing Interpreter Selection and Workspace State

A common misconception plagues almost every tutorial online: they claim that selecting an interpreter saves the path directly into your workspace settings. This is incorrect and leads to severe configuration issues.

Why Interpreter State is Not in settings.json

VS Code stores your active interpreter selection in an internal workspace state database, not in .vscode/settings.json.

This design choice is intentional. It prevents developers on the same team from constantly overwriting each other's local paths during Git merges. Your local .venv path stays local to your machine. You only use the settings file when you want to force a strict, shared interpreter path for every developer on the project.

Configuring Multi-Root Workspaces

Working with a multi-root workspace requires a different approach. Since you have multiple independent folders loaded into one window, the internal state might get confused about which environment belongs where.

Open the Command Palette and select Python: Select Interpreter for each specific folder in the workspace. The editor maintains a separate internal state for each root directory. This ensures your backend API uses its own dependencies while your data processing scripts use completely different packages.

Fixing the Activated Environment Mismatch Error

This is the most frustrating error developers face. You select your environment, but the integrated terminal keeps using the global Python path.

Understanding python.terminal.activateEnvironment

The root cause lies in how VS Code handles terminal injection. Check your settings for python.terminal.activateEnvironment.

When this is set to true, the editor tries to run an activation script the moment you open a new terminal. However, if your default shell (like Zsh or PowerShell) takes too long to load its own profile, it overwrites the VS Code injection. Fix this by switching the terminal profile to a simpler shell or restarting VS Code entirely.

Resolving Pre-Activated Terminal Conflicts

Never launch VS Code from a terminal that already has a virtual environment activated.

If you run source .venv/bin/activate in your system terminal and then type code ., the editor inherits those environment variables globally. This locks VS Code into that specific environment and breaks the internal selection mechanism. Always launch the editor cleanly from your application launcher or a fresh terminal session.

Solving Pylance ModuleNotFoundError

You activated the terminal correctly, your code runs fine, but Pylance keeps underlining your imports with a red squiggly line.

Setting Explicit Paths for IntelliSense

Pylance sometimes fails to read the internal workspace state quickly enough. Provide an explicit fallback path to fix the IntelliSense engine.

Open your .vscode/settings.json file and add the python.defaultInterpreterPath key. Set its value to ${workspaceFolder}/.venv/bin/python on Mac and Linux, or ${workspaceFolder}/.venv/Scripts/python.exe on Windows. This tells Pylance exactly where to look for module definitions, clearing those false-positive import errors and restoring autocomplete.

{
  "python.defaultInterpreterPath": "${workspaceFolder}/.venv/bin/python"
}

Once the environment is correctly bound, any Python environment variables you define in a .env file at the project root will also be picked up automatically by the Python extension.

FAQ

Frequently Asked Questions

Open the Command Palette with Ctrl+Shift+P, type Python: Create Environment, and select Venv. VS Code builds a .venv folder and binds it to your workspace automatically. No manual activation script is needed.

The most common cause is your default shell profile loading before VS Code can inject the environment path. Set python.terminal.activateEnvironment to true in your settings. Also make sure you did not launch VS Code from a terminal that already had a venv active.

venv is the standard Python tool for lightweight, project-specific isolation using the system Python. Conda manages both Python versions and binary packages, making it better suited for data science projects with complex dependencies like NumPy or PyTorch.

Open the Command Palette and run Python: Select Interpreter. VS Code stores your choice in internal workspace state, not in settings.json, so it stays local to your machine and does not affect teammates.

.venv is the recommended folder name for Python virtual environments. The leading dot makes it hidden by default on Mac and Linux. Python 3.13 and newer automatically creates a .gitignore inside the folder to prevent accidental commits.

VS Code activates the environment automatically in new terminals when python.terminal.activateEnvironment is set to true and your .venv folder is in the workspace root. No separate activation command is required.

Open the integrated terminal, verify the correct interpreter is shown in the status bar, then run: pip install -r requirements.txt. The packages install into the active virtual environment, not the global Python installation.

Pylance sometimes cannot read the internal workspace state in time. Add python.defaultInterpreterPath to .vscode/settings.json and point it to .venv/bin/python on Mac/Linux or .venv/Scripts/python.exe on Windows. This gives Pylance an explicit path to fall back on.

Published in

Programming