Pylance

Fast, feature-rich language support for Python

This repository is for providing feedback and documentation on the Pylance language server extension in Visual Studio Code. You can use the repository to report issues or submit feature requests. The Pylance codebase is not open-source but you can contribute to Pyright to make improvements to the core typing engine that powers the Pylance experience.

Pylance is the default language support for Python in Visual Studio Code and is shipped as part of that extension as an optional dependency.

The Pylance name is a small ode to Monty Python's Lancelot who was the first knight to answer the bridgekeeper's questions in the Holy Grail.

Quick Start

1. Install the Python extension from the marketplace. Pylance will be installed as an optional extension.
2. Open a Python (.py) file and the Pylance extension will activate.

Note: If you've previously set a language server and want to try Pylance, make sure you've set "python.languageServer": "Default" or "Pylance" in your settings.json file using the text editor, or using the Settings Editor UI.

Features

Pylance provides some awesome features for Python 3, including:

• Docstrings
• Signature help, with type information
• Parameter suggestions
• Code completion
• Auto-imports (as well as add and remove import code actions)
• As-you-type reporting of code errors and warnings (diagnostics)
• Code outline
• Code navigation
• Type checking mode
• Native multi-root workspace support
• Jupyter Notebooks compatibility
• Semantic highlighting
• Generate Dependency File command for workspace roots, Explorer folders, and Python scripts (Pylance: Generate Dependency File)
• Toggle Block Comment command for Python (Pylance: Toggle Block Comment)
• Install Matching Type Stubs command that finds and installs type stub packages for your installed dependencies (Pylance: Install Matching Type Stubs)
• Copilot Chat skills for fact-grounded Python help, type inference, inline type annotations, finding reviewed third-party stubs, stub authoring, Pylance docs, refactoring, profiling, improving Pylance type-evaluation performance, and adding or dropping Python version support

See the changelog for the latest release.

Settings and Customization

Pylance provides users with the ability to customize their Python language support via a host of settings which can either be placed in the settings.json file in your workspace, or edited through the Settings Editor UI.

• python.analysis.languageServerMode

  • Offers predefined configurations to help users optimize Pylance's performance based on their development needs. It controls how many IntelliSense features Pylance provides, allowing you to choose between full language service functionality or a lightweight experience optimized for performance.

  • Default value: default

  • Available values:

    • light
    • default (default)
    • full

  • Description:

    • default: Provides a balanced experience with many useful features enabled by default. It ensures that the language server delivers sufficient functionality for most users without overloading the system. Advanced features can be enabled as needed, allowing for further customization at the cost of performance.
    • light: Designed for users seeking a lightweight, memory-efficient setup. This mode disables various features to make Pylance function more like a streamlined text editor. Ideal for those who do not require the full breadth of IntelliSense capabilities and prefer Pylance to be as resource-friendly as possible.
    • full: Designed for users seeking the most extensive feature set. This mode enables most of Pylance's features, offering the richest IntelliSense experience. Ideal for those who want access to the full range of available functionality.

  • Individual settings can be configured to override the defaults set by languageServerMode.

  • Default settings based on mode are:

    Mode	light	default	full
    python.analysis.exclude	["**"]	[]	[]
    python.analysis.useLibraryCodeForTypes	false	true	true
    python.analysis.enablePytestSupport	false	true	true
    python.analysis.indexing	false	true	true
    python.analysis.userFileIndexFollowSymlinkedFolders	true	true	true
    python.analysis.autoImportCompletions	false	false	true
    python.analysis.showOnlyDirectDependenciesInAutoImport	false	false	true
    python.analysis.packageIndexDepths	See	settings	below
    python.analysis.regenerateStdLibIndices	false	false	true
    python.analysis.userFileIndexingLimit	2000	2000	-1
    python.analysis.includeAliasesFromUserFiles	false	false	true
    python.analysis.functionReturnTypes	false	false	true
    python.analysis.pytestParameters	false	false	true
    python.analysis.supportRestructuredText	false	true	true
    python.analysis.supportDocstringTemplate	false	false	true
    python.analysis.nodeExecutable	""	""	"auto"

• python.analysis.typeCheckingMode

  • Used to specify the level of type checking analysis performed.
  • Default: off.

    Note that the value of this setting can be overridden by having a pyrightconfig.json or a pyproject.toml. For more information see this link.

  • Available values:
    • off: No type checking analysis is conducted; unresolved imports/variables diagnostics are produced.
    • basic: All rules from off + basic type checking rules.
    • standard: All rules from basic + standard type checking rules.
    • strict: All rules from standard + strict type checking rules.

    You can refer to pyright documentation to reference the default type checking rules for each of the type checking modes.

  • Performance Consideration:
    • Setting python.analysis.typeCheckingMode to off can improve performance by disabling type checking analysis, which can be resource-intensive, especially in large codebases.

