pylance-release/USING_WITH_PYRIGHT.md

Pyright and Pylance Together

Pyright is an open source version of a Python type checker that forms the basis for Pylance. Both Pyright and Pylance can be used inside of an IDE to provide a language server for Python code.

Pyright can also be used on the command line to produce json or text output. This can be used in a variety of situations, like a pre-commit hook, or a github action.

However, Pylance and Pyright don't always produce the same results. There are several reasons why this may happen.

Pyright version and Pylance's underlying Pyright version are different

Since Pyright and Pylance have different release cadences, there are many times when the latest version of Pylance (even Pylance prerelease) is not based on the latest version of Pyright. If you're using one of the following tools to run Pyright, you can specify your Pylance version (latest-release, latest-prerelease, or version number) and the tool will use the matching version of Pyright:

• pyright-action: In v1.8.0+, provide the pylance-version option instead of version. For more details, see their documentation.
• pyright-python: In v1.1.338+, set the PYRIGHT_PYTHON_PYLANCE_VERSION environment variable and do not set PYRIGHT_PYTHON_FORCE_VERSION. For more details, see their documentation.

If you are aware of other similar tools that could benefit from having the same behavior, please let us know.

Type stub differences

Pylance comes bundled with a number of stubs, usually found here in the installation:

<pylance-extension-install>/dist/bundled
<pylance-extension-install>/dist/native-stubs

For Pyright to produce the same errors as Pylance, it needs to use the same stub files.

This might be done by copying the contents of each of the bundled Pylance stub folders to a new folder.

You'd then reference that new folder in your pyrightconfig.json

{
    "stubPath": "./pylanceStubs"
}

or pyproject.toml

[tool.pyright]
stubPath="./pylanceStubs"

Where pylanceStubs contains the contents of the bundled and native-stubs folders.

We have plans to make this easier in the future.

Settings differences

Both Pylance and Pyright have settings to control behavior. For the most part, they use the same values, but the few differences, described below, do have an impact on the analysis.

Setting	Pylance default	Pyright default	Description	Potential Impact
autoSearchPaths	true	false	Adds 'src' to the list of search paths.	This may change what files are found when analyzing. So if you're getting missing imports for modules in your 'src' tree, this might be why.
extraPaths	PYTHONPATH	[ ]	Additional search paths that will be used when searching for modules imported by files.	Pylance includes paths found in the PYTHONPATH environment variable and the PYTHONPATH definition from your .env file. Pyright ignores .env files and treats paths from the PYTHONPATH environment variable as third party library paths. This results in a difference in prioritization of these paths when resolving imports.
typeCheckingMode	off	standard	Determines what diagnostics are shown.	Pylance defaults to off. If you want to guarantee this is the same as Pyright, set it to standard (or whatever you want to enforce) by specifying it in your settings.json.

Here's an example pyrightconfig.json you would use to ensure Pylance and Pyright both picked up the same settings:

{
    "autoSearchPaths": false,
    "extraPaths": [], // Include paths from PYTHONPATH env var and .env definition
    "typeCheckingMode": "standard"
}

or pyproject.toml

[tool.pyright]
autoSearchPaths=false
extraPaths=[] # Include paths from PYTHONPATH env var and .env definition
typeCheckingMode="standard"

Diagnostic severity overrides

Both Pylance and Pyright support a python.analysis.diagnosticSeverityOverrides setting. Differences in this setting have a direct impact on the diagnostics returned. If you were attempting to get the same error output from both Pylance and Pyright, ensure that they are using the same value for this setting.

By default they are the same except for one value: reportShadowedImports.

In order to have Pylance and Pyright behave the same, you would set this value in a pyrightconfig.json

{
    "reportShadowedImports": "warning"
}

or pyproject.toml

[tool.pyright]
reportShadowedImports="warning"