VSCode Pylance Extension Usage and Setup Instructions

VSCode Pylance Extension

The Pylance extension in VSCode provides powerful support for Python language development, such as smart hints, completions, diagnostics and analysis of code. In general, this extension will be installed with VSCode’s Python extension and will be the Python language server recognized by the Python extension.

Set up VSCode Pylance Extension

Like most VSCode extensions, Pylance provides developers with settings that allow you to tweak and change some of the functionality implemented by the Pylance extension by editing the setting.json file in the .vscode folder of your workspace or by editing the related items in VSCode’s Settings Panel.

Set up Python Type Checking Feature of the VSCode Pylance Extension

The setting item python.analysis.typeCheckingMode of the Pylance extension can be used to set Pylance’s Python type checking mode. Different type checking modes correspond to different Python type checking rulesets, and are categorized into the following modes, from loose to strict.

off mode

The off mode is the default value for the python.analysis.typeCheckingMode setting item, which means that Python code is not type-checked, and is only diagnosed for invalid syntax, undefined content (variables, functions, etc.), and imports that are unresolved (e.g., imports of inaccessible Python modules or packages, or imports of non-existent content).

basic mode

The basic mode contains all the rules in the off mode, as well as basic Python type checking rules, such as that unknown class attributes should not be accessed, and that methods or functions should be called with all the necessary parameters.

standard mode

The standard mode contains all the rules in the off mode, as well as the basic and standard Python type checking rules, and is therefore stricter than the basic mode.

strict mode

The strict mode is the strictest type checking mode, and contains all the rules in the off mode, as well as all the Python type checking rules, e.g., reporting variables or parameters whose types cannot be derived.

{
	// The strictest mode strict
	"python.analysis.typeCheckingMode": "strict",
}

pyright/docs/configuration.md at main · microsoft/pyright

{
	// Customize the severity level of Python type checking rules
	"python.analysis.diagnosticSeverityOverrides": {
		// Imports that cannot be resolved
		"reportMissingImports": "warning"
	},
}

Set Python Files to be Diagnosed by the VSCode Pylance Extension

The Pylance extension’s setting item python.analysis.diagnosticMode can be used to set the scope in which Pylance will diagnose Python code files, and the problems obtained from diagnosis will be displayed in VSCode’s Problems Panel, and the valid values for this setting item are the following two.

openFilesOnly mode

The openFilesOnly mode is the default value for the python.analysis.diagnosticMode setting item, which indicates that Pylance only diagnoses Python code files that have been opened in VSCode.

workspace mode

The workspace mode means that Pylance will diagnose all Python code files in the VSCode workspace, as well as Python code files opened by VSCode.

{
	// Diagnose all and opened Python code files in the workspace
	"python.analysis.diagnosticMode": "workspace",
}

{
	// The path information of the files to be diagnosed
	"python.analysis.include": [
		// Three-character folders beginning with s and c
		"s?c\\",
		// First-level subfolders of the src folder
		"src\\*\\",
		// Files or folders in the src folder or any of its subfolders that end with s.py
		"src\\**\\*s.py"
	],
}

{
	// Path information for files that do not require diagnostics
	"python.analysis.exclude": [
		// A file or folder ending with test.py in the src folder or any subfolder
		"src\\**\\*test.py"
	],
}

Set Python Files that Ignore Diagnostic Results from the VSCode Pylance Extension

The Pylance extension’s setting item python.analysis.ignore (its default value is []) is an array containing path information, so that if the beginning of the path of a particular Python code file matches one of the items in this array, then Pylance’s diagnostic results (including errors and warnings) about the file will be ignored (not displayed).

Similar to the python.analysis.include setting item, python.analysis.ignore can also use relative paths, absolute paths, and path wildcards.

{
	// Path information for files that ignore diagnostic results
	"python.analysis.ignore": [
		// The first-level subfolders of the src folder whose name contains test
		"src\\*test*\\"
	],
}

Set the Python Type Stub File Directory for the VSCode Pylance Extension

The python.analysis.stubPath setting item of the Pylance extension can be used to specify the directory where the Python type stub files are located, similar to python.analysis.include, where you can take a relative or absolute path. The default value of python.analysis.stubPath is typings, which is the typings folder in the root directory of the VSCode workspace.

