← 返回首页
Python environments in VS Code
Visual Studio Code
Download

Use the Agents window to build in an agent-first way.

Documentation

Topics Overview Overview Linux macOS Windows VS Code for the Web Raspberry Pi Network Additional Components Uninstall VS Code Tutorial Copilot Quickstart User Interface Personalize VS Code Install Extensions Tips and Tricks Intro Videos Overview Setup Quickstart Overview Language Models Context Tools Agents Customization Trust & Safety Overview Agents Tutorial Agents Window Planning Memory Tools Subagents Local Agents Copilot CLI Cloud Agents Third-Party Agents Overview Chat Sessions Add Context Inline Chat Review Edits Checkpoints Artifacts Panel Debug Chat Interactions Prompt Examples Overview Instructions Prompt Files Custom Agents Agent Skills Language Models MCP Hooks Plugins Context Engineering Customize AI Test-Driven Development Edit Notebooks with AI Test with AI Test Web Apps with Browser Tools Debug with AI MCP Dev Guide OpenTelemetry Monitoring Inline Suggestions Smart Actions Best Practices Security Troubleshooting FAQ Cheat Sheet Settings Reference MCP Configuration Workspace Context Display Language Layout Keyboard Shortcuts Settings Settings Sync Extension Marketplace Extension Runtime Security Themes Profiles Overview Voice Interactions Command Line Interface Telemetry Basic Editing IntelliSense Code Navigation Refactoring Snippets Overview Multi-Root Workspaces Workspace Trust Tasks Debugging Debug Configuration Testing Port Forwarding Integrated Browser Overview Quickstart Staging & Committing Branches & Worktrees Repositories & Remotes Merge Conflicts Collaborate on GitHub Troubleshooting FAQ Getting Started Tutorial Terminal Basics Terminal Profiles Shell Integration Appearance Advanced Overview Enterprise Policies AI Settings Extensions Telemetry Updates Overview JavaScript JSON HTML Emmet CSS, SCSS and Less TypeScript Markdown PowerShell C++ Java PHP Python Julia R Ruby Rust Go T-SQL C# .NET Swift Working with JavaScript Node.js Tutorial Node.js Debugging Deploy Node.js Apps Browser Debugging Angular Tutorial React Tutorial Vue Tutorial Debugging Recipes Performance Profiling Extensions Tutorial Transpiling Editing Refactoring Debugging Quick Start Tutorial Run Python Code Editing Linting Formatting Debugging Environments Testing Python Interactive Django Tutorial FastAPI Tutorial Flask Tutorial Create Containers Deploy Python Apps Python in the Web Settings Reference Getting Started Navigate and Edit Refactoring Formatting and Linting Project Management Build Tools Run and Debug Testing Spring Boot Modernizing Java Apps Application Servers Deploy Java Apps GUI Applications Extensions FAQ Intro Videos GCC on Linux GCC on Windows GCC on Windows Subsystem for Linux Clang on macOS Microsoft C++ on Windows Build with CMake CMake Tools on Linux CMake Quick Start C++ Dev Tools for Copilot Editing and Navigating Debugging Configure Debugging Refactoring Settings Reference Configure IntelliSense Configure IntelliSense for Cross-Compiling FAQ Intro Videos Get Started Navigate and Edit IntelliCode Refactoring Formatting and Linting Project Management Build Tools Package Management Run and Debug Testing FAQ Overview Node.js Python ASP.NET Core Debug Docker Compose Registries Deploy to Azure Choose a Dev Environment Customize Develop with Kubernetes Tips and Tricks Overview Jupyter Notebooks Data Science Tutorial Python Interactive Data Wrangler Quick Start Data Wrangler PyTorch Support Azure Machine Learning Manage Jupyter Kernels Jupyter Notebooks on the Web Data Science in Microsoft Fabric Foundry Toolkit Overview Foundry Toolkit Copilot Tools Create Agents Models Playground Agent Builder Agent Inspector Evaluation Tool Catalog Fine-Tuning (Automated Setup) Fine-Tuning (Project Template) Model Conversion Tracing Profiling (Windows ML) FAQ File Structure Manual Model Conversion Manual Model Conversion on GPU Setup Environment Without Foundry Toolkit Template Project Migrating from Visualizer to Agent Inspector Overview Getting Started Resources View Deployment VS Code for the Web - Azure Containers Azure Kubernetes Service Kubernetes MongoDB Remote Debugging for Node.js Overview SSH Dev Containers Windows Subsystem for Linux GitHub Codespaces VS Code Server Tunnels SSH Tutorial WSL Tutorial Tips and Tricks FAQ Overview Tutorial Attach to Container Create Dev Container Advanced Containers devcontainer.json Dev Container CLI Tips and Tricks FAQ Default Keyboard Shortcuts Default Settings Substitution Variables Tasks Schema
Copy as Markdown

On this page there are 9 sections

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

02/04/2026