• python.analysis.diagnosticMode

  • Used to allow a user to specify what files they want the language server to analyze to get problems flagged in their code.
  • Available values:
    • workspace
    • openFilesOnly (default)
  • Performance Consideration:
    • Setting python.analysis.diagnosticMode to openFilesOnly limits analysis to open files, improving performance by reducing the amount of code Pylance needs to process in large workspaces.

• python.analysis.include

  • Paths of directories or files that should be included. If no paths are specified, Pylance defaults to the directory that contains workspace root. Paths may contain wildcard characters ** (a directory or multiple levels of directories), * (a sequence of zero or more characters), or ? (a single character).
  • Default value: empty array

• python.analysis.exclude

  • Paths of directories or files that should not be included. These override the include directories, allowing specific subdirectories to be excluded. Note that files in the exclude paths may still be included in the analysis if they are referenced (imported) by source files that are not excluded. Paths may contain wildcard characters ** (a directory or multiple levels of directories), * (a sequence of zero or more characters), or ? (a single character). If no exclude paths are specified, Pylance automatically excludes the following: **/node_modules, **/__pycache__, .git and any virtual environment directories.
  • Default value: empty array (or ["**"] in light mode)
  • Performance Consideration:
    • Excluding unnecessary files or directories can significantly improve performance by reducing the scope of analysis. For example, setting python.analysis.exclude to ["**"] will exclude all files except those currently open, minimizing resource consumption.

• python.analysis.useDefaultExcludes

  • When enabled (the default), Pylance adds a set of built-in default excludes in addition to any paths listed in python.analysis.exclude: **/node_modules, **/__pycache__, **/__editable__.*, hidden directories (dotfiles), and auto-detected virtual environment directories. These defaults take precedence over python.analysis.include, so a directory auto-detected as a virtual environment stays excluded even if it is explicitly included.
  • Set this to false to disable all of these built-in excludes — including virtual environment auto-detection — so that only the paths listed in python.analysis.exclude are excluded. Disabling this can slow analysis significantly if your workspace contains large dependency or environment directories.
  • Default value: true

• python.analysis.useNearestConfiguration (Experimental)

  • When enabled, Pylance will search for and use pyrightconfig.json or pyproject.toml files in subdirectories, creating virtual workspaces for each configuration. This allows different type-checking settings for different parts of your codebase.
  • Default value: false
  • Available values:
    • true
    • false (default)
  • Note:
    • This feature is experimental and may have performance implications in large workspaces.
    • Virtual workspaces respect python.analysis.exclude patterns.
    • Only pyproject.toml files containing [tool.pyright] sections are discovered.
    • Important: Files in different virtual workspaces are isolated from each other. If you need files in one workspace to import from another workspace, you must configure extraPaths in your pyrightconfig.json or pyproject.toml to reference the other workspace directories. For example:

      {
        "extraPaths": ["../other-workspace"]
      }
      

• python.analysis.usePerProjectEnvironments

  • When enabled, Pylance will use a separate Python environment (interpreter) for each project declared via python-envs.pythonProjects. This ensures that each sub-project in a single-root workspace is type checked against its own interpreter.
  • Default value: false
  • Available values:
    • true
    • false (default)
  • Note:
    • Each sub-project may also need its own extraPaths configuration so that cross-project imports resolve correctly. To have Pylance configure these automatically, enable python.analysis.addExtraPathsForPythonProjects.
    • This setting replaces the deprecated python.analysis.addFoldersForPythonProjects, which continues to work for backwards compatibility.

• python.analysis.addExtraPathsForPythonProjects

  • Experimental. When enabled, Pylance automatically adds the source root of every project declared via python-envs.pythonProjects to extraPaths, so cross-project imports between sub-projects of a monorepo resolve without configuring extraPaths manually.
  • The source root is detected per project: a src directory if present, otherwise the project's parent directory when the project folder is itself a package (contains __init__.py), otherwise the project folder.
  • Editable/local cross-package references declared in each project's pyproject.toml are followed transitively, so a registered project that imports sibling packages as editable installs picks up their source roots too. This is what makes monorepos such as dagster resolve without registering every package individually. The following dependency-manager formats are recognized:
    • uv — [tool.uv.sources] entries with a local path.
    • Poetry — path/develop entries in [tool.poetry.dependencies], [tool.poetry.dev-dependencies], and [tool.poetry.group.<group>.dependencies].
    • PDM / Rye / PEP 508 / PEP 735 — file: direct references (including ${PROJECT_ROOT} and {root:uri} root tokens, and -e/--editable entries) in [project].dependencies, [project.optional-dependencies], [dependency-groups], [tool.pdm.dev-dependencies], and [tool.rye.dev-dependencies].
  • Named, VCS, and remote-URL requirements are ignored, and references that point at built archives (wheels/sdists) are skipped.
  • Any extraPaths you configure are preserved; the detected source roots are appended.
  • Default value: false
  • Available values:
    • true
    • false (default)

