Skip to content

pyright: Python Static Type Checker by Microsoft

by Tim Hopper · Markdown
Type Checking

pyright is a static type checker and language server for Python, built and maintained by Microsoft. It reads type annotations, infers types for code that has none, and reports mismatches before the code runs.

pyright is written in TypeScript and runs on Node.js. The CLI and language server are MIT-licensed and ship on both PyPI and npm, so uv add --dev pyright works without a separate Node install. Release 1.1.411 landed in June 2026, on a cadence that has slowed from weekly in 2024 to roughly monthly.

pyright is also the engine inside the Pylance extension for Visual Studio Code, which has passed 196 million installs. Pylance is closed-source and layers autocompletion, signature help, and rename refactoring on top of pyright’s open-source language server.

When to use pyright

pyright is a strong choice for teams that want real-time type feedback in the editor, especially in VS Code through Pylance. Its aggressive type inference catches bugs in unannotated code that mypy skips by default.

Teams already using mypy as a CLI type checker have no urgent reason to switch, and the two coexist: Pylance in the editor for instant feedback, mypy in CI for the authoritative gate. For the full trade-off table, see How do mypy, pyright, and ty compare?.

The handbook’s default recommendation for new projects is Pyrefly, stable since May 2026 and more than 10x faster than pyright on the handbook’s benchmark codebases. ty is the alternative when its gradual guarantee matters, though it remains in beta.

Key Features

  • Type inference on unannotated code: pyright checks all code by default, including functions with no annotations, using inferred types. Four strictness levels (off, basic, standard, strict) control how aggressively it reports.
  • Flow analysis: tracks variable types through control flow paths, narrowing types after isinstance checks, is None guards, and similar patterns.
  • Parallel checking: pyright --threads splits analysis across worker threads and accepts an optional thread count.
  • Watch mode: pyright --watch rechecks files as they change, giving continuous feedback during development.
  • Standards-forward: often implements new typing PEPs before other checkers, and passes 134 of 141 cases (95.0%) on the official typing conformance suite as of June 2026.
  • Type stub integration: works with typeshed and custom stub files, and --verifytypes reports how complete a py.typed package’s public API is.

Configuration

pyright reads configuration from pyrightconfig.json or pyproject.toml (under [tool.pyright]).

pyproject.toml
[tool.pyright]
pythonVersion = "3.12"
typeCheckingMode = "standard"
reportMissingTypeStubs = false

The typeCheckingMode setting controls overall strictness:

Mode Behavior
off No type checking
basic Minimal checks, few false positives
standard Default. Checks most code, flags common errors
strict Requires annotations on all public functions, flags more issues

Any other value is rejected with Config "typeCheckingMode" entry must contain "off", "basic", "standard", or "strict"., and pyright falls back to standard. The all and recommended modes documented in some comparisons belong to basedpyright, not pyright.

pyright also supports execution environments for per-directory settings, which is useful for monorepos where different packages need different configurations:

pyrightconfig.json
{
  "executionEnvironments": [
    { "root": "src/backend", "pythonVersion": "3.11" },
    { "root": "src/scripts", "pythonVersion": "3.12" }
  ]
}

Installation and Usage

pyright ships on PyPI, so uv can install and run it with no Node.js setup. The PyPI package uses the node already on PATH and otherwise downloads its own build through nodeenv into ~/.cache/pyright-python the first time it runs.

The quickest way to run pyright is with uvx:

uvx pyright src/

For project use, add pyright as a development dependency:

uv add --dev pyright
uv run pyright src/

uv tool install pyright installs it globally instead, along with the pyright-langserver entry point that editors need.

Diagnostics name the file, position, and rule that fired:

$ uv run pyright src/
src/demo.py
  src/demo.py:5:5 - error: Argument of type "Literal['1']" cannot be assigned to parameter "a" of type "int" in function "add"
    "Literal['1']" is not assignable to "int" (reportArgumentType)
1 error, 0 warnings, 0 informations

Common command-line options:

# Check with a specific config file
pyright --project ./pyrightconfig.json

# Watch mode for continuous checking
pyright --watch

# Split checking across worker threads
pyright --threads src/

# Output as JSON for CI integration
pyright --outputjson src/

Editor Integration

VS Code: install the Pylance extension, which bundles pyright and adds autocompletion, signature help, auto-imports, and rename refactoring. Pylance is free but closed-source, and its license restricts it to official Microsoft VS Code builds. Forks such as Cursor, VSCodium, and Positron fall back to plain pyright or basedpyright.

Other editors: pyright’s open-source language server works anywhere LSP does. Start it with pyright-langserver --stdio. Neovim users configure it through nvim-lspconfig; Emacs users through Eglot or lsp-mode.

Pros

  • Checks unannotated code by default, catching bugs that mypy skips
  • VS Code integration through Pylance, which has passed 196 million installs
  • 95.0% on the official typing conformance suite as of June 2026, ahead of both mypy and ty
  • Granular configuration with per-directory execution environments for monorepos
  • MIT-licensed and published to both PyPI and npm, so uv add --dev pyright needs no separate Node install

Cons

  • No longer the fast option: mypy 2.x runs 2-3x faster on real-world codebases, and Pyrefly, ty, and Zuban are faster still
  • Aggressive inference on unannotated code can produce false positives in highly dynamic code
  • Needs a Node.js runtime, which the PyPI package downloads on first run and which offline or air-gapped CI has to provide up front
  • No plugin API, so the django-stubs and SQLAlchemy plugin behavior mypy users rely on has no equivalent
  • Pylance is closed-source and VS Code-only, so editor features beyond basic LSP do not travel to other editors

Learn More

Last updated on
pyreflypytest