{
	// Specify the type stub file directory as the my_typings folder in the workspace
	"python.analysis.stubPath": "my_typings",
}

The setting item python.analysis.useLibraryCodeForTypes of the Pylance extension is a boolean value that can be used to specify whether or not to analyze the Python code file corresponding to a Python module that needs to be analyzed when the module doesn’t have a corresponding type stub file; the default value is true, which analyzes the corresponding code file.

{
	// This will not analyze the module's corresponding code file when the type stub file does not exist
	"python.analysis.useLibraryCodeForTypes": false,
}

Set Extra Python Module Paths for the VSCode Pylance Extension

The Pylance extension’s setting item python.analysis.extraPaths (its default value is []) is an array containing information about extra module paths, and Pylance attempts to find and analyze the code files corresponding to Python modules in these paths when they are imported. It should be noted that extra module paths do not affect Python’s own Module Search Path.

In terms of paths, python.analysis.extraPaths is similar to the python.analysis.include setting item in that you can use relative paths, absolute paths, and path wildcards. Paths in python.analysis.extraPaths need to point to a folder or a zip compressed file, pointing to anything else may not work.

{
	// Extra Python module paths
	"python.analysis.extraPaths": [
		// Search for modules in extra.zip in the root directory of the workspace
		"extra.zip"
	],
}

The Pylance extension’s setting item python.analysis.autoSearchPaths is a boolean value that can be used to specify whether to enable automatic Python Module Search Paths or not; by setting python.analysis.autoSearchPaths to true (the default value), Pylance can try to find and analyze the code files corresponding to Python modules from some predefined paths (e.g., the src folder in the root directory of the VSCode workspace) when they are imported.

In terms of effect, the automatic Module Search Paths are similar to the extra module paths, except that the paths in python.analysis.autoSearchPaths are preset, while the paths in python.analysis.extraPaths are specified by the developer. The automatic Module Search Paths also do not affect Python’s own Module Search Path, and may indicate that the module was not found ModuleNotFoundError at runtime.

{
	// Disable the automatic Python Module Search Paths
	"python.analysis.autoSearchPaths": false,
}

Set up Python Indexing Feature of the VSCode Pylance Extension

The Pylance extension’s setting item, python.analysis.indexing, can be used to control whether or not user files (Python code files in the VSCode workspace, whose corresponding modules should have valid fully qualified names), Python third-party packages or modules are indexed (the default is true, indexed). Effective indexing is a prerequisite for Pylance to automatically import modules, add import statements, and so on.

{
	// Disable Python indexing
	"python.analysis.indexing": false,
}

The Pylance extension’s setting item python.analysis.packageIndexDepths is an array containing indexing schemes, and different Python packages can have different indexing schemes. By default, Pylance indexes only Python packages located directly in third-party package directories (excluding modules, and subpackages or submodules within packages).

If you want to index subpackages or submodules of a Python package, you need to set the depth setting item of the corresponding scheme to 2 (the default is 1), and the name setting to the name of the Python package, and if you want to index subpackages or submodules of a subpackage, you need to set the depth setting item to 3, and so on. If you want to index all attributes of a Python package or module, you need to set the includeAllSymbols setting item of the corresponding scheme to true, in some cases includeAllSymbols doesn’t work and Pylance will index all attributes.

The Pylance extension’s setting item python.analysis.persistAllIndices is a boolean (the default is true, save) that can be used to set whether or not to save the compiled indexes for Python’s third-party packages and modules as json index files in the .cache subfolder of the dist folder of the Pylance extension installation directory for next use. If python.analysis.persistAllIndices is set to false, the json index files will not be used, even if they already exist.

The setting item python.analysis.userFileIndexingLimit of the Pylance extension can be used to set the maximum number of user files for indexing, which defaults to 2000, and if it is set to -1, it means that there is no limit to the number of user files that can participate in indexing. Setting it to -1 is not recommended due to the fact that indexing can involve a large number of operations in a short period of time.