• python.analysis.ignore

  • Paths of directories or files whose diagnostic output (errors and warnings) should be suppressed even if they are an included file or within the transitive closure of an included file. Paths may contain wildcard characters ** (a directory or multiple levels of directories), * (a sequence of zero or more characters), or ? (a single character).
  • Default value: empty array

• python.analysis.excludeLibraryDiagnostics

  • When enabled, suppresses all diagnostics from library files (site-packages, typeshed, bundled stubs, etc.) while preserving diagnostics for user-authored workspace and orphan files. Useful when opening library source files for reference without cluttering the Problems panel.
  • Default value: false

• python.analysis.stubPath

  • Used to allow a user to specify a path to a directory that contains custom type stubs. Each package's type stub file(s) are expected to be in its own subdirectory.
  • Default value: ./typings

• python.analysis.autoSearchPaths

  • Used to automatically add search paths based on some predefined names (like src).
  • Available values:
    • true (default)
    • false

• python.analysis.extraPaths

  • Used to specify extra search paths for import resolution. This replaces the old python.autoComplete.extraPaths setting.
  • Default value: empty array

• python.analysis.ignoredPackages

  • List of installed packages to exclude from type analysis. Specify the importable package name (e.g. "PIL" rather than "Pillow"). Files in ignored packages return empty content during analysis while the directory structure is preserved for import resolution.
  • Default value: empty array

• python.analysis.disableBundledStubs

  • Disable Pylance's bundled type stubs so the installed package is analyzed directly. Set to true to disable all bundled stubs, or provide a list of package names to disable only those.
  • Default value: false

• python.analysis.includeExtraPathSymbolsInSymbolSearch

  • Include symbols from python.analysis.extraPaths in Workspace Symbol search.
  • Default value: false
  • Performance Consideration:
    • Enabling this setting may slow down Workspace Symbol search.
  • Note:
    • For non-py.typed libraries, only symbols exported via a package __init__.py __all__ are included.

• python.analysis.includeVenvInWorkspaceSymbols

  • Include symbols from installed third-party packages (venv site-packages) in Workspace Symbol search.
  • Default value: false
  • Performance Consideration:
    • Enabling this setting may significantly slow down Workspace Symbol search for large virtual environments.
    • Only takes effect when python.analysis.indexing is enabled.
  • Note:
    • Only symbols from packages installed in site-packages (or dist-packages on Debian/Ubuntu) are included. Standard library symbols are excluded.
    • For non-py.typed libraries, only symbols exported via a package __init__.py __all__ are included.
    • When the search query is empty, venv/library symbols are not returned (the result set would be too large). User-code symbols are always returned regardless of the query.
    • The depth of sub-packages searched depends on python.analysis.packageIndexDepths. By default, only top-level modules (depth 1) are indexed. To include symbols from deeper sub-modules (e.g., django.views), increase the depth for the corresponding package in packageIndexDepths.

• python.analysis.diagnosticSeverityOverrides

  • Used to allow a user to override the severity levels for individual diagnostics should they desire.
  • Accepted severity values:
    • error (red squiggle)
    • warning (yellow squiggle)
    • information (blue squiggle)
    • none (disables the rule)
  • Available rules to use as keys can be found here
  • Example:

  {
      "python.analysis.diagnosticSeverityOverrides": {
          "reportUnboundVariable": "information",
          "reportImplicitStringConcatenation": "warning"
      }
  }
  

• python.analysis.typeEvaluation

  • Used to allow a user to override the behavior of type evaluator should they desire.
  • Available rules to use as subkeys can be found here
  • Example:

  {
      "python.analysis.typeEvaluation.enableReachabilityAnalysis": true,
      "python.analysis.typeEvaluation.strictDictionaryInference": false
  }
  

• python.analysis.disableTaggedHints

  • Disable hint diagnostics with special hints for grayed-out or strike-through text.
  • Accepted values:
    • true
    • false (default)

