Pylance is a fast, feature-rich language support extension for Python in Visual Studio Code, powered by the Pyright static type checker. It provides advanced type checking, auto-completions, code navigation, and other language features to enhance your Python development experience.
Many codebases contain multiple Python sub-projects — each with different type-checking needs, Python version targets, or strictness levels. Pylance offers the python.analysis.useNearestConfiguration setting to automatically discover pyrightconfig.json and pyproject.toml files throughout your workspace and apply the right settings to the right files — without requiring a multi-root workspace.
This guide explains what python.analysis.useNearestConfiguration does, how it discovers configuration files, and how virtual workspaces work.
The python.analysis.useNearestConfiguration setting controls whether Pylance scans your workspace for pyrightconfig.json and pyproject.toml files in subdirectories and creates virtual workspaces for each one. Each virtual workspace uses its own configuration, so different parts of your codebase can have independent type-checking settings.
This is an experimental feature and is disabled by default.
When python.analysis.useNearestConfiguration is set to true:
- Discovery: Pylance recursively scans your workspace from the root, looking for
pyrightconfig.jsonand qualifyingpyproject.tomlfiles in subdirectories. - Virtual workspace creation: For each discovered config file, Pylance creates an internal virtual workspace rooted at that config file's parent directory.
- Isolation: Each Python file is type-checked using the configuration from its enclosing virtual workspace — the nearest ancestor directory that has a config file.
- Dynamic updates: File watchers detect config files being added, removed, or changed, and recompute virtual workspaces automatically.
pyrightconfig.json: Any valid JSON file with this name in a subdirectory.pyproject.toml: Only included if it contains a[tool.pyright]or[tool.pyrightconfig]section.
These directories are automatically skipped during discovery:
- Any directory starting with
.(covers.git,.vscode,.venv,.env,.tox,.nox,.mypy_cache,.pytest_cache,.eggs, etc.) node_modules,__pycache__venv,env,site-packagesdist,build,*.egg-info
workspace/
├── pyproject.toml # Python 3.11, strict checking
├── src/
│ └── main.py
├── scripts/
│ ├── pyrightconfig.json # Python 3.12, relaxed checking
│ └── helper.py
└── examples/
├── pyrightconfig.json # Python 3.12, medium checking
└── demo.py
With "python.analysis.useNearestConfiguration": true:
src/main.pyuses the rootpyproject.toml(Python 3.11, strict)scripts/helper.pyusesscripts/pyrightconfig.json(Python 3.12, relaxed)examples/demo.pyusesexamples/pyrightconfig.json(Python 3.12, medium)
true: Enables automatic discovery of config files and creation of virtual workspaces.false(default): Pylance only uses config files at workspace roots.
The default value is false.
To enable python.analysis.useNearestConfiguration:
- Open Settings and search for
python.analysis.useNearestConfiguration. - Check the box to enable it.
Alternatively, edit your settings.json file directly:
- Open Command Palette, type Preferences: Open Settings (JSON), and select it.
- Add or update the following line:
"python.analysis.useNearestConfiguration": true
Virtual workspaces are transparent — they do not appear in the VS Code Explorer or change the UI in any way. The setting scope is resource, so it can be configured per workspace folder.
Virtual workspaces are isolated by default. Files in one virtual workspace cannot import from another virtual workspace unless extraPaths is explicitly configured in the config file.
To allow cross-workspace imports, add extraPaths in the relevant pyrightconfig.json:
{
"extraPaths": ["../shared"]
}Use python.analysis.exclude to prevent virtual workspaces from being created for certain subdirectories:
{
"python.analysis.useNearestConfiguration": true,
"python.analysis.exclude": ["**/tests/**", "**/temp/**"]
}Changes to python.analysis.exclude trigger an automatic recomputation of virtual workspaces.
| Feature | Multi-Root Workspaces | useNearestConfiguration |
|---|---|---|
| Manual setup required | Yes — .code-workspace file |
No — automatic discovery |
| UI changes | Yes — multiple roots in Explorer | No — single root |
Works with code . |
No — needs a workspace file | Yes |
| Config in any subdirectory | No — only explicit roots | Yes |
| User awareness | Explicit | Transparent |
- Experimental: This feature is experimental and may change in future releases.
- Extension-side only: The config discovery and virtual workspace creation happen on the VS Code extension side. The language server receives virtual workspaces as standard workspace folders.
- Light mode interaction: When
python.analysis.languageServerModeis set tolight, the defaultpython.analysis.excludepattern is["**"], which excludes all subdirectories — effectively makinguseNearestConfigurationhave no effect. - Only
pyrightconfig.jsonand qualifyingpyproject.toml: Other config formats are not discovered.
A: In most cases, no. useNearestConfiguration automatically discovers config files and creates virtual workspaces. Multi-root workspaces are still useful when your sub-projects are in unrelated directories or when you want explicit control over which folders are included.
A: Pylance only recognizes pyproject.toml files that contain a [tool.pyright] or [tool.pyrightconfig] section. Add one of these sections to your pyproject.toml:
[tool.pyright]
typeCheckingMode = "standard"A: Not by default. Virtual workspaces are isolated. Add extraPaths in the relevant pyrightconfig.json to enable cross-workspace imports.
A: In light mode, python.analysis.exclude defaults to ["**"], which excludes all virtual workspace subdirectories. Switch to default or full language server mode to use useNearestConfiguration.
python.analysis.exclude: Exclude patterns that filter out virtual workspaces.python.analysis.languageServerMode: Controls language server mode;lightmode effectively disablesuseNearestConfiguration.
- How to Set Up CI Type Checking — per-subtree config for CI pipelines
- How to Set Up a Python Monorepo — multi-config monorepo patterns
For more information on Pylance settings and customization, refer to the Pylance Settings and Customization documentation.
This document was generated with the assistance of AI and has been reviewed by humans for accuracy and completeness.