{
	// This will not index Python code files in the workspace, unless they are opened
	"python.analysis.userFileIndexingLimit": 0,
	// Indexing scheme for the third-party package named just_test
	"python.analysis.packageIndexDepths": [
		{ "name": "just_test", "depth": 3, "includeAllSymbols": true }
	],
}

Set up Code Completion Feature of the VSCode Pylance Extension

The Pylance extension’s setting item, python.analysis.autoImportCompletions, can be used to set whether or not to enable Python import statement completion (the default is false, which does not do import statement completion), which automatically writes import or from…import to import Python modules when you use the module’s attributes and have not imported the module. If python.analysis.indexing is set to false, then Pylance’s import statement completion is only available for Python code files that have been opened in VSCode (the module corresponding to the file should have a valid fully qualified name).

The Pylance extension’s setting item, python.analysis.importFormat, can be used to set the format of Python’s import statement completion, and its valid values include the following two.

absolute format

The absolute format is the default value for the python.analysis.importFormat setting item, which indicates that the Python import statement is to be completed with a fully qualified name.

relative format

The relative format indicates that the Python import statement should be completed with relative names wherever possible, or fully qualified names if this is not possible.

The Pylance extension’s setting item, python.analysis.completeFunctionParens, can be used to set whether to enable Python function or method parenthesis completion, which automatically writes parentheses () after a function or method is selected to be called; the default is false, which does not perform function or method parenthesis completion.