• python.analysis.useLibraryCodeForTypes

  • Used to parse the source code for a package when a typestub is not found.
  • Default value: true (or false in light mode)
  • Accepted values:
    • true (default)
    • false
  • Performance Consideration:
    • Setting python.analysis.useLibraryCodeForTypes to false can improve performance by preventing Pylance from parsing the source code of third-party libraries when type stubs are unavailable, thereby reducing resource usage.

• python.analysis.indexing

  • Used to specify whether Pylance should index installed third party libraries and user files to improve features such as auto-import, add import, workspace symbols, etc.
  • Without indexing, auto-import, add import, and workspace symbols will have less information.
  • Default value: true (or false in light mode)
  • Available values:
    • true (default)
    • false
  • Performance Consideration:
    • Disabling indexing by setting python.analysis.indexing to false can improve performance by reducing resource consumption, especially in large projects, at the cost of making features like auto-imports and workspace symbol search find fewer symbols.

• python.analysis.userFileIndexFollowSymlinkedFolders

  • Used to specify whether user-file indexing should follow files that are located under symlinked folders in the workspace.
  • With indexing enabled and this setting set to true, workspace symbol search (Ctrl+T) includes symbols from linked package folders, even when their targets are outside the workspace.
  • Default value: true
  • Available values:
    • true (default)
    • false
  • Performance Consideration:
    • Disabling this setting can improve indexing performance in workspaces that contain symlinks into very large directory trees.
  • Note:
    • This setting affects only user-file indexing. It does not change how installed third-party libraries are indexed, including packages in site-packages or dist-packages.
    • Symlinked individual files are still indexed; this setting only controls files discovered under symlinked folders.
    • Source discovery skips directory links to filesystem roots or ancestors of included folders unless the target is covered by an explicit include.
    • Only takes effect when python.analysis.indexing is enabled.
    • This can change which import suggestions are offered. For example, if the same symbol could be imported as from lib import Symbol or from symlinked import Symbol, turning this setting off can prevent from symlinked import Symbol from being offered when symlinked is reached through a symlinked folder.

• python.analysis.userFileIndexingLimit

  • Maximum number of user files to index in the workspace. Indexing files is a performance-intensive task. Please use this setting to limit the number of files you want us to index. If you enter -1, we will index all files.
  • Default value: 2000 (or -1 for full mode)
  • Performance Consideration:
    • Increasing this number will cause Pylance to allocate more resources for user file indexing.

