Understanding python.analysis.useDefaultExcludes in Pylance

July 29, 2026 · View on GitHub

Pylance is a fast and feature-rich language server extension for Python in Visual Studio Code, powered by the Pyright static type checker.

The python.analysis.useDefaultExcludes setting controls whether Pylance applies its built-in default exclusions in addition to the paths you list in python.analysis.exclude.

What Is `python.analysis.useDefaultExcludes`?

To keep analysis fast, Pylance excludes a set of directories that rarely need to be analyzed. When this setting is enabled (the default), those built-in exclusions are applied in addition to any paths you specify in python.analysis.exclude.

The built-in default exclusions are:

**/node_modules
**/__pycache__
**/__editable__.*
Hidden directories (dotfiles), i.e. any directory whose name begins with a . (for example .git, .venv, .tox)
Auto-detected virtual environment directories (e.g., those containing bin/activate, Scripts/activate, or pyvenv.cfg)

These defaults take precedence over python.analysis.include, so a directory that Pylance auto-detects as a virtual environment stays excluded even if you name it explicitly in include.

Type: boolean Default: true Scope: resource (can be set per workspace folder)

Behavior

When enabled (`true`, the default)

The built-in default exclusions listed above are applied on top of your python.analysis.exclude entries. Your custom excludes are additive — they add to the defaults rather than replacing them — so you never need to re-list the defaults to keep them excluded.

When disabled (`false`)

All of the built-in default exclusions are turned off, including virtual-environment auto-detection. Only the paths you list in python.analysis.exclude are excluded.

Note: Disabling the built-in excludes can slow analysis significantly if your workspace contains large dependency or virtual-environment directories, because Pylance will then analyze them unless you exclude them yourself.

How to Change `python.analysis.useDefaultExcludes`

Using the Settings UI

Open the Command Palette (Ctrl+Shift+P / Cmd+Shift+P) and run Preferences: Open Settings (UI).
Search for python.analysis.useDefaultExcludes.
Check or uncheck the box.

Using `settings.json`

{
    "python.analysis.useDefaultExcludes": false
}

When to Use It

Keep enabled (the default) for almost all projects. The built-in excludes keep analysis fast and rarely need to change, and your own python.analysis.exclude entries are added on top of them.
Disable when a default exclusion is skipping a directory you need analyzed — most commonly a directory that was incorrectly auto-detected as a virtual environment. Because the defaults take precedence over include, turning this setting off is the way to force analysis of such a directory; adding it to include will not.

When you disable the defaults, you'll typically want to re-add the exclusions you still care about (such as **/node_modules and your real virtual environment) to python.analysis.exclude yourself:

{
    "python.analysis.useDefaultExcludes": false,
    "python.analysis.exclude": ["**/node_modules", "**/__pycache__", "venv/**"]
}

python.analysis.exclude: Paths to exclude from analysis; combined with the built-in defaults this setting controls.
python.analysis.include: Paths to include in analysis. The built-in default exclusions take precedence over include.
python.analysis.ignore: Suppresses diagnostics for specific paths without excluding them.