Issues working on workspaces with multiple components subfolders, each with it's own venv.

[Carbaz]

Hard to describe it completely, seems the core of the issue comes that at some point this has been designed for a single project single venv workspace.

I'll try to illustrate the situation with a sequence of screenshots and status/actions.

The screenshots will show four sections:

• The two above are from the old "Python Environment Manager (deprecated)" plugin and provided as a reference of expected behavior.
• The two bellow belong to this "vscode-python-environments"

Note

It's important to mention that this behavior happens the same if the old plugin is removed, so no interference in-between is the root cause of the issue.

Note

Also important to mention that on most "choose environment" actions that uses top drop down the missing venvs are not shown AND there are not a "browse" option, the only way to get the "browse" is using the bottom bar - left side - environment section.

This makes cumbersome to work with notebooks, for example, that each one belongs to a different environment, as many unexpected and not obvious steps has to be taken to properly make them connect to the right venv.

Issue detailed description follows from this point:

---

We have opened a workspace folder which contains several subfolders each of one belong to a different repository.

I.e: Think of it as each one is a component of a multiservice project.

The old plugin shows them properly:

• 2 venv environments: One of them is made using uv the other is bare python -m venv .venv.

• 3 PyEnv python versions available (The default one shown as "Global" here.)

• 3 pipenv environments: One does not belongs to this project actually but as its centralized is shown, I understand this behavior.