• python.analysis.packageIndexDepths

  • Used to override how many levels under installed packages to index on a per package basis. By default, only top-level modules are indexed (depth = 1). To index submodules, increase depth by 1 for each level of submodule you want to index.
  • If depth is set to 0, the entry is treated as an exclude prefix and is removed from the index. Exclusions are module-boundary aware: pydantic.v1 excludes pydantic.v1 and pydantic.v1.*, but does not exclude pydantic.v10.
  • Default value:

    [
        { "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 }
    ]
    

    or in full mode

    [
        { "name": "", "depth": 4,  "includeAllSymbols": true }
    ]
    

  • Accepted values:

    {
        "name": "package name (str)",
        "depth": "depth to scan (int)",
        "includeAllSymbols": "whether to include all symbols (bool)"
    }
    

    If includeAllSymbols is set to false, only symbols in each package's __all__ are included. When it's set to true, Pylance will index every module/top level symbol declarations in the file.
  • Example:

    [
        { "name": "sklearn", "depth": 2, "includeAllSymbols": true },
        { "name": "matplotlib", "depth": 3, "includeAllSymbols": false }
    ]
    

  • Exclusion example:

    [
        { "name": "ctypes", "depth": 0 },
        { "name": "pydantic.v1", "depth": 0 }
    ]
    

  • Performance Consideration:
    • Adjusting this setting will cause Pylance to allocate more resources for indexing third-party libraries.

• python.analysis.persistAllIndices

  • Used to specify whether indices for all third-party libraries should be persisted to disk.
  • Default value: true
  • Performance Consideration:
    • Enabling this setting can improve startup performance by reducing the need to re-index third-party libraries.

• python.analysis.regenerateStdLibIndices

  • Instead of relying on the shared stdlib.json indices for all Python versions, generate unique indices tailored to each workspace's specific Python version and platform. This regeneration process will affect performance, unlike using the prebuilt stdlib indices.
  • Default value: false (or true in full mode)
  • Accepted values:
    • true
    • false (default)
  • Performance Consideration:
    • Enabling this can impact performance by creating its own indices for standard libraries.

• python.analysis.includeAliasesFromUserFiles

  • Include alias symbols from user files. This will make alias symbols appear in features such as add import and auto import.
  • Default value: false (or true in full mode)
  • Accepted values:
    • true
    • false (default)
  • Performance Consideration:
    • Enabling this can impact performance by increasing the number of completion items and indexing multiple files as changes occur.

• python.analysis.autoImportCompletions

  • Used to control the offering of auto-imports in completions. This will impact number of items shown in the completion and performance.
  • Default value: false (or true in full mode)
  • Accepted values:
    • true
    • false (default)
  • Performance Consideration:
    • Enabling python.analysis.autoImportCompletions can impact performance by increasing the number of completion items and resource usage. Disabling it can improve performance by reducing the computational overhead during code completion.

• python.analysis.showOnlyDirectDependenciesInAutoImport

  • Show only direct dependencies declared in requirements.txt or pyproject.toml in auto import suggestions, if they exist. This only affects auto import for completions. The add import code action will continue to show all possible imports.
  • Default value: false (or true in full mode)
  • Accepted values:
    • true
    • false (default)

• python.analysis.importFormat

  • Defines the default format for import module.
  • Accepted values:
    • absolute (default)
    • relative

• python.analysis.completeFunctionParens

  • Add parentheses to function completions.
  • Accepted values:
    • true
    • false (default)
  • Performance Consideration:
    • Disabling python.analysis.completeFunctionParens can slightly improve performance by reducing the overhead during code completion, though the impact is minimal.

• python.analysis.renameInDocstrings

  • When renaming a symbol, also update whole-word occurrences of its name inside docstrings. Matching is name-based and not scope-aware, so unrelated whole-word occurrences of the same name (including ordinary English prose) may also be rewritten. The occurrences are added to the rename edit and can be reviewed with the Refactor Preview.
  • Accepted values:
    • true
    • false (default)

• python.analysis.inlayHints.variableTypes

  • Enable/disable inlay hints for variable types.
  • Accepted values:
    • true
    • false (default)
  • Performance Consideration:
    • Disabling inlay hints for variable types by setting python.analysis.inlayHints.variableTypes to false can improve performance by reducing the processing required to generate these hints, which can be beneficial in large codebases.

• python.analysis.inlayHints.functionReturnTypes

  • Enable/disable inlay hints for function return types.
  • Default value: false (or true in full mode)
  • Accepted values:
    • true
    • false (default)
  • Performance Consideration:
    • Disabling inlay hints for function return types can improve performance by reducing the overhead of generating these hints.

• python.analysis.inlayHints.callArgumentNames

  • Enable/disable inlay hints for call argument names.
  • Accepted values:
    • off (default)
    • partial
    • all
  • Performance Consideration:
    • Setting python.analysis.inlayHints.callArgumentNames to off can improve performance by reducing the processing needed to display argument names during function calls.

• python.analysis.inlayHints.pytestParameters

  • Enable/disable inlay hints for pytest function parameters.
  • Default value: false (or true in full mode)
  • Accepted values:
    • true
    • false (default)
  • Example:

    def test_foo(my_fixture):
        assert(my_fixture)
    

    becomes

    def test_foo(my_fixture: str):
        assert(my_fixture)
    

  • Performance Consideration:
    • Disabling inlay hints for pytest parameters can improve performance by reducing the overhead associated with generating these hints.

• python.analysis.fixAll

  • The set of commands to run when doing a fix all.
  • Accepted values:
    • source.unusedImports
    • source.convertImportFormat
    • source.convertImportStar
    • source.addTypeAnnotation

• python.analysis.enablePytestSupport

  • Enable pytest goto def and inlay hint support for fixtures.
  • Default value: true (or false in light mode)
  • Accepted values:
    • true (default)
    • false
  • Performance Consideration:
    • Disabling pytest support by setting python.analysis.enablePytestSupport to false can improve performance by reducing the overhead associated with providing IntelliSense features for pytest fixtures.

• python.analysis.enableDjangoSupport [Experimental]

  • Enables Django support in Pylance. When enabled, Pylance detects Django projects and provides IntelliSense for ORM-generated model attributes (e.g. objects, reverse relations, and field descriptors) by merging virtual content into your source files via a file overlay.
  • Requires a native binary that is only available on Windows (x64/ARM64), macOS (Apple Silicon), and Linux (x64/ARM64). On unsupported platforms this setting is silently ignored.
  • Default value: false
  • Accepted values:
    • true
    • false (default)

• python.analysis.enableTreeSitterColorization [Experimental]

  • Uses an incremental Tree-sitter Rust sidecar for Python syntax colors, combined with Pylance's type-aware semantic tokens.
  • Set this to true and enable editor.semanticHighlighting.enabled to use it. Requires a trusted workspace and a supported native binary.
  • Supports open Python files up to 2 MiB. Notebooks, virtual content, and larger files keep existing highlighting.
  • Themes control the colors; unstyled tokens retain TextMate colors. TextMate remains the fallback.
  • Default value: false
  • Accepted values:
    • true
    • false (default)

• python.analysis.enablePydanticSupport [Experimental]

  • Enables field IntelliSense and constructor type checking for statically recoverable Pydantic create_model calls.
  • Default value: false
  • Accepted values:
    • true
    • false (default)

• python.analysis.autoFormatStrings

  • When typing a { in a string, automatically puts an f on the front of the string.
  • Accepted values:
    • true
    • false (default)
  • Performance Consideration:
    • Disabling python.analysis.autoFormatStrings can slightly improve performance by reducing the processing required during string formatting, though the impact is minimal.

• python.analysis.nodeExecutable

  • Path to a node executable to use to run Pylance. If this value is empty, Pylance uses VS Code's node executable. If set to auto, it will automatically download a version from nodejs
  • Set this value when you are having out of memory issues. Using a custom node executable allows Pylance to allocate more memory.
  • Accepted values:
    • any executable path or auto

• python.analysis.nodeArguments

  • Extra arguments to pass to node when using python.analysis.nodeExecutable. Defaults to --max-old-space-size=8192
  • Accepted values:
    • Any argument that node accepts

• python.analysis.autoIndent

  • Automatically adjust indentation based on language semantics when typing Python code.
  • Accepted values:
    • true (default)
    • false

• python.analysis.autoSplitStrings

  • Automatically add quote and line continuation characters when splitting strings.
  • Accepted values:
    • true (default)
    • false

• python.analysis.formatOnTypeStyle (Experimental)

  • Selects the code style Pylance uses when it auto-indents your code as you type (format-on-type). This applies when editor.formatOnType is enabled for Python.
  • Default value: pep8
  • Accepted values:
    • pep8 (default): Use PEP 8-style continuation indentation when auto-indenting wrapped brackets (an extra level of indentation on a function definition's parameter list).
    • black: Use Black-compatible continuation indentation when auto-indenting wrapped brackets (a single level of indentation on a function definition's parameter list).
  • Note: This setting only affects the indentation Pylance applies while typing; it does not run a full formatter over your document.

• python.analysis.autoTranslateDocstrings

  • Automatically translate Python docstrings in hover tooltips to the user's preferred language using GitHub Copilot.
  • When enabled, docstrings will be translated to the language specified by the GitHub Copilot locale setting (github.copilot.chat.localeOverride). If set to auto, Pylance will use the VS Code display language. Translations preserve Python code blocks, keywords, and markdown formatting.
  • Default value: false
  • Accepted values:
    • true
    • false (default)
  • Note: Requires GitHub Copilot to be installed and active.
  • Performance Consideration:
    • Enabling python.analysis.autoTranslateDocstrings may make hover tooltips display significantly slower due to the time required to call GitHub Copilot for AI-powered translation before showing the hover content.

• python.analysis.supportRestructuredText

  • Enable/disable support for reStructuredText in docstrings.
  • Default value: false (or true in full mode)
  • Accepted values:
    • true (default)
    • false
  • Performance Consideration:
    • Disabling support for reStructuredText in docstrings by setting python.analysis.supportRestructuredText to false can improve performance by reducing the overhead of parsing complex docstrings.

• python.analysis.aiCodeActions

  • Enable/disable AI-assisted code actions. Requires the Copilot Chat extension to be enabled.
  • This setting accepts objects where the keys are the available AI-assisted code actions, and the values are true or false to enable or disable each action.
  • Available code actions to use as keys:
    • convertFormatString
    • convertLambdaToNamedFunction
    • generateDocstring
    • generateSymbol
    • implementAbstractClasses
  • Example:

  {
      "python.analysis.aiCodeActions": {
          "implementAbstractClasses": true,
          "generateSymbol": true,
          "generateDocstring": true
      }
  }
  

• python.analysis.supportDocstringTemplate

  • Enable/disable support for reStructuredText docstring generation.
  • Default value: false (or true in full mode)
  • Accepted values:
    • true
    • false (default)
  • Example:

    def foo(arg):
        """|<Trigger completion or code action here"""
    

• python.analysis.displayEnglishDiagnostics

  • Display diagnostics in English regardless of VS Code's display language.
  • Accepted values:
    • true
    • false (default)

• python.analysis.generateWithTypeAnnotation

  • Add type annotations when generating code. Defaults to false for type checking mode off, and true for other modes.
  • Accepted values:
    • true
    • false (default)

• python.analysis.diagnosticsSource

  • Allows specifying a different type checker to use for diagnostics. Pylance will combine its results with the chosen server.
  • This setting applies to all workspace folders in the current VS Code window.
  • Accepted values:
    • Pylance (default) - Use Pylance for diagnostics.
    • Pylance + Pyright - Use a different version of Pyright for diagnostics. Allows running a different Pyright than the one shipped with the Pylance extension. Pyright diagnostics will completely replace the diagnostics from Pylance. See the python.analysis.pyrightVersion setting.
    • Pylance + Pyrefly - Use Pyrefly for diagnostics. Pylance will search for a Pyrefly installation in your virtual environments or download it automatically. See the python.analysis.pyreflyVersion setting.

• python.analysis.pyrightVersion

  • Specifies the version of Pyright to use for diagnostics. This setting is only used when python.analysis.diagnosticsSource is set to Pylance + Pyright. Minimum version required is 1.1.397 or higher.
  • Accepted values:
    • version string, i.e. 1.1.397
    • path to a pyright-langserver.js file. For example, the Pyright installed by the PyPI Pyright module. In that case the path would be something like ~/.cache/pyright-python/1.1.397/node_modules/pyright/dist/pyright-langserver.js

• python.analysis.pyreflyVersion

  • Specifies the version of Pyrefly to use for diagnostics. This setting is only used when python.analysis.diagnosticsSource is set to Pylance + Pyrefly. Minimum version allowed is 1.1.1.
  • Accepted values:
    • empty (default) — automatically find or download the latest version
    • version string, e.g. 1.1.1 — download and use that specific version
    • path to a local pyrefly executable

• python.analysis.enableColorPicker

  • Enable/disable color picker in the editor for '#RRGGBB' strings. For all eight-digit hex strings in a workspace, choose the alpha placement explicitly.
  • Accepted values:
    • true (default) — enables the color picker; eight-digit hex strings use the default RRGGBBAA ordering
    • false
    • RRGGBBAA — same eight-digit behavior as true
    • AARRGGBB

• python.analysis.enableTroubleshootMissingImports

  • Enable/disable the Quick Fix for troubleshooting missing imports. This Quick Fix requires the Python Environments extension to be installed and enabled.
  • Accepted values:
    • true
    • false (default)

• python.analysis.gotoOverrideCodeLens (Experimental)

  • Enable/disable a CodeLens on methods that override a base-class member. Clicking it peeks the overridden declaration.
  • Accepted values:
    • true
    • false (default)

• python.analysis.supportHtmlEmbeddedPython (Experimental)

  • Enable/disable language support (IntelliSense, diagnostics) for Python embedded in HTML files, such as PyScript <py-script>/<script type="py"> blocks.
  • Accepted values:
    • true
    • false (default)

• python.analysis.cellMagicLanguages (Experimental)

  • Maps IPython cell magic names, without the leading %%, to VS Code language identifiers. In mapped Python notebook cells, Pylance forwards completions, hover, and go to definition for the cell body to the extension that provides the configured language.
  • Diagnostics are projected when the configured language provider publishes them for hidden virtual documents. Pull-only diagnostic providers, including VS Code's built-in JSON support, do not supply diagnostics for mapped cells.
  • Default value: {}
  • Example: {"sql": "sql", "kql": "kusto", "cypher": "cypher"}

• python.analysis.enablePyreflyNotificationForAll (Experimental)

  • Offers to switch the Python diagnostics provider to Pyrefly when the effective type-checking mode is off, even if Pyrefly is not installed or configured. Pylance downloads Pyrefly if needed after you accept the offer.
  • This setting works independently of python.analysis.enablePyreflyNotification and respects a previous dismissal of the offer.
  • Accepted values:
    • true
    • false (default)

• python.analysis.enablePyreflyShadowExperiment (Experimental)

  • Force-enable a hidden Pyrefly-typed Pylance language server alongside the primary server and log its telemetry events. When disabled, enrollment remains controlled by the experiment service. For internal performance and reliability testing only. Requires reloading the window.
  • Accepted values:
    • true
    • false (default)

Semantic highlighting

Visual Studio Code uses TextMate grammars as the main tokenization engine. TextMate grammars work on a single file as input and break it up based on lexical rules expressed in regular expressions.

Semantic tokenization allows language servers to provide additional token information based on the language server's knowledge on how to resolve symbols in the context of a project. Themes can opt-in to use semantic tokens to improve and refine the syntax highlighting from grammars. The editor applies the highlighting from semantic tokens on top of the highlighting from grammars.

Here's an example of what semantic highlighting can add:

Without semantic highlighting:

With semantic highlighting:

Semantic colors can be customized in settings.json by associating the Pylance semantic token types and modifiers with the desired colors.

• Semantic token types

  • class, enum
  • parameter, variable, property, enumMember
  • function, member
  • module
  • intrinsic
  • magicFunction (dunder methods)
  • selfParameter, clsParameter

• Semantic token modifiers

  • declaration
  • readonly, static, abstract
  • async
  • typeHint, typeHintComment
  • decorator
  • builtin
  • documentation
  • overridden
  • callable
  • library

The scope inspector tool allows you to explore what semantic tokens are present in a source file and what theme rules they match to.

Example of customizing semantic colors in settings.json:

{
    "editor.semanticTokenColorCustomizations": {
        "[One Dark Pro]": { // Apply to this theme only
            "enabled": true,
            "rules": {
                "magicFunction:python": "#ee0000",
                "function.declaration:python": "#990000",
                "*.decorator:python": "#0000dd",
                "*.library:python": "#008000",
                "*.typeHint:python": "#5500aa",
                "*.typeHintComment:python": "#aaaaaa"
            }
        }
    }
}

Code Actions

Pylance provides a set of code actions that are available through the lightbulb menu (or Ctrl+. / Cmd+.). The exact titles can vary depending on context (e.g. the unresolved symbol name), but the actions below are what Pylance can offer.

Quick Fixes

• Remove unused import
• Remove all unused imports
• Add import: ... (adds a missing import for an unresolved symbol)
• Search for additional imports
• Change spelling to ... (may also add an import when the best match is an auto-import)
• Add # type: ignore / # pyright: ignore[...] for a diagnostic
• Add ... to python.analysis.extraPaths (for unresolved imports)
• Troubleshoot missing imports (third-party imports; requires Python Environments extension)
• Select Interpreter / Select Kernel (for unresolved imports)
• Learn more about import resolution
• Fix formatted string (for specific diagnostics that provide a fix)

Refactorings

• Extract Variable
• Extract Method
• Move symbols to file...
• Move symbols to new file...
• Convert to explicit imports (for from module import *)
• Convert to module import (for from x import y)
• Convert import to relative path / absolute path (and Convert all... variants)
• Add type annotation (at cursor)
• Rename module (shadows stdlib module)
• Implement all abstract classes
• Add pytest fixture type annotation (and Add all... variants)

AI-assisted code actions (require Copilot)

• Generate docstring (for empty docstrings)
• Generate docstring (with Copilot)
• Generate function ... / Generate class ...
• Generate member ...
• Convert to f-string / Convert to format()
• Convert lambda to named function
• Implement all abstract classes (with Copilot)

Source (whole-file) code actions

• source.unusedImports

  • Remove all unused imports in a file

• source.convertImportFormat

  • Convert import format according to python.analysis.importFormat.

• source.convertImportStar

  • Convert all wildcard imports (from module import *) to explicit imports listing all imported symbols.

• source.convertImportToModule

  • Convert from x import y style imports into module imports.

• source.addTypeAnnotation

  • Add type annotations throughout the file where they can be inferred.

• source.renameShadowedStdlibImports

  • Rename imported user modules that shadow stdlib module names.

• source.fixAll.pylance

  • Apply the commands listed in the python.analysis.fixAll setting

Troubleshooting

Known issues are documented in TROUBLESHOOTING.

Repeated crashes

In desktop VS Code, Pylance automatically restarts after an unexpected server exit. To avoid an endless crash loop, it stops restarting after five crashes unless the server has run continuously for at least 10 minutes between failures. Reaching a ready state briefly does not reset this count; time spent starting or stopped does not count toward recovery. The five-crashes-in-three-minutes limit also remains in effect.

If Pylance stops restarting, inspect the Pylance output channel for crash details and address the reported cause before reloading the VS Code window to try again. The restart limits prevent repeated failures from continuing indefinitely; they do not fix the cause of a crash.

Contributing

Pylance leverages Microsoft's open-source static type checking tool, Pyright, to provide performant language support for Python.

Code contributions are welcomed via the Pyright repo.

Pylance ships with a collection of type stubs for popular modules to provide fast and accurate auto-completions and type checking. Our type stubs are sourced from typeshed and our work-in-progress stub repository, microsoft/python-type-stubs. Type stubs in microsoft/python-type-stubs will be contributed back to typeshed or added inline to source packages once they are of high enough quality.

For information on getting started, refer to the CONTRIBUTING instructions.

Feedback

• File a bug in GitHub Issues
• Tweet us with other feedback

License

See Pylance's license and the pylance-release repository's license for more information.