Pyright — Fast Static Type Checker for Python

Introduction

Pyright is a static type checker for Python created by Microsoft. Written in TypeScript and running on Node.js, it delivers significantly faster analysis than traditional Python-based type checkers, making it practical for large codebases with millions of lines.

What Pyright Does

• Performs full static type analysis of Python code using PEP 484 type annotations
• Infers types for unannotated code using flow-sensitive narrowing and control flow analysis
• Reports type errors, missing imports, and unreachable code at development time
• Powers the Pylance VS Code extension for real-time editor diagnostics
• Supports all typing constructs including generics, protocols, TypedDict, and ParamSpec

Architecture Overview

Pyright parses Python source files into an AST, then runs multiple analysis passes: import resolution, scope analysis, type evaluation, and type narrowing. Its incremental architecture re-analyzes only changed files and their dependents. Because it runs on Node.js rather than CPython, startup and throughput are substantially faster than mypy for equivalent codebases.

Self-Hosting & Configuration

• Install via pip (pip install pyright) or npm (npm install pyright)
• Configure through a pyrightconfig.json file at the project root
• Set typeCheckingMode to basic, standard, or strict for varying rigor levels
• Define include and exclude paths to control which files are analyzed
• Use venvPath and venv settings to point Pyright at virtual environments

Key Features

• Analyzes large codebases 3-5x faster than mypy due to TypeScript runtime
• Watch mode re-checks only affected files on save for near-instant feedback
• Supports PEP 695 type parameter syntax and all modern typing features
• Provides detailed diagnostic messages with fix suggestions
• Full Language Server Protocol support for IDE integration beyond VS Code

Comparison with Similar Tools

• mypy — the original Python type checker, slower but with a broader plugin ecosystem
• pytype — Google's type checker with automatic type inference and rewriting
• Pyre — Meta's type checker focused on large monorepos with incremental analysis
• Ruff — ultrafast linter and formatter but does not perform type checking
• Pylint — general-purpose linter that catches code smells but not type errors

FAQ

Q: Can I use Pyright alongside mypy? A: Yes. Many teams run both in CI. Pyright and mypy may flag different issues due to differing inference strategies, so overlapping coverage can catch more bugs.

Q: Does Pyright replace Pylance? A: Pylance is a VS Code extension that bundles Pyright as its type-checking engine and adds IDE features like auto-imports and semantic highlighting. Pyright is the standalone CLI.

Q: How do I migrate a project from mypy to Pyright? A: Replace the mypy config with a pyrightconfig.json, run Pyright, and address any new diagnostics. Most PEP 484 annotations are fully compatible between the two.

Q: Does Pyright work with Django and other dynamic frameworks? A: Pyright handles most Django patterns when paired with django-stubs type stubs. Highly dynamic code may need targeted # type: ignore annotations.

Sources

• https://github.com/microsoft/pyright
• https://microsoft.github.io/pyright/