Pylance Documentation

The Type Server Protocol (TSP) is a JSON-RPC based protocol used to request Python analysis data from a type server. It provides access to protocol versions, snapshots, Python search paths, import resolution, and various type queries (computed, declared, and expected types).

Key characteristics:

• Data Shapes: Uses Language Server Protocol (LSP) conventions for Position, Range, and URI string representations.
• Method Prefix: All TSP methods are prefixed with typeServer/.
• Communication: Typically operates over stdio on a main JSON-RPC connection, with optional support for extra read-only connections via ipc.

The python.analysis.indexing setting controls whether Pylance scans your codebase and installed third-party libraries to build a symbol index. This index powers advanced IntelliSense features by allowing Pylance to understand symbols that are not currently open in your editor.

Key Benefits

• Improved Auto-Imports: Suggests imports for symbols that are neither imported nor currently open in VS Code.
• Enhanced Code Navigation: Improves the performance and scope of the go to symbol feature across the entire workspace.
• Improved Code Generation: Automatically adds import statements for used symbols during code generation.

Performance Trade-offs

Indexing consumes CPU and memory. For very large projects or resource-constrained environments (like remote development), disabling indexing can improve editor responsiveness.

Type narrowing is a technique used to resolve type errors when working with union types (e.g., str | None or int | str). When a variable has multiple possible types, Pylance cannot guarantee which one is active. You can use conditional checks to 'narrow' the type, telling Pylance exactly which variant you are working with in a specific code branch.

Narrowing works in both if and else branches. For example, if you check isinstance(val, int), Pylance treats val as an int inside the if block and as the remaining types in the else block.

def describe(val: int | str):
    if isinstance(val, int):
        print(val + 1)      # OK — val is int here
    else:
        print(val.upper())  # OK — val is str here

Pylance resolves settings from multiple sources. If a setting is not behaving as expected, a higher-priority source is likely overriding it. The precedence order (from highest to lowest) is:

1. pyrightconfig.json or pyproject.toml [tool.pyright] section (Per-project)
2. .vscode/settings.json (Workspace folder)
3. .code-workspace file settings (Per-workspace)
4. User settings (settings.json) (Global)
5. languageServerMode defaults (Implicit defaults)

Note on Config Files: If both pyrightconfig.json and pyproject.toml (with [tool.pyright]) exist in a workspace, pyrightconfig.json takes precedence and pyproject.toml is ignored.

It is important to distinguish between these two settings:

1. python.analysis.indexing: A master toggle. It determines whether Pylance performs indexing of user files and third-party libraries at all. If false, indexing features are disabled.
2. python.analysis.persistAllIndices: A performance optimization. It determines whether the indices created by the indexing process are saved to disk for reuse.

If python.analysis.indexing is false, python.analysis.persistAllIndices does nothing.

Pylance uses indices to provide fast code completions, auto-import suggestions, and symbol searches.

By default, Pylance uses prebuilt indices to avoid the overhead of indexing the standard library every time a workspace is opened. However, these prebuilt indices are optimized for the latest Python version and may not account for:

• Older Python versions (where certain modules or decorators do not exist).
• Platform-specific modules (differences between Windows, Linux, etc.).

Enabling python.analysis.regenerateStdLibIndices creates workspace-specific indices that accurately reflect your configured Python environment.