Using Python Environments In Visual Studio Code

Python environments in VS Code

The Python Environments extension brings environment and package management into Visual Studio Code's UI. The extension provides a unified interface for creating environments, installing packages, and switching interpreters, regardless whether you're using venv, uv, conda, pyenv, poetry, or pipenv.

Core features:

• Creating, deleting, and switching between environments
• Installing and managing packages
• Activated Python in terminals
• Assigning environments to specific files or folders (called "Python projects")

The extension works alongside the Python extension and requires no setup to get started.

Quick start

Most users don't need to configure anything. The extension automatically discovers your Python environments and uses them when running code.

If you have a basic setup, such as one environment for your whole workspace:

1. Open a Python file
2. Check the Status Bar to see which environment is active
3. To switch environments, select the environment control in the Status Bar

Need to create an environment? Open the Python sidebar, expand Environment Managers, and select the + button. The extension walks you through the different steps.

User interface components

Environment discovery

The following environment managers are discovered automatically:

Manager	Search locations
venv	Workspace folders (configurable via workspaceSearchPaths)
System Python	PATH, /usr/bin, /usr/local/bin, Windows Registry, python.org installs
Conda	Runs conda info --envs to find configured environment directories
Pyenv	$PYENV_ROOT/versions or ~/.pyenv/versions
Poetry	Project .venv folders and ~/.cache/pypoetry/virtualenvs
Pipenv	~/.local/share/virtualenvs (Linux/macOS) or %USERPROFILE%\.virtualenvs (Windows)

Discovery runs automatically when the extension activates. The extension uses the Python Environment Tool (PET) Rust binary that scans your system for Python environments. PET finds environment managers by checking your PATH (for example, by looking for conda, pyenv, and poetry executables) and known installation locations, and then searches for environments managed by each of these environment managers.

To manually trigger a refresh:

1. Open the Command Palette (Cmd+Shift+P or Ctrl+Shift+P)
2. Run Python Environments: Refresh All Environment Managers

You can also click the refresh icon in the Environment Managers view header.

Select the refresh icon to rescan for environments.

View discovered environments

Discovered environments appear in two places:

• Environment Managers view: in the Python sidebar, environments are grouped by manager type (for example, venv, Conda, and more)
• Environment selection: when selecting an interpreter for a project, all discovered environments appear in a unified list

The Environment Managers view groups environments by type.

Tip

Don't have an environment yet? See the Python Projects section for information on how to create one with the extension.

Configure search paths

By default, the extension searches your entire workspace for virtual environments using the glob pattern ./**/.venv. This finds any folder named .venv anywhere in your workspace.

To discover environments in custom locations, update the python-envs.workspaceSearchPaths setting:

Note

This setting must be configured at the workspace or folder level, not user level.

{ "python-envs.globalSearchPaths": ["/Users/yourname/envs", "/opt/shared-envs"] }

This setting requires absolute paths and is configured at the user (global) level.

Legacy settings: If you previously used python.venvPath or python.venvFolders, these are automatically merged with the new search paths. Consider migrating to python-envs.globalSearchPaths for future compatibility.

Select an environment

To use a discovered environment:

• Status Bar: select the Python version shown at the bottom of the window
• Command Palette: run Python: Select Interpreter and choose from the list

The selected environment is used for running code, debugging, and language features like IntelliSense.

Tip

By default, the debugger uses your selected environment. To use a different interpreter for debugging, set the python property in your launch.json debug configuration.

Select the Python version in the Status Bar to switch environments. How the extension auto-selects: When you open a workspace without explicitly selecting an environment, the extension chooses one automatically in the following order:

1. Workspace-local virtual environments (.venv, venv)
2. Global/system interpreters

To override this priority order, set python-envs.defaultEnvManager to prefer a specific manager (for example, ms-python.python:conda), or configure Python Projects for per-folder control. The legacy setting is still supported as well.

Troubleshoot environment discovery

Symptom	Cause	Solution
Environment not listed	Location not in search paths	Add the path to workspaceSearchPaths or globalSearchPaths
Environment shows as "(broken)"	Missing pyvenv.cfg or invalid Python executable	Recreate the environment or fix the broken files
Recently created environment missing	Discovery cache is stale	Run Refresh All Environment Managers
Conda environment not found	Conda not detected	Ensure conda is in your PATH or install Conda
Settings not taking effect	Wrong setting scope	Ensure workspaceSearchPaths is set at workspace level, not user level

For advanced troubleshooting, run the Python Environment Tool (PET) directly to see raw discovery output:

1. Open the Command Palette
2. Run Python Environments: Run Python Environment Tool (PET) in Terminal...
3. Choose an option:
   • Find All Environments: runs pet find --verbose to list all discovered environments with detailed output
   • Resolve Environment...: enter a path to a Python executable to debug why a specific environment isn't being detected

PET verbose output shows exactly what environments are discovered and why.

Advanced troubleshooting is useful for the following scenarios:

• You need to verify an environment is being detected
• You want to understand why an environment appears under a specific manager
• You're debugging path resolution issues

