Python environments in VS Code
AI agents: See llms.txt for documentation discovery and navigation. Documentation articles are also available as Markdown by appending .md to the article URL. Join VS Code at Microsoft Ignite or catch the sessions online. A year of VS Code, wrapped. Explore the highlights. Python environments in VS Code View as Markdown Ask in VS Code Ask in VS Code Insiders 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: Open a Python file Check the Status Bar to see which environment is active 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: Open the Command Palette ( Cmd+Shift+P or Ctrl+Shift+P ) 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.workspaceSearchPaths" : [ "./**/.venv" , "./envs/**" , "./my-custom-env" ] } Tips : Use ** for recursive searches (for example, ./**/env finds any folder named env at any depth) Relative paths resolve from your workspace folder root To quickly open search path settings: Open the Command Palette Run Python Environments: Configure Search Settings Add custom glob patterns to search additional locations.
Global search paths : For environments outside your workspace (like a shared ~/envs folder), use python-envs.globalSearchPaths : { "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: Workspace-local virtual environments ( .venv , venv ) 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: Open the Command Palette Run Python Environments: Run Python Environment Tool (PET) in Terminal...
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: Choose manager : venv or conda Select Python version : pick from discovered interpreters (venv) or available Python versions (conda) Name your environment : enter a custom name or accept
The rest of this page is on the live site.