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

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.

Thank you for the detailed issue! I will investigate!

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.

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!

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:

Project-based discovery: Searches within registered Python project directories
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:

Click + in the Python Projects panel
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:

Collect project directories: The extension gathers all registered Python project paths
Collect search paths: Legacy settings, globalSearchPaths, and workspaceSearchPaths are combined
Configure the finder: The native Python environment finder receives these paths
Discover environments: The finder scans each location for Python environments
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:

Right-click the folder in Explorer
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"
    ]
}

Eleanor Boyd (@eleanorjboyd)

Thanks, Eleanor Boyd (@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.

I’ve been testing it for a while and it works perfectly for my use case. It turns out this was the right approach from the beginning. Sorry for not noticing that feature earlier.

Since the extension usually behaves automatically, it’s not obvious that some folders need to be registered manually as projects. That manual step is correct, just not very visible. Maybe the extension could suggest marking folders as projects when it detects more than one venv in the workspace or when the active environment is not located at the root, as long as no projects have already been declared.

Note

This scenario does not only apply to monorepos. It also applies to umbrella‑style repositories and multi‑repository workspaces, where each component is its own repository but the workspace includes them all, as shown in my updated example tree.

The Source Control component handles this very well and can locate .git folders, which allows it to recognize repositories up to a configurable depth through the git.repositoryScanMaxDepth setting. The way they perform that scan might offer a useful hint for improving environment autodetection.

P.d.:
One thing I noticed is that after adding a directory as a project, the context menu still offers the option to add it again when using the right‑click menu. It would be more helpful if, once a folder is already registered as a project, the command switched to offering the option to remove it instead.

Thanks for taking the time to look into this.

From my side this can be closed, unless you prefer to handle the closure yourselves or want me to run any additional tests.

Hi! So glad to hear this is working for you! After your comments I went ahead and changed the default setting so now all .venv in your workspace should be found as this continued to be a confusing aspect that was causing very valid confusion like you had.

To your second point- about the context menu still showing add project I am working on that- turns out to be a bit harder than expected.

I will close this issue then but if you run into any other issues or have any followup feedback feel free to reach out. Happy coding!

Navigation Menu

Repository navigation

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

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.

The old plugin shows them properly:

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

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.

The old plugin still shows them properly with a exception:

The current plugin now correctly shows both `venvs`.

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.

How Interpreter Discovery Works

Overview

Why the Extension Doesn't Search Your Entire Workspace

Project Roots and Environment Discovery

How Projects Drive Discovery

Example: Mono-repo with Multiple Services

Adding Projects

Search Path Settings

`python-envs.globalSearchPaths`

`python-envs.workspaceSearchPaths`

Legacy Settings Migration

The Discovery Process

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

"My environment is in a subfolder of my workspace"

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

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

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

Description

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.

The old plugin shows them properly:

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

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.

The old plugin still shows them properly with a exception:

The current plugin now correctly shows both venvs.

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.

Activity

eleanorjboyd commented on Dec 8, 2025

Carbaz commented on Feb 2, 2026

eleanorjboyd commented on Feb 4, 2026

eleanorjboyd commented on Feb 4, 2026

How Interpreter Discovery Works

Overview

Why the Extension Doesn't Search Your Entire Workspace

Project Roots and Environment Discovery

How Projects Drive Discovery

Example: Mono-repo with Multiple Services

Adding Projects

Search Path Settings

python-envs.globalSearchPaths

python-envs.workspaceSearchPaths

Legacy Settings Migration

The Discovery Process

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

"My environment is in a subfolder of my workspace"

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

Carbaz commented on Feb 5, 2026

Carbaz commented on Feb 5, 2026

eleanorjboyd commented on Feb 11, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions

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

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.

The current plugin now correctly shows both `venvs`.

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.

`python-envs.globalSearchPaths`

`python-envs.workspaceSearchPaths`