Create, delete, and manage environments

Create environments

The extension provides two ways to create environments: Quick Create for speed, and Custom Create for control.

Quick Create

Select the + button in the Environment Managers view. The extension performs the following steps:

• Uses your default manager (venv by default, configurable via python-envs.defaultEnvManager)
• Picks the latest Python version available
• Names the environment .venv (or .venv-1, .venv-2 if one already exists)
• Installs dependencies from requirements.txt or pyproject.toml if found
• Selects the new environment for your workspace

This is the fastest way to get a working environment.

Quick Create builds an environment with sensible defaults.

Custom Create

For more control, run Python: Create Environment from the Command Palette and walk through the prompts:

1. Choose manager: venv or conda
2. Select Python version: pick from discovered interpreters (venv) or available Python versions (conda)
3. Name your environment: enter a custom name or accept the default
4. Install dependencies: choose to install from requirements.txt, pyproject.toml, or environment.yml

Custom Create lets you configure each step.

Using uv for faster creation

If uv is installed, the extension uses it automatically for venv creation and package installation, which is significantly faster than standard tools. Configure this with:

Workspace ├── Python Project: backend/ │ └── Environment: .venv (Python 3.12) │ └── Manager: venv │ ├── Python Project: frontend-utils/ │ └── Environment: .venv (Python 3.10) │ └── Manager: venv │ └── Python Project: ml-pipeline/ └── Environment: ml-env (Python 3.11) └── Manager: conda

What uses project assignments?

• Running and debugging: uses the project's environment
• Terminals: activated with the project's environment
• Test Explorer: each project gets its own test tree with its own interpreter (see Multi-Project Testing)

Note

Pylance and Jupyter currently use a single interpreter per workspace, not per-project environments. See Known Limitations.

Add a project

To treat a folder or file as a separate project:

1. Right-click it in the Explorer
2. Select Add as Python Project

Alternatively, select + in the Python Projects view and choose either of these options:

• Add Existing: select files/folders manually
• Auto Find: discover folders with pyproject.toml or setup.py

Tip

When you add a project, its folder is automatically added to the environment search path. Environments inside project folders (for example, my-project/.venv) are discovered automatically without the need to update workspaceSearchPaths.

Add existing folders or auto-discover projects.

Assign an environment

Once a folder is a project, assign its environment:

1. In the Python Projects view, click the environment shown under your project (or "No environment")
2. Select from discovered environments

The selected environment is used whenever you run or debug files in that project.

Click the environment to change it.

How settings are stored

When you assign an environment to a project, the extension writes to your workspace settings (.vscode/settings.json):

# .env API_KEY=your-secret-key DATABASE_URL=postgres://localhost/mydb

Variables are injected when terminals are created. This is useful for development credentials that shouldn't be committed to source control.

Legacy settings

These settings from the Python extension are still supported but have newer equivalents:

Legacy setting	New equivalent	Notes
python.venvPath	python-envs.globalSearchPaths	Automatically merged. Consider migrating.
python.venvFolders	python-envs.globalSearchPaths	Automatically merged. Consider migrating.
python.terminal.activateEnvironment	python-envs.terminal.autoActivationType	Set to off to disable. New setting takes precedence.
python.defaultInterpreterPath	—	Still supported. Used as fallback in priority chain.
python.condaPath	—	Still supported. Specifies custom conda executable location.

Settings scope reference

Settings behave differently depending on where they're configured:

Setting	User	Workspace	Folder
defaultEnvManager	✅	✅	❌
defaultPackageManager	✅	✅	❌
pythonProjects	❌	✅	✅
workspaceSearchPaths	❌	✅	✅
globalSearchPaths	✅	❌	❌
alwaysUseUv	✅	❌	❌
terminal.autoActivationType	✅	❌	❌

Key insight: workspaceSearchPaths must be set at workspace or folder level (not user level) because it's relative to workspace folders.

Extensibility

The Python Environments extension is designed to be extensible. Any environment or package manager can build an extension that plugs into the Python sidebar, appearing alongside the built-in managers. This means the ecosystem can grow to support new tools without waiting for updates to this extension.

Community members are building extensions for additional environment managers like the Pixi Extension.

Known limitations

Pylance and multi-project workspaces

Pylance does not support multiple Python projects with different interpreters in the same workspace. Even if you configure separate environments for different folders using Python Projects, Pylance uses a single interpreter for the entire workspace—typically the one associated with the workspace root. To use different interpreters for different folders, add them as workspace folders in a multi-root workspace (File > Add Folder to Workspace), since Pylance runs independently per workspace folder.

Jupyter notebooks

Jupyter notebooks do not use the Python Environments API for environment discovery. Instead, they rely on the older Python extension API. This means notebook kernel selection may show a different set of environments than the Environment Managers view.

Next steps

• Python tutorial - Get started with Python in VS Code.
• Debugging - Learn to debug your Python code.
• Testing - Configure and run tests for your Python projects.
• Settings reference - Explore all Python extension settings.

02/04/2026