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:

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.

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:

{
  "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:

1. Open the Command Palette
2. 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.

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

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:

{
  "python-envs.alwaysUseUv": true
}

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

Supported managers

Delete environments

To delete an environment:

1. In the Environment Managers view, find the environment
2. Right-click and select Delete

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

A Python 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 (see Multi-Project Testing)

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

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):

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

Notice that settings store the environment 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 the Python Projects view and select Remove 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, run Python Envs: Create New Project from Template from the Command Palette. Choose between:

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

See the full Python Projects guide for details on template structure.

Learn more

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

Package management

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

Install packages

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

Or run Python 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 from requirements.txt, pyproject.toml, or environment.yml. When prompted, select the file, and the extension installs all listed dependencies.

Uninstall packages

1. Expand an environment in the Environment Managers view to see installed packages
2. Right-click a package and select Uninstall Package

Package managers by environment

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

To override the default, set python-envs.defaultPackageManager.

Faster installation with uv

If uv is installed and python-envs.alwaysUseUv is enabled (the default), package installation in venv environments uses uv pip instead of regular pip, 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 set defaultEnvManager (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 the Interpreter 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 your settings.json.

Python Environments settings

Terminal settings

When you open a terminal in VS Code, the extension automatically activates your selected Python environment so that python, 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 the Environment Managers view, find the environment
2. Right-click and select Open in Terminal

Open a terminal with any environment activated.

For detailed troubleshooting and how activation works under the hood, see Terminal 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 with python.envFile
2. Set python.terminal.useEnvFile to true

# .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:

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 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.