Pyright: Python Static Type Checker by Microsoft

pyright is a static type checker and language server for Python, built and maintained by Microsoft. It analyzes type annotations to detect bugs before runtime and provides editor features like autocompletion, hover information, and go-to-definition.

pyright powers the Pylance extension for Visual Studio Code. Pylance is closed-source and adds features on top of pyright’s open-source language server, but pyright itself can be used with any editor that supports LSP.

When to use pyright

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

Teams already using mypy as a CLI type checker have no urgent reason to switch. pyright and mypy can coexist: use Pylance in the editor for instant feedback and mypy in CI for type checking. For a detailed comparison, see How do mypy, pyright, and ty compare?.

For a newer, faster alternative, see ty, which is 10-100x faster than mypy and pyright and uses a gradual typing approach that avoids false positives on untyped code. ty is still in beta.

Key Features

• Type inference on unannotated code: pyright checks all code by default, including functions without type annotations, using inferred types. Five strictness levels (off, basic, standard, strict, all) control how aggressively it flags issues.
• On-demand type computation: computes types lazily rather than analyzing everything upfront, making it 3-5x faster than mypy on large codebases.
• Watch mode: pyright --watch rechecks files as they change, providing continuous feedback during development.
• Flow analysis: tracks variable types through control flow paths, narrowing types after isinstance checks, is None guards, and other patterns.
• Standards-forward: often implements new typing PEPs before other checkers, making it useful for projects using the latest typing features.
• Type stub integration: works with typeshed and custom stub files for libraries that don’t ship inline type annotations.

Configuration

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

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

The typeCheckingMode setting controls overall strictness:

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

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

Installation and Usage

# Install with uv
uv pip install pyright

# Or run without installing
uvx pyright src/

# Check a project
pyright src/

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

# Watch mode for continuous checking
pyright --watch

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

To add pyright as a development dependency in a uv project:

uv add --dev pyright
uv run pyright src/

Editor Integration

VS Code: install the Pylance extension, which bundles pyright and adds autocompletion, signature help, auto-imports, and rename refactoring. Pylance is closed-source but free.

Other editors: pyright’s open-source language server works with any editor that supports LSP. Run pyright --langserver or pyright-langserver --stdio to start it. Neovim users can configure it through nvim-lspconfig; Emacs users through Eglot or lsp-mode.

Pros

• Faster than mypy on most codebases (3-5x), though ty is now significantly faster than both
• Best-in-class VS Code integration through the Pylance extension
• Checks unannotated code by default, catching bugs that mypy skips
• Weekly releases with early adoption of new typing PEPs
• Granular configuration with per-directory execution environments for monorepos

Cons

• Aggressive inference on unannotated code can produce false positives in highly dynamic code
• Requires Node.js runtime (written in TypeScript)
• Pylance (the VS Code extension) is closed-source, so editor features beyond basic LSP are VS Code-only

Learn More

• How do mypy, pyright, and ty compare?
• How to migrate from Pyright to ty
• How to gradually adopt type checking in an existing Python project
• Official pyright Documentation
• Pylance Extension for VS Code
• pyright GitHub Repository
• mypy reference
• ty reference