Multiple projects and interpreters in the workspace

Since version 0.14.0, PyDev for VSCode has the capability to detect multiple projects and interpreters within a workspace.

This means that each folder in the workspace can have its own interpreter or source folder settings, which are automatically detected through a series of heuristics.

By default, this feature is enabled, however, if want more control and can work with a single project for the entire workspace, you can disable this feature by setting python.pydev.autoDetectProjects to false. In this case, the whole workspace will use the settings specified by python.pydev.pythonInterpreter and python.pydev.pythonPath (otherwise, these settings will be used just as a fallback for python files that are not part of any project).

Heuristic 1: Sema4ai VSCode Extension

If the Sema4ai VSCode Extension is installed, it will be queried to resolve the interpreter or PYTHONPATH for a file. This process should automatically create an interpreter based on the package.yaml or robot.yaml file if available. If the extension is not installed or fails to resolve the interpreter, alternative heuristics are applied.

Heuristic 2: finding the folders to be used in the PYTHONPATH

To determine the folders to be used in the PYTHONPATH, the following steps are taken:

• If a pyproject.toml file is found, its contents are used to create a scoped project, with source folders derived from the information within the file. This includes support for poetry projects. If tool.poetry.packages is found, and projects contain entries with a path, those entries define the PYTHONPATH (source folders). Additionally, if tool.poetry.dependencies or tool.poetry.dev.dependencies are present, those dependent projects are also scanned for source folder dependencies.
• If tool.mypy.mypy_path is found, the folders defined there are used as the PYTHONPATH.
• If none of the above heuristics match, default folders such as src, sources, source, test, and tests are used as the PYTHONPATH.
• If these folders are not found, the directory containing the pyproject.toml file is used as the PYTHONPATH.

Heuristic 3: finding the interpreter

For finding the interpreter, the following heuristics are used:

• If a virtual environment folder (identified by having a pyvenv.cfg file inside it, typically named .venv) is found, it will be used as the interpreter for the project.
• If a conda environment with the same name as the project.name or tool.poetry.name defined in the pyproject.toml file is found, that conda environment will be used as the interpreter (may require setting python.pydev.conda.location to the path where the conda executable is located if it's not in the PATH).

It is important to note that the interpreter is neither updated nor created by the extension. PyDev uses the interpreters it finds, so if you are using tools like poetry, uv, or conda to manage your Python environment, you should continue using them.

Examples

Example: a project using a pyproject.toml with a dependency on another project (from poetry)

By having a structure like this:

my_project1/
├── src/
│   └── my_package/
│       └── my_module1.py
├── tests/
│   └── test_my_module1.py
├── pyproject.toml

my_project2/
└── my_package2/
   └── my_module2.py
├── tests/
│   └── test_my_module2.py
├── pyproject.toml

pyproject.toml (from my_project1)

[project]
name = "my_project1"
version = "0.1.0"

[tool.poetry]
packages = [{ include = "my_package", from = "src" }] # tool.poetry.packages is analyzed by `PyDev` to find the folders with python sources (must be in `from=`)

[tool.poetry.dependencies]  # tool.poetry.dependencies and tool.poetry.group.dev.dependencies are analyzed by `PyDev` to find project dependencies.
python = "^3.10"
my_project2 = { path = "../my_project2/" }

[tool.mypy]
mypy_path = "src:tests" # The `tool.mypy.mypy_path` is analyzed by `PyDev` to find the folders with python sources.

pyproject.toml (from my_project2)

[project]
name = "my_project2"
version = "0.1.0"

[tool.poetry]
packages = [{ include = "my_package2", from = "." }] # tool.poetry.packages is analyzed by `PyDev` to find the folders with python sources (must be in `from=`)

[tool.poetry.dependencies]
python = "^3.10"

[tool.mypy]
mypy_path = "src:tests" # The `tool.mypy.mypy_path` is analyzed by `PyDev` to find the folders with python sources.

In this case, when bootstrapping the interpreter with poetry, PyDev will detect the dependency from my_project1 to my_project2 and will build the PYTHONPATH with the folders that should be considered source folders from both projects accordingly.

Regarding the interpreter, there are actually 2 choices here: either the interpreter should be in a .venv, right next to the pyproject.toml file, or it should be in a conda environment with the same name as the project.name or tool.poetry.name defined in the pyproject.toml file (note that the interpreter needs to be manually created externally, PyDev does not update or create interpreters, it just uses the ones it finds).

Example: a project using a Sema4ai VSCode Extension project

By having a structure like this:

my_project/
├── src/
│   └── my_module.py
├── tests/
│   └── test_my_module.py
├── package.yaml

package.yaml

name: my_project
version: 0.1.0
spec-version: v2

dependencies:
  conda-forge:
    - python=3.11.11
    - uv=0.4.19

  pypi:
    - sema4ai-actions=1.3.0

dev-dependencies:
  conda-forge:
    - pytest=8.3.3
  pypi:
    - ruff=0.7.0
    - mypy=1.13.0

pythonpath:
  - src
  - tests

When the my_module.py file is opened, PyDev will automatically detect the my_project project and use the interpreter defined in the package.yaml file to have an interpreter with the dependencies defined in the package.yaml file along with the given PYTHONPATH (note that it always bootstraps the interpreter with the dev-dependencies).

Note: PyDev should automatically detect and update its internal caches as needed, but if changes are made and PyDev does not automatically detect them, you can use the command PyDev: Clear caches to clear the internal caches and force a re-detection.

If the issue persists, please report to https://brainwy.com/tracker/PyDev to improve the heuristics.

Note: When searching for symbols, only those from the project associated with the last active Python file are considered if multiple projects are detected in the workspace.

Note: A new setting, decorations.pySourceFolderContents.enabled, can be set to true to make it easier to see which files are part of the detected projects in the EXPLORER view.

This setting makes PyDev add a PY decoration to folders and files identified as part of source folders in the EXPLORER view, making it easier to quickly identify which files are part of the detected projects in PyDev.