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 usingvenv,uv,conda,pyenv,poetry, orpipenv.

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 thePython 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, expandEnvironment 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:

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 forconda,pyenv, andpoetry 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 orCtrl+Shift+P)
2. RunPython Environments: Refresh All Environment Managers

You can also click the refresh icon in theEnvironment 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.

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 thepython-envs.workspaceSearchPaths setting:

{  "python-envs.workspaceSearchPaths": ["./**/.venv","./envs/**","./my-custom-env"]}

Tips:

• Use** for recursive searches (for example,./**/env finds any folder namedenv at any depth)
• Relative paths resolve from your workspace folder root

To quickly open search path settings:

1. Open the Command Palette
2. RunPython 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), usepython-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 usedpython.venvPath orpython.venvFolders, these are automatically merged with the new search paths. Consider migrating topython-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: runPython: Select Interpreter and choose from the list

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

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, setpython-envs.defaultEnvManager to prefer a specific manager (for example,ms-python.python:conda), or configurePython Projects for per-folder control. The legacy setting is still supported as well.

Troubleshoot environment discovery

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

1. Open the Command Palette
2. RunPython Environments: Run Python Environment Tool (PET) in Terminal...
3. Choose an option:
   • Find All Environments: runspet 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, andCustom 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 viapython-envs.defaultEnvManager)
• Picks the latest Python version available
• Names the environment.venv (or.venv-1,.venv-2 if one already exists)
• Installs dependencies fromrequirements.txt orpyproject.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, runPython: 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 fromrequirements.txt,pyproject.toml, orenvironment.yml

Custom Create lets you configure each step.

Using uv for faster creation

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

{  "python-envs.alwaysUseUv":true}

WhenalwaysUseUv is enabled (the default), uv manages all virtual environments. Set it tofalse to only use uv for environments explicitly created by uv.

Supported managers

Delete environments

To delete an environment:

1. In theEnvironment Managers view, find the environment
2. Right-click and selectDelete

Deleting an environment removes the environment folder from disk. Any projects that use this environment will require that you select a new one.

Python projects

APython project is any file or folder you want to associate with a specific environment. By default, your entire workspace uses one environment. Projects let you assign different environments to different folders. This is essential for mono-repos, microservices, or testing across Python versions.

Why use projects?

If you only have one environment for your whole workspace, you don't need to set up projects explicitly. Select an interpreter and you're done.

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 (seeMulti-Project Testing)

Add a project

To treat a folder or file as a separate project:

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

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

• Add Existing: select files/folders manually
• Auto Find: discover folders withpyproject.toml orsetup.py

Add existing folders or auto-discover projects.

Assign an environment

Once a folder is a project, assign its environment:

1. In thePython 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):

{  "python-envs.pythonProjects": [    {      "path":"backend",      "envManager":"ms-python.python:venv"    },    {      "path":"ml-service",      "envManager":"ms-python.python:conda"    }  ]}

Notice that settings store theenvironment manager, not hardcoded interpreter paths. The extension remembers which specific environment you selected separately, and resolves it at runtime. This design makes settings shareable:

• No machine-specific paths: teammates don't need/Users/yourname/.venv
• Portable across systems: works on macOS, Windows, and Linux
• Survives environment recreation: if you delete and recreate.venv, it still works

Sharing with teammates:

1. Commit.vscode/settings.json to your repo
2. Teammates clone and open the workspace
3. They create their own environments (Quick Create works great here)
4. The extension automatically uses each project's configured manager

Remove a project

Right-click a project in thePython Projects view and selectRemove Python Project. This removes the mapping. It does not delete any files.

Create a project from a template

To scaffold a new project with the right structure, runPython Envs: Create New Project from Template from the Command Palette. Choose between:

• Package: creates a folder withpyproject.toml, package directory, and tests
• Script: creates a single.py file with inline dependency metadata (PEP 723)

See the fullPython Projects guide for details on template structure.

Learn more

For detailed guidance on templates, multi-root workspaces, common scenarios, and troubleshooting, see the fullPython Projects guide.

Package management

Install and uninstall Python packages directly from VS Code without opening a terminal.

Install packages

1. In theEnvironment Managers view, find an environment
2. Right-click and selectManage Packages
3. Search for packages and select the ones you want to install

Or runPython Envs: Manage Packages from the Command Palette.

Search and install packages directly from VS Code.

Installing from a requirements file: You can also install packages fromrequirements.txt,pyproject.toml, orenvironment.yml. When prompted, select the file, and the extension installs all listed dependencies.

Uninstall packages

1. Expand an environment in theEnvironment Managers view to see installed packages
2. Right-click a package and selectUninstall Package

Package managers by environment

The extension automatically uses the appropriate package manager based on your environment:

To override the default, setpython-envs.defaultPackageManager.

Faster installation with uv

Ifuv is installed andpython-envs.alwaysUseUv is enabled (the default), package installation in venv environments usesuv pip instead of regularpip, which is significantly faster for large dependency trees.

Settings and configuration

This section covers all extension settings, how interpreter selection works, and legacy settings migration.

Interpreter selection priority

When you open a workspace, the extension determines which environment to use by checking these sources in order:

Key principle: User-configured settings always win over defaults. If you haven't explicitly setdefaultEnvManager (it has the built-in default), the extension skips it and checks the next priority.

Caching: The extension caches resolved environments for performance, but your explicit settings always take precedence over cached values. You never need to worry about stale cache overriding your choices.

For more details on interpreter selection behavior, see theInterpreter Selection Quick Reference.

When settings are written

The extension only writes to settings when you make an explicit change:

This ensures that opening a workspace does not add auto-generated entries to yoursettings.json.

Python Environments settings

Terminal settings

When you open a terminal in VS Code, the extension automatically activates your selected Python environment so thatpython,pip, and related commands use the correct interpreter.

Terminal activation types:

Opening a terminal for a specific environment:

You can open a new terminal with any environment activated:

1. In theEnvironment Managers view, find the environment
2. Right-click and selectOpen in Terminal

Open a terminal with any environment activated.

For detailed troubleshooting and how activation works under the hood, seeTerminal Auto-Activation Explained.

.env file support

To inject environment variables from a.env file into your terminals:

1. Create a.env file in your workspace root or specify a custom path withpython.envFile
2. Setpython.terminal.useEnvFile totrue

# .envAPI_KEY=your-secret-keyDATABASE_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:

Settings scope reference

Settings behave differently depending on where they're configured:

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 thePixi 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 usingPython 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 amulti-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 theEnvironment 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.