The Pylance extension’s setting item, python.analysis.autoFormatStrings, can be used to set whether or not to complement Python strings with the prefix f when you write { in the string (note that this feature fails to have the desired effect in some cases). The default value of python.analysis.autoFormatStrings is false, which does not do prefix f completion.

{
	// Enable completion of import statements
	"python.analysis.autoImportCompletions": true,
	// Completion of import statements uses relative names
	"python.analysis.importFormat": "relative",
	// Enable parenthesis completion for functions or methods
	"python.analysis.completeFunctionParens": true,
	// Enable f prefix completion of strings (may have no effect)
	"python.analysis.autoFormatStrings": true,
}

Set up Code Inlay Hint Feature of the VSCode Pylance Extension

The Pylance extension’s setting item, python.analysis.inlayHints.variableTypes, can be used to set whether or not to enable the inlay hint feature for variable types (the default is false, which doesn’t enable it), which embeds a description of a variable’s type when you don’t specify the variable’s type using : and the variable type needs a clear description. For example, a=[1,2] will have the description embedded, b=1 or c=set() will not.

The Pylance extension’s setting item, python.analysis.inlayHints.functionReturnTypes, can be used to set whether or not to enable the inlay hint feature for function or method return values (the default is false, which doesn’t enable it), which embeds a description of the type of the function or method return value when you do not use -> to specify the type of the function or method return value.

The Pylance extension’s setting item, python.analysis.inlayHints.callArgumentNames, can be used to set whether to enable the inlay hint feature for parameter names, which attempts to embed parameter names for arguments when the name of that argument is not specified, to help the developers understand the meaning of the argument efficiently. Valid values for the python.analysis.inlayHints.callArgumentNames setting item include the following.

off

off is the default value of the python.analysis.inlayHints.callArgumentNames setting item, which indicates that the inlay hint feature for parameter names are disabled.

partial

partial indicates that if a argument is both a positional and named parameter, an attempt is made to embed the parameter name for it.

all

all indicates an attempt to embed parameter names for all arguments.

The Pylance extension’s setting item, python.analysis.inlayHints.pytestParameters, can be used to set whether or not to enable the inlay hint feature for the parameter types of a pytest function or method (the default is false, which does not enable it), which attempts to embed a description of the parameter type when Python’s pytest package is able to infer the type of a parameter and the parameter does not use : to specify the type. Note that use of the python.analysis.inlayHints.pytestParameters setting item assumes that the pytest package is available and that the python.analysis.enablePytestSupport setting item has a value of true.

The setting item python.analysis.enablePytestSupport for the Pylance extension is a boolean that can be used to set whether or not to enable support for the pytest package, which defaults to true, enable.

{
	// Enable inlay hints for variable types
	"python.analysis.inlayHints.variableTypes": true,
	// Enable inlay hints for return value types
	"python.analysis.inlayHints.functionReturnTypes": true,
	// Enable inlay hints for all parameter names
	"python.analysis.inlayHints.callArgumentNames": "all",
	// Enable inlay hints for the parameter types of pytest functions or methods
	"python.analysis.inlayHints.pytestParameters": true,
	// Disable support for pytest, which will invalidate the pytestParameters setting item
	"python.analysis.enablePytestSupport": false,
}

Set up Code Navigation Feature of the VSCode Pylance Extension

The Pylance extension’s setting item, python.analysis.gotoDefinitionInStringLiteral, can be used to set whether or not to enable module navigation feature for Python strings (the default is true, which enables it), which provides navigation for literals that are considered to be modules in Python strings. For example, for sys in "sys is here", you can use the context menu or shortcut key for sys to jump to the code file or type stub file associated with the module sys.

{
	// Disable module navigation for strings
	"python.analysis.gotoDefinitionInStringLiteral": false,
}

Set up Logging Feature of the VSCode Pylance Extension

The python.analysis.logLevel setting item of the Pylance extension, which can be used to set what Pylance outputs as a log, has the following valid values.

Error level

The Error level indicates that only errors are output to the log.

Warning level

The Warning level indicates that errors and warnings are output to the log.

Information level

The Information level is the default value for the setting item python.analysis.logLevel, which indicates that errors, warnings, and information are output to the log.

Trace level

The Trace level indicates that errors, warnings, information and traces are output as logs.

{
	// Set Pylance to report errors only
	"python.analysis.logLevel": "Error",
}

Set the Behavior of the VSCode Pylance Extension in the FixAll Command

The Pylance extension’s setting item python.analysis.fixAll is an array of strings (its default value is []), and each item in the array corresponds to a behavior that determines how the Pylance extension behaves when the Fix All command is executed; the following are valid values for the python.analysis.fixAll array.

source.unusedImports behavior

The source.unusedImports behavior removes some import statements from Python code files that have been opened in VSCode because they import modules that are not being used.

source.convertImportFormat behavior

The source.convertImportFormat behavior will convert import statements in Python code files that have been opened in VSCode based on the setting item python.analysis.importFormat.

{
	// Set the behavior when running the Fix All command
	"python.analysis.fixAll": [
		"source.unusedImports",
		"source.convertImportFormat"
	],
}

Set the Path to the Node.js Executable Running the VSCode Pylance Extension

The setting item python.analysis.nodeExecutable (which defaults to an empty string) of the Pylance extension is used to indicate an external Node.js executable that Pylance will run through this external Node.js. In general, Pylance uses VSCode’s own Node.js, and its memory is limited by VSCode, so if you want more memory space, then setting the python.analysis.nodeExecutable setting item is possible.

The value of the python.analysis.nodeExecutable setting item is not limited to the path of the Node.js executable, it can also be an alias pointing to Node.js, but in any case you should make sure that the value is able to start Node.js correctly on the command line.

{
	// External Node.js (not available in VSCode workspace settings)
	"python.analysis.nodeExecutable": "node",
}

Customize Python Syntax Highlighting Styles for the VSCode Pylance Extension

The editor.semanticTokenColorCustomizations setting item allows you to customize the Python syntax highlighting styles of the Pylance extension for a particular theme or for all themes of VSCode, mainly with respect to colors, of course. The following are the specific semantic token types and semantic token modifiers supported by the Pylance extension that can be used to customize Python syntax highlighting styles. In practice, the names of items should be suffixed with :python to restrict them to only work in the Python language, and all items should be placed in the rules setting.

Semantic token types include, but are not limited to, class, enum, parameter, variable, property, enumMember, function, member, module, intrinsic, magicFunction. selfParameter, clsParameter. Semantic token modifiers include, but are not limited to, declaration, readonly, static, abstract, async, typeHint, typeHintComment, decorator, builtin.

{
	// Customize Python syntax highlighting for all themes
	"editor.semanticTokenColorCustomizations": {
		"rules": {
			// Specify the color of the class
			"class:python": "#da9797",
			// Specify the color of declarations, e.g., class and function definitions
			"*.declaration:python": "#82cb7a"
		}
	}
}

Source Code

settings.json·codebeatme/python·GitHub