Understanding python.analysis.autoSearchPaths in Pylance

April 8, 2026 · View on GitHub

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.

Managing import paths in Python projects can sometimes be challenging, especially in larger projects with complex directory structures. Pylance offers the python.analysis.autoSearchPaths setting to help streamline this process by automatically adding certain directories to the import search path.

This guide explains what python.analysis.autoSearchPaths does, how it affects your project, and how you can configure it to suit your needs.

What Is `python.analysis.autoSearchPaths`?

The python.analysis.autoSearchPaths setting controls whether Pylance automatically adds a src directory to the import search paths used for module resolution. When enabled, Pylance checks for a src directory at the root of your workspace and, if it meets certain conditions, includes it as an extra search path — without requiring you to configure python.analysis.extraPaths manually.

How Does It Work?

When python.analysis.autoSearchPaths is set to true, Pylance checks for a directory named src at the root of your workspace. If it finds one and the following conditions are met, it adds this directory to the module search paths:

Directory name: Must be src, located at the workspace root.
No __init__.py: The src directory must not contain an __init__.py file at its root. If __init__.py is present, src is treated as a Python package rather than a search path root.

Effect on Imports

With autoSearchPaths enabled and a qualifying src/ directory present, you can write imports relative to src/ without additional configuration.

Example project structure:

my_project/
├── src/
│   ├── module_a.py
│   └── package/
│       └── module_b.py
└── main.py

In main.py, you can import directly:

from module_a import some_function
from package.module_b import helper

Without autoSearchPaths, Pylance would flag these as unresolved imports because it wouldn't know to look inside src/.

The `python.analysis.autoSearchPaths` Setting

Accepted Values

true (default): Enables automatic addition of the src directory to search paths.
false: Disables automatic search paths. You manage all import paths manually through extraPaths or config files.

Default Value

The default value is true.

How to Change the Setting

To adjust python.analysis.autoSearchPaths:

Open Settings and search for python.analysis.autoSearchPaths.
Toggle the setting on or off.

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.autoSearchPaths": false

Interaction with Other Settings

Combined with `extraPaths`

The auto-detected src/ path and any manually specified extraPaths are additive — they are combined, not mutually exclusive. Setting extraPaths does not override the auto-detected src/ directory.

Execution Environments

When execution environments are defined in a pyrightconfig.json file, the auto-detected src/ path applies only to the default execution environment. It does not automatically apply to explicitly defined execution environments. Add src to each environment's extraPaths if needed:

{
    "executionEnvironments": [
        {
            "root": "packages/api",
            "extraPaths": ["../../src"]
        }
    ]
}

Limitations

Only src/: Only a directory named src at the workspace root is auto-detected. Other directory names (e.g., lib, source, app) require manual configuration via extraPaths.
No nested directories: Nested src/ directories (e.g., packages/core/src/) are not auto-detected.
__init__.py changes behavior: If src/ contains __init__.py, it is treated as a package rather than a search path root. Imports would then require from src.module_a import ....

Frequently Asked Questions

Q: Why isn't my `src` directory being automatically included?

A: Ensure that:

python.analysis.autoSearchPaths is set to true
The src directory is at the workspace root
There is no __init__.py file in the src directory

Q: Can I auto-detect directories other than `src`?

A: No. autoSearchPaths only detects src/. For other directories, use python.analysis.extraPaths.

Q: Does this setting affect runtime behavior?

A: No. autoSearchPaths only affects Pylance's analysis within VS Code. It does not modify sys.path at runtime. To ensure your code runs correctly, you may need to adjust PYTHONPATH or configure your build tool.

python.analysis.extraPaths: Manually add directories to the import search path. Additive with autoSearchPaths.
python.analysis.stubPath: Directory containing custom type stubs.