Pylance is a fast, feature-rich language server extension for Python in Visual Studio Code, powered by the Pyright static type checker. It offers advanced IntelliSense features, including type checking, auto-completions, and code navigation, enhancing your Python development experience.
One of Pylance's configuration settings is python.analysis.packageIndexDepths, which allows you to control how Pylance indexes third-party packages for features such as auto-imports and code completion.
This guide explains what python.analysis.packageIndexDepths does, how to use it effectively, and considerations when adjusting this setting.
By default, Pylance indexes only the top-level modules of installed third-party packages (depth = 1). This indexing behavior is a performance optimization, ensuring that Pylance operates efficiently, especially in large projects.
The python.analysis.packageIndexDepths setting allows you to override this default behavior by specifying the depth to which Pylance should index specific packages. Increasing the index depth enables Pylance to recognize deeper modules and symbols within a package, improving IntelliSense features like auto-import suggestions for those modules.
Pylance reads requirements.txt and pyproject.toml in your workspace root to identify your project's direct dependencies. Packages found there are automatically indexed at depth 2, even when the global default is 1. This covers the most common usage pattern — importing from a top-level subpackage like from flask import Flask or from requests.exceptions import HTTPError — without requiring any manual configuration.
The automatic boost applies only when the package is not already listed in packageIndexDepths. If you set an explicit depth for a package, your setting takes priority.
Distribution-name-to-module-name mapping is handled automatically (e.g., scikit-learn → sklearn).
PEP 420 namespace packages (e.g., azure, google) lack an __init__.py at the top level. Pylance automatically looks up to 4 levels deep to find the first real subpackage containing an __init__.py. This adjustment reaches the nearest real subpackage; deeper modules may still require a per-package depth override.
In some cases, you may notice that Pylance does not provide auto-import suggestions for certain submodules or symbols within a third-party package. This behavior occurs because those submodules are not included in the default index.
By adjusting the indexing depth for a package, you can include additional submodules and symbols, enhancing Pylance's ability to provide relevant suggestions.
The python.analysis.packageIndexDepths setting accepts a list of configurations, each specifying a package, the depth to which it should be indexed, and whether to include all symbols.
Each configuration in the list should be an object with the following properties:
"name": The name of the package (string)."depth": The depth to which Pylance should index the package (integer)."includeAllSymbols"(optional): Whether to include all symbols in the indexing (boolean). If set tofalse, ordinary untyped.pymodules contribute only symbols in__all__; stub files andpy.typedpackages contribute their public symbols. Default isfalseif not specified.
Note: Your list replaces the configured per-package overrides. Unlisted packages are still indexed at their default depth.
{
"name": "package_name",
"depth": depth_to_scan,
"includeAllSymbols": true_or_false
}To adjust the packageIndexDepths setting in Visual Studio Code:
-
Open the Settings JSON:
- Open the Command Palette and select Preferences: Open Settings (JSON).
-
Add or Modify the Setting:
- Include the
python.analysis.packageIndexDepthssetting in yoursettings.jsonfile:"python.analysis.packageIndexDepths": [ { "name": "package_name", "depth": depth_to_scan, "includeAllSymbols": true_or_false } ],
- Include the
-
Save and Reload:
- Save the
settings.jsonfile. - Reload Visual Studio Code for the changes to take effect.
- Save the
Note: Adjusting the indexing depth may impact performance. It's recommended to specify only the packages you need and to set the minimum depth required.
- Depth: The number of modules in the module path that Pylance should index.
-
Depth 1: Only the package's top-level modules are indexed (e.g.,
django). -
Depth 2: Includes modules one level deeper (e.g.,
django.core). -
Depth 3: Includes modules two levels deeper (e.g.,
django.core.api).Note that the depth does not directly correspond to the directory structure. For example,
django.corecould be located indjango/core.pyordjango/core/__init__.py.
-
-
includeAllSymbols: false(default):- For ordinary untyped
.pymodules, Pylance includes only symbols specified in__all__. Stub files andpy.typedpackages contribute their public symbols. - This helps reduce the number of irrelevant or private symbols in the index.
- For ordinary untyped
-
includeAllSymbols: true:- Pylance includes all top-level symbols declared in the files, regardless of the
__all__attribute. - Use this option if necessary symbols are not included due to missing
__all__declarations.
- Pylance includes all top-level symbols declared in the files, regardless of the
Adjusting the python.analysis.packageIndexDepths setting causes Pylance to allocate more resources for indexing third-party libraries. Indexing deeper levels or including all symbols increases the amount of data Pylance processes, which can lead to:
- Increased Memory Usage: More symbols and modules are loaded into memory.
- Longer Indexing Times: Initial indexing when starting VS Code may take more time.
- Potential Impact on Responsiveness: Large projects or extensive indexing may affect editor performance.
To mitigate performance impacts:
- Only specify packages where deeper indexing is necessary.
- Set the smallest
depthvalue that includes the required modules. - Avoid setting
includeAllSymbolstotrueunless needed.
Suppose you're working with the django package and need auto-import suggestions for modules within django.core.
"python.analysis.packageIndexDepths": [
{
"name": "django",
"depth": 3
}
],- Explanation: This setting tells Pylance to index
djangoto a depth of 3, includingdjango(depth 1),django.core(depth 2), and submodules withindjango.core(depth 3).
If the package does not correctly export symbols via __all__, and you need all symbols indexed, you can set includeAllSymbols to true.
"python.analysis.packageIndexDepths": [
{
"name": "rest_framework",
"depth": 3,
"includeAllSymbols": true
}
],- Explanation: This setting tells Pylance to index the
rest_frameworkpackage to a depth of 3 and include all symbols. This can be useful if you're not getting auto-import suggestions for certain classes or functions within the package.
You can specify multiple packages in the packageIndexDepths list.
"python.analysis.packageIndexDepths": [
{
"name": "matplotlib",
"depth": 2
},
{
"name": "numpy",
"depth": 2
},
{
"name": "pandas",
"depth": 2
}
],- Explanation: This configuration adjusts the indexing depth for
matplotlib,numpy, andpandasto 2, enabling better auto-imports and auto-import suggestions for submodules within these packages.
If you want to change the indexing depth for all packages, you can set the name to an empty string "".
"python.analysis.packageIndexDepths": [
{
"name": "",
"depth": 3
}
],-
Pylance treats the entry with "name": "" as a catch-all default that applies only to packages without an exact match in the list.
-
For each package being indexed:
- If there’s a config object whose "name" exactly matches that package, Pylance uses that depth (and includeAllSymbols if specified).
- Otherwise, if there’s an entry with "name": "", Pylance falls back to its depth (and includeAllSymbols).
-
Entries are not merged or order-dependent—exact matches always override the empty-string default.
-
Explanation: This setting adjusts the default indexing depth for all packages to 3. Use this cautiously, as it may significantly impact performance.
In default and light modes, most packages are indexed at depth 1 (top-level only). A few popular libraries are indexed deeper:
Note: In light mode, indexing is disabled by default. These depth values only apply when python.analysis.indexing is explicitly set to true.
In addition, packages listed as direct dependencies in requirements.txt or pyproject.toml are automatically indexed at depth 2, even if they are not in the list above (see Automatic Depth Boost for Direct Dependencies).
In full mode, most packages default to depth 4 with includeAllSymbols: true:
[{ "name": "", "depth": 4, "includeAllSymbols": true }]This provides broad auto-import coverage at the cost of higher resource usage.
A: The depth depends on how deep the modules or symbols you need are within the package's directory structure. Start with a depth of 2 or 3 and increase if necessary. Be mindful of performance impacts when setting higher depths.
A: Your list replaces the configured per-package overrides. Unlisted packages are still indexed at their default depth.
Note: The automatic depth boost for direct dependencies (from requirements.txt/pyproject.toml) still applies for packages that are not listed in your custom packageIndexDepths. If you explicitly list a package, your depth takes priority over the automatic boost.
A: Currently, the python.analysis.packageIndexDepths setting applies globally or per-workspace in VS Code settings. You can adjust the setting in your workspace's settings.json to enable it for a specific project.
- How to Tune Pylance Performance — indexing depth and performance trade-offs
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."
Last content update aligned with Pylance 2026.4.1.
[ { "name": "sklearn", "depth": 2 }, { "name": "matplotlib", "depth": 2 }, { "name": "scipy", "depth": 2 }, { "name": "django", "depth": 4 }, { "name": "flask", "depth": 2 }, { "name": "fastapi", "depth": 2 }, { "name": "cuda", "depth": 3, "includeAllSymbols": true }, ]