• The "Workspace environments" properly shows the two venv ones that are in fact .venv folders inside this workspace projects/subfolders.
  (Showing here also which ones of pipenv belongs would be nice, it can be decided by the venvs meta info that is present and can be seen unfolding them, but that's just a side suggestion)

The current plugin is missing one of the venvs, it shown only the one is currently chosen.

Everything else is shown properly, only the venv section does not populates right.

---

Now we have used the bottom bar - left side - environment section to choose the missing environment and thus it makes the new plugin aware of it.

To make this possible we need to choose the "browse" option as the missing one it's not showing on the drop down.

The old plugin still shows them properly with a exception:

• The "Workspace environments" now shows the one we just choose duplicated and misses the other one. (We don't care about this now)

The current plugin now correctly shows both venvs.

• But on the "Python Projects" section the previous one is gone now.

---

Now we refresh the widgets.

The old plugin now correctly shows both venvs again.

The current plugin is now missing the other venv, it again shows only the one is currently chosen.

[eleanorjboyd]

Thank you for the detailed issue! I will investigate!

[Carbaz]

I have an update on this. I recently created a new .venv inside a subfolder of another subfolder, and now both extensions fail to retain all detected environments. As a result, I need to rely on the “Browse…” option (as mentioned earlier) to manually point VS Code to one environment or another in order to select them as kernels for my IPython/Jupyter notebooks.

Below is an example tree structure of the workspace:

workspace-root-folder/
├── .vscode/
│   └── ...
├── component1/                  # pipenv
│   ├── .git/
│   ├── Pipfile
│   └── ...
├── component2/                  # uv
│   ├── .git/
│   ├── .venv/
│   ├── pyproject.toml
│   └── ...
├── component3/                  # uv
│   ├── .git/
│   ├── .venv/
│   ├── pyproject.toml
│   └── ...
├── component4/                  # pipenv
│   ├── .git/
│   ├── Pipfile
│   └── ...
├── component5/                  # venv (native)
│   ├── .git/
│   ├── .venv/
│   ├── requirements.txt
│   └── ...
└── subservice/
    ├── component1/              # uv
    │   ├── .git/
    │   ├── .venv/
    │   ├── pyproject.toml
    │   └── ...
    ├── component2/              # uv
    │   ├── .git/
    │   ├── .venv/
    │   ├── pyproject.toml
    │   └── ...
    └── component3/              # uv
        ├── .git/
        ├── .venv/
        ├── pyproject.toml
        └── ...

As shown, the workspace contains several subfolders for components or groups of components. They do not all use the same environment manager, and they are not all maintained by the same team.

In summary, this is not an extremely complex workspace, but it is also not a flat one. It is a realistic multi‑repository, multi‑environment setup. The venv‑based environments (including those using .venv/ inside uv‑managed components) are not reliably detected or retained by VS Code.

On a positive note, the extension does correctly distinguish between uv‑managed environments and native venv environments, and it labels them accordingly. So at least the identification of the environment type seems to be working as expected, even though not all venv‑based environments are reliably detected or retained.

[eleanorjboyd]

Reviewing this further I have an idea of what the problem is and would love if you can give it a try and let me know.

The design of the python-env extension does NOT search for any venvs in your workspace lower than what is at the root directory. This is for performance reasons, we don't want to do a huge grep search through your repository. This means that we only look in certain places but we have ways for you to dictate those places to search. What I think you need to do- is add the folder which is the parent of the env you are looking for as a project. This project definition then allows it to get found. If you don't want to - and the venv is not for a "project" then you can also use these settings for search paths.

but my recommendation is add workspace-root-folder/component1 as a project and then workspace-root-folder/component2/.venv will be found. To add a python project- just right click on the folder in the explorer view and you should see an option "add as python project"

Search for not venv happen a different way so let me know if any of those aren't working. Adding it as a project is still the best move but some environment managers as we have them defined will just search the common locations where the tool stores environments.

Hope this helps and let me know how it goes!

[eleanorjboyd]

Here is a first draft of some documentation Im writing which I think should answer your question. If it does- I would really appreciate any thoughts you have on how we could introduce features into the extension that may make this discovery process easier and less confusing.

How Interpreter Discovery Works

This guide explains how the Python Environments extension discovers Python interpreters and environments in your workspace. Understanding this process helps you configure the extension correctly and troubleshoot common issues like missing environments.

Overview

The extension uses a two-pronged approach to find Python environments:

1. Project-based discovery: Searches within registered Python project directories
2. Custom search paths: Searches additional locations you configure via settings

This targeted approach is faster than scanning your entire filesystem and ensures environments are associated with the correct projects.

Why the Extension Doesn't Search Your Entire Workspace

A common question is: "Why doesn't the extension just search everywhere?"
This is due to performance. It is very costly to have to search an entire, gigantic repository for any environments. Instead we want the user to tell us where to search so we are performant.

Project Roots and Environment Discovery

When you add a folder as a Python project, the extension searches that folder and its subdirectories for Python environments.

How Projects Drive Discovery

The native Python finder receives a list of workspaceDirectories—these are the paths of all registered Python projects. For each project, the finder looks for:

• Virtual environments (.venv, venv, .virtualenv, etc.)
• Conda environments
• Poetry environments (via pyproject.toml and Poetry configuration)
• Pipenv environments (via Pipfile)

Example: Mono-repo with Multiple Services

workspace/
├── backend/              
│   └── .venv/            ← Found if backend/ is a project
├── frontend/             
│   └── .venv/            ← Found if frontend/ is a project
├── shared/
│   └── .venv/            ← NOT found unless shared/ is a project
└── .venv/                ← Found (workspace root is always a project)

Key insight: If backend/ and frontend/ are not added as projects, their .venv folders won't be discovered or properly associated with those directories.

Adding Projects

To add subfolders as projects:

option 1: Right-click a folder in Explorer and select Add as Python Project
option2:

1. Click + in the Python Projects panel
2. Select Add Existing and choose the folder

See Managing Python Projects for detailed instructions.

Search Path Settings

For environments stored outside your workspace, or in locations not registered as projects, use search path settings.

python-envs.globalSearchPaths

Paths searched regardless of which workspace is open. Use this for environments you want available across all your projects.

Property	Value
Scope	User (machine-level)
Type	Array of strings
Default	[]

Example:

{
    "python-envs.globalSearchPaths": [
        "~/envs",
        "/opt/python/environments",
        "~/.virtualenvs"
    ]
}

python-envs.workspaceSearchPaths

Paths searched for the current workspace. Supports both absolute paths and paths relative to the workspace root.

Property	Value
Scope	Workspace or Workspace Folder
Type	Array of strings
Default	[]

Example:

{
    "python-envs.workspaceSearchPaths": [
        "environments",
        "../shared-envs",
        "/team/shared/python-envs"
    ]
}

Important: workspaceSearchPaths can only be set at the workspace or workspace folder level, not in user settings. The extension logs an error if you set this at the user level.

Glob patterns are NOT YET supported- coming soon!

Pattern	Matches
*	Any single directory or file name segment
**	Any number of directory levels
services/*/.venv	.venv inside any immediate subfolder of services/
**/environments	Any folder named environments at any depth

Legacy Settings Migration

If you previously used these settings from the Python extension, they continue to work:

• python.venvPath: Single path to a folder containing virtual environments
• python.venvFolders: Array of folder names relative to your home directory

The extension reads both the legacy settings and the new globalSearchPaths/workspaceSearchPaths settings, combining them for discovery.

The Discovery Process

When the extension activates or refreshes, here's what happens:

1. Collect project directories: The extension gathers all registered Python project paths
2. Collect search paths: Legacy settings, globalSearchPaths, and workspaceSearchPaths are combined
3. Configure the finder: The native Python environment finder receives these paths
4. Discover environments: The finder scans each location for Python environments
5. Associate with projects: Each discovered environment is associated with its containing project

FAQ: Why Can't the Extension Find My Environment?

"My environment is in a subfolder of my workspace"

Cause: The subfolder is not registered as a Python project.

Solution: Add the subfolder as a project:

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

"My environments are in a central location outside the workspace"

Cause: The location is not in your search paths.

Solution: Add it to globalSearchPaths:

{
    "python-envs.globalSearchPaths": [
        "/path/to/your/environments"
    ]
}

[Carbaz]

Thanks, @eleanorjboyd, I wasn’t aware of the Add as Python Project feature. I’ll review it in detail.

Here is the corrected link you shared: Managing Python Projects

Regarding other environment managers such as pipenv or poetry, I haven’t seen issues in similar setups.
Their centralized environment locations make discovery predictable, so what you mentioned aligns with my experience.

I’ll test the project based discovery flow across my workspace structure and share the results once I have them.