Pyright - Fast Python Type Checker progressive_disclosure: entry_point: summary: "Fast Python type checker from Microsoft with VS Code integration and strict modes" when_to_use: - "When needing faster type checking than mypy" - "When using VS Code (Pylance)" - "When requiring stricter type checking" - "When migrating from mypy" quick_start: - "npm install -g pyright" - "Create pyrightconfig.json" - "pyright ." token_estimate: entry: 65-80 full: 3500-4500 Installation Node.js (Recommended)

Global installation

npm install -g pyright

Per-project installation

npm install --save-dev pyright

Verify installation

pyright --version

VS Code (Pylance)

Pyright powers Pylance extension:

Install Pylance extension (includes pyright)

code --install-extension ms-python.vscode-pylance

pip Installation

Community wrapper

pip install pyright

Note: Still requires Node.js runtime

Configuration pyrightconfig.json { "include": [ "src" ], "exclude": [ "/node_modules", "/pycache", ".venv" ], "typeCheckingMode": "basic", "pythonVersion": "3.11", "pythonPlatform": "Linux", "reportMissingImports": true, "reportMissingTypeStubs": false, "strictListInference": true, "strictDictionaryInference": true, "strictSetInference": true }

Type Checking Modes

Basic Mode (Default):

{ "typeCheckingMode": "basic", "reportUnusedImport": "warning", "reportUnusedVariable": "warning" }

Standard Mode:

{ "typeCheckingMode": "standard", "reportUnknownParameterType": "error", "reportUnknownArgumentType": "error", "reportUnknownVariableType": "error" }

Strict Mode (Maximum type safety):

{ "typeCheckingMode": "strict", "reportPrivateUsage": "error", "reportConstantRedefinition": "error", "reportIncompatibleMethodOverride": "error", "reportIncompatibleVariableOverride": "error", "reportUnnecessaryIsInstance": "warning", "reportUnnecessaryCast": "warning" }

Per-File Configuration

pyright: strict

"""Strict type checking for this file."""

pyright: basic

"""Basic type checking."""

pyright: reportGeneralTypeIssues=false

"""Disable specific diagnostics."""

VS Code Integration settings.json { "python.languageServer": "Pylance", "python.analysis.typeCheckingMode": "basic", "python.analysis.diagnosticMode": "workspace", "python.analysis.autoImportCompletions": true, "python.analysis.inlayHints.functionReturnTypes": true, "python.analysis.inlayHints.variableTypes": true, "python.analysis.completeFunctionParens": true }

Workspace Configuration { "python.analysis.extraPaths": [ "./src", "./lib" ], "python.analysis.stubPath": "./typings", "python.analysis.diagnosticSeverityOverrides": { "reportUnusedImport": "warning", "reportUnusedVariable": "warning", "reportGeneralTypeIssues": "error" } }

Type Checking Features Type Narrowing from typing import Union

def process(value: Union[str, int]) -> str: # Pyright narrows type based on isinstance if isinstance(value, str): return value.upper() # value is str here else: return str(value) # value is int here

Type guards

from typing import TypeGuard

def is_str_list(val: list[object]) -> TypeGuard[list[str]]: return all(isinstance(x, str) for x in val)

def process_list(items: list[object]) -> None: if is_str_list(items): # items is list[str] here print(", ".join(items))

Protocol Support from typing import Protocol

class Drawable(Protocol): def draw(self) -> None: ...

class Circle: def draw(self) -> None: print("Drawing circle")

def render(obj: Drawable) -> None: obj.draw()

Works with structural typing

render(Circle()) # ✓ No explicit inheritance needed

TypedDict from typing import TypedDict, NotRequired

class User(TypedDict): name: str age: int email: NotRequired[str] # Optional in Python 3.11+

def create_user(data: User) -> None: print(data["name"]) # ✓ Type-safe # print(data["missing"]) # ✗ Error

user: User = { "name": "Alice", "age": 30 } # ✓ email is optional

Literal Types from typing import Literal

Mode = Literal["read", "write", "append"]

def open_file(mode: Mode) -> None: ...

open_file("read") # ✓ open_file("delete") # ✗ Error

Advanced Features Variance and Generics from typing import TypeVar, Generic, Sequence

T_co = TypeVar("T_co", covariant=True) T_contra = TypeVar("T_contra", contravariant=True)

class Reader(Generic[T_co]): def read(self) -> T_co: ...

class Writer(Generic[T_contra]): def write(self, item: T_contra) -> None: ...

Covariance: Reader[Dog] is subtype of Reader[Animal]

Contravariance: Writer[Animal] is subtype of Writer[Dog]

ParamSpec from typing import ParamSpec, TypeVar, Callable

P = ParamSpec("P") R = TypeVar("R")

def add_logging(f: Callable[P, R]) -> Callable[P, R]: def wrapper(args: P.args, kwargs: P.kwargs) -> R: print(f"Calling {f.name}") return f(args, **kwargs) return wrapper

@add_logging def greet(name: str, age: int) -> str: return f"Hello {name}, {age}"

Type-safe: greet("Alice", 30)

Type Aliases from typing import TypeAlias

Simple alias

UserId: TypeAlias = int Username: TypeAlias = str

Generic alias

from collections.abc import Sequence Vector: TypeAlias = Sequence[float]

Complex alias

JSON: TypeAlias = dict[str, "JSON"] | list["JSON"] | str | int | float | bool | None

CI/CD Integration GitHub Actions name: Type Check

on: [push, pull_request]

jobs: typecheck: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4

  - name: Set up Node.js
    uses: actions/setup-node@v4
    with:
      node-version: '20'

  - name: Install pyright
    run: npm install -g pyright

  - name: Set up Python
    uses: actions/setup-python@v5
    with:
      python-version: '3.11'

  - name: Install dependencies
    run: |
      python -m pip install --upgrade pip
      pip install -r requirements.txt

  - name: Run pyright
    run: pyright

Pre-commit Hook

.pre-commit-config.yaml

repos: - repo: local hooks: - id: pyright name: pyright entry: pyright language: node types: [python] pass_filenames: false additional_dependencies: ['pyright@1.1.350']

Makefile .PHONY: typecheck typecheck-strict

typecheck: pyright

typecheck-strict: pyright --level strict

typecheck-watch: pyright --watch

typecheck-stats: pyright --stats

Migration from mypy Configuration Mapping { "// mypy: disallow_untyped_defs": "reportUntypedFunctionDecorator", "// mypy: disallow_any_generics": "reportMissingTypeArgument", "// mypy: warn_return_any": "reportUnknownArgumentType", "// mypy: strict_equality": "reportUnnecessaryComparison", "// mypy: warn_unused_ignores": "reportUnnecessaryTypeIgnoreComment" }

Comment Syntax

mypy: ignore-errors

↓ pyright equivalent

pyright: reportGeneralTypeIssues=false

type: ignore

↓ pyright equivalent

pyright: ignore

type: ignore[error-code]

↓ pyright equivalent

pyright: ignore[reportGeneralTypeIssues]

Gradual Migration { "typeCheckingMode": "basic", "include": ["src/new_module"], "exclude": ["src/legacy"], "reportMissingImports": true, "reportMissingTypeStubs": false }

Performance Optimization Baseline Performance

Create performance baseline

pyright --stats --createstub

Compare after changes

pyright --stats

Watch Mode

Fast incremental checking

pyright --watch

With specific path

pyright --watch src/

Parallel Checking { "executionEnvironments": [ { "root": "src", "pythonVersion": "3.11" }, { "root": "tests", "pythonVersion": "3.11", "extraPaths": ["src"] } ] }

Common Patterns Optional Handling from typing import Optional

def get_user(user_id: int) -> Optional[str]: return "Alice" if user_id == 1 else None

Before pyright 1.1.200

user = get_user(1) if user is not None: print(user.upper())

With pyright type narrowing

user = get_user(1) if user: # Narrows to str print(user.upper())

Union Narrowing from typing import Union

def process(value: Union[str, list[str]]) -> str: if isinstance(value, list): return ", ".join(value) # value is list[str] return value # value is str

Overload from typing import overload, Literal

@overload def open_file(path: str, mode: Literal["r"]) -> str: ...

@overload def open_file(path: str, mode: Literal["rb"]) -> bytes: ...

def open_file(path: str, mode: str) -> str | bytes: if mode == "rb": return b"binary data" return "text data"

Type-safe usage

text: str = open_file("file.txt", "r") data: bytes = open_file("file.bin", "rb")

Assertion Functions from typing import Never

def assert_never(value: Never) -> Never: raise AssertionError(f"Unexpected value: {value}")

def handle_status(status: Literal["success", "error"]) -> None: if status == "success": print("OK") elif status == "error": print("Failed") else: assert_never(status) # Exhaustiveness check

Pyright vs mypy Performance Comparison

Typical project (10K lines)

mypy: ~5-10 seconds

pyright: ~1-2 seconds

Large project (100K lines)

mypy: ~60-120 seconds

pyright: ~10-20 seconds

Feature Differences

Pyright Advantages:

5-10x faster type checking Better type inference VS Code integration (Pylance) Active development by Microsoft Better Protocol support Superior type narrowing

mypy Advantages:

More mature ecosystem Plugin system Finer-grained control Better documentation More configuration options When to Use Pyright ✅ VS Code users ✅ Need fast feedback ✅ Want strict type checking ✅ Modern Python (3.10+) ✅ Starting new projects When to Use mypy ✅ Existing mypy setup ✅ Need mypy plugins ✅ Non-VS Code editors ✅ Legacy Python (<3.8) ✅ Team prefers mypy Best Practices Start with Basic Mode { "typeCheckingMode": "basic", "reportMissingImports": true, "reportUndefinedVariable": true }

Gradually Increase Strictness { "typeCheckingMode": "standard", "reportUnknownParameterType": "warning", "reportUnknownArgumentType": "warning" }

Use Type Stubs

Generate stubs for third-party packages

pyright --createstub package_name

Custom stubs directory

mkdir -p typings

Leverage Inlay Hints { "python.analysis.inlayHints.variableTypes": true, "python.analysis.inlayHints.functionReturnTypes": true, "python.analysis.inlayHints.callArgumentNames": true }

Type Coverage

Check type completeness

pyright --stats

Output:

Files analyzed: 42

Lines of code: 3,421

Type completeness: 87.3%

Ignore Strategically

Avoid broad ignores

pyright: ignore # ✗ Too broad

Prefer specific ignores

pyright: ignore[reportGeneralTypeIssues] # ✓ Specific

Or fix the issue

value: str = cast(str, unknown_value) # ✓ Best

Troubleshooting Import Resolution { "extraPaths": ["src", "lib"], "stubPath": "typings", "venvPath": ".", "venv": ".venv" }

Stub Generation

Generate stubs for package

pyright --createstub requests

Custom stub location

pyright --createstub requests --outputdir typings

Performance Issues { "exclude": [ "/node_modules", "/pycache", ".venv", "build", "dist" ] }

VS Code Not Using Pyright { "python.languageServer": "Pylance", "python.analysis.typeCheckingMode": "basic", "python.analysis.diagnosticMode": "workspace" }

Resources

Official:

Pyright Docs Pylance Extension Type Checking Mode Guide

Community:

awesome-pyright Python Type Hints PEP 484 - Type Hints

Related Skills: mypy, FastAPI, Django, pytest Token Count: ~3,850 tokens