Self-Hosted Python Type Checking: MyPy vs Pyright vs Pyre vs Pytype vs Beartype

Introduction

Python’s dynamic typing is both its greatest strength and its most notorious weakness. While duck typing enables rapid prototyping, it also allows entire categories of bugs to slip through to production — AttributeError, TypeError, and NoneType errors are among the most common Python exceptions in production logs. Static type checking bridges this gap, catching type errors at development time without sacrificing Python’s flexibility.

The Python ecosystem now offers several mature type checkers, each with distinct philosophies, performance characteristics, and integration patterns. This guide compares five leading options: MyPy (the de facto standard), Pyright (Microsoft’s high-performance checker), Pyre (Meta’s incremental checker for large codebases), Pytype (Google’s inference-based checker), and Beartype (the zero-overhead runtime checker).

Comparison Table

MyPy: The Reference Implementation

MyPy is the original Python type checker, created by Jukka Lehtinen and now maintained by the Python community under the PSF umbrella. It serves as the reference implementation for Python’s type hinting system and is the most widely adopted type checker.

Installation:

1

pip install mypy

Basic Configuration (pyproject.toml):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

[tool.mypy]
python_version = "3.11"
strict = true
warn_return_any = true
warn_unused_configs = true
disallow_untyped_defs = true
check_untyped_defs = true
no_implicit_optional = true
warn_redundant_casts = true

[[tool.mypy.overrides]]
module = ["tests.*"]
ignore_errors = true

Example Usage:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

# example.py
from typing import Optional

def greet(name: Optional[str]) -> str:
    if name is None:
        return "Hello, stranger!"
    return f"Hello, {name}!"

# Type checking reveals: if we forget the None check,
# mypy will catch the type mismatch
result: str = greet(None)  # OK — mypy verifies this

MyPy’s strength lies in its comprehensive feature set. It supports generics, protocols, overloads, type narrowing, and the full range of PEP 484+ typing features. Its plugin system allows frameworks like Django, SQLAlchemy, and Pydantic to provide custom type inference. MyPy also offers stubgen for auto-generating .pyi stub files from existing code.

However, MyPy’s performance can be a bottleneck on large codebases. A full type check on a 500K-line codebase can take 30-60 seconds. Its caching system (mypy --incremental) mitigates this for incremental checks but requires careful configuration.

Pyright: Microsoft’s High-Performance Alternative

Pyright is Microsoft’s type checker, written in TypeScript and compiled to native code via Node.js. It powers the Pylance language server in VS Code and is designed for speed — it can process millions of lines of code in seconds.

Installation:

1
2
3

npm install -g pyright
# or via pip:
pip install pyright

Configuration (pyrightconfig.json):

1
2
3
4
5
6
7
8
9

{
  "include": ["src"],
  "exclude": ["**/node_modules", "**/__pycache__", "tests"],
  "typeCheckingMode": "strict",
  "reportMissingImports": true,
  "reportMissingTypeStubs": false,
  "pythonVersion": "3.11",
  "pythonPlatform": "Linux"
}

Pyright’s key advantage is raw speed. Its TypeScript-based engine is optimized for real-time feedback in the editor, making it the default choice for VS Code users (via Pylance). It also supports advanced features like type narrowing through assertions, exhaustive checking of match/case statements, and recursive type aliases.

Pyright is notably stricter than MyPy by default. It catches cases that MyPy silently accepts, which can be both a blessing (more bugs caught) and a curse (more type annotations needed). The strict mode enables all checks and is recommended for new projects.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

# Pyright's stricter analysis catches this subtle bug
from typing import Sequence

def process(items: Sequence[int]) -> list[int]:
    result: list[int] = []
    for item in items:
        result.append(item)
    return result

# With strict mode, Pyright warns about:
# - Missing return type annotations on nested functions
# - Implicit relative imports
# - Unnecessary isinstance checks

Pyre: Meta’s Incremental Checker

Pyre (Python REasoning) is Meta’s type checker, designed for their massive Python monorepo. It’s written in OCaml and optimized for incremental type checking — it can process single-file changes without re-analyzing the entire codebase.

Installation:

1

pip install pyre-check

Setup:

1
2
3
4
5
6

# Initialize Pyre in your project
pyre init
# Start the persistent server for incremental checks
pyre
# Run a one-shot type check
pyre check

Pyre’s “watchman” mode runs a persistent daemon that maintains type state in memory. When you edit a file, only that file and its dependents are re-checked. This makes Pyre uniquely suited for large monorepos where full-project checks are impractical.

1
2
3
4
5
6
7

# Pyre configuration (.pyre_configuration)
{
  "source_directories": ["src"],
  "search_path": ["stubs"],
  "exclude": [".*/tests/.*"],
  "strict": true
}

Pyre also offers a unique “taint analysis” mode that tracks data flow for security analysis — useful for detecting injection vulnerabilities and sensitive data leaks. Its “infer” command can automatically generate type annotations for untyped code.

Pytype: Google’s Inference-First Checker

Pytype takes a fundamentally different approach: instead of requiring type annotations, it infers types from runtime behavior. This makes it ideal for gradually typing legacy codebases where adding annotations is impractical.

Installation:

1

pip install pytype

Usage:

1
2
3
4
5
6

# Type-check a file or directory
pytype src/
# Generate type stubs
pytype src/ -o stubs/
# Merge inferred types into source as annotations
merge-pyi -i src/script.py stubs/script.pyi

Pytype’s key innovation is that it can type-check entirely untyped code by analyzing control flow and inferring types. It’s also the only type checker that can handle pyi merging — it can generate .pyi stub files with inferred types and merge them back into your source code as inline annotations.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

# Pytype infers types from usage patterns
# No annotations needed:
def add(a, b):
    return a + b

def process(data, handler):
    result = handler(data)
    if result > 0:
        return str(result)
    return None

# Pytype will infer:
# - add(a: Any, b: Any) -> Any
# - process(data: Any, handler: Callable) -> Optional[str]
# And warn about potential NoneType errors

Beartype: Zero-Overhead Runtime Checking

Beartype takes the opposite approach from all other checkers: it checks types at runtime instead of at analysis time. But unlike traditional runtime checkers (like typeguard or enforce), Beartype uses a novel “O(1) random sampling” algorithm that adds near-zero overhead.

Installation:

1

pip install beartype

Usage:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

from beartype import beartype
from typing import List, Optional

@beartype
def process_batch(items: List[float], scale: Optional[float] = None) -> List[float]:
    if scale is None:
        scale = 1.0
    return [item * scale for item in items]

# Runtime type checking with negligible overhead
result = process_batch([1.0, 2.0, 3.0], scale=2.0)  # OK
# result = process_batch(["a", "b"])  # Raises BeartypeCallHintParamViolation

Beartype’s performance advantage comes from its random sampling strategy — it checks types probabilistically at function boundaries, reducing overhead to O(1) instead of O(n) for deeply nested structures. For production systems, Beartype can be configured to check only a fraction of calls, making it suitable for use in hot paths.

The beartype.claw module also supports import hooks that automatically apply @beartype to all functions in a package:

1
2
3

# In your package's __init__.py
from beartype.claw import beartype_this_package
beartype_this_package()

Deployment and CI Integration

All five type checkers integrate seamlessly into CI/CD pipelines. Here’s a GitHub Actions workflow that runs all checkers:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

name: Type Checking
on: [push, pull_request]

jobs:
  type-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: '3.11'

      - name: Install type checkers
        run: |
          pip install mypy pyright pyre-check pytype beartype

      - name: Run MyPy
        run: mypy src/ --strict

      - name: Run Pyright
        run: pyright src/

      - name: Run Pytype
        run: pytype src/

      - name: Run Beartype tests
        run: pytest tests/ -v

For pre-commit hooks:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/pre-commit/mirrors-mypy
    rev: v1.11.0
    hooks:
      - id: mypy
        args: [--strict, --ignore-missing-imports]

  - repo: https://github.com/RobertCraigie/pyright-python
    rev: v1.1.370
    hooks:
      - id: pyright

Performance Benchmarks

Type checking speed varies dramatically between checkers. On a 100K-line Python codebase:

Pyright leads in raw speed, while Pyre’s daemon mode delivers the fastest incremental checks. Beartype adds essentially zero build-time cost since it operates entirely at runtime.

Why Self-Host Your Type Checking Pipeline?

Running type checkers locally and in your CI pipeline gives you complete control over your code quality workflow. Unlike SaaS code analysis platforms that require sending your code to external servers, self-hosted type checking keeps your intellectual property within your infrastructure. You define the rules, choose the strictness level, and integrate deeply with your existing toolchain.

For teams managing large Python codebases, combining multiple type checkers provides defense-in-depth. MyPy serves as the baseline for CI enforcement, Pyright provides real-time IDE feedback, and Beartype catches runtime type violations in production that static analysis could miss. Our Python logging libraries comparison and Python ORM libraries guide cover complementary aspects of the Python development ecosystem.

For profiling and performance optimization, see our Python profiling tools comparison. Together, type checking, logging, ORM selection, and profiling form a complete quality assurance toolkit for Python projects.

FAQ

Which type checker should I start with?

Start with MyPy. It’s the most widely adopted, has the largest community, and is the reference implementation for Python typing PEPs. Once comfortable, add Pyright for faster IDE feedback and Beartype for runtime safety in critical paths.

Can I use multiple type checkers together?

Yes. Many mature projects run MyPy in CI, Pyright in the editor, and Beartype in production. Each checker catches different issues — MyPy and Pyright overlap 80-90% but their remaining 10-20% catches are often complementary. Beartype adds runtime guarantees that static checkers cannot provide.

Does type checking slow down my development?

Initially, adding type annotations requires effort, especially for existing untyped codebases. Start with gradual typing — use mypy --check-untyped-defs on new code and pytype’s inference on legacy code. Modern IDEs with Pylance make type-driven development faster by providing better autocomplete, refactoring support, and documentation on hover.

What about Python 3.12+ syntax features?

All major type checkers support Python 3.12 syntax including PEP 695 type parameter syntax (class Container[T]:), PEP 698 @override, and PEP 692 TypedDict with Unpack. MyPy and Pyright typically lead in adopting new typing PEPs, with Pyre and Pytype following within a few releases.

Is Beartype a replacement for MyPy?

No. Beartype is complementary, not a replacement. Static checkers (MyPy, Pyright, Pyre, Pytype) catch bugs at development time without running code. Beartype catches bugs at runtime when code executes. Use both for maximum safety — static checking in CI and runtime checking in tests and production.

How do I handle third-party libraries without type stubs?

All checkers support ignoring missing imports (--ignore-missing-imports in MyPy, reportMissingTypeStubs: false in Pyright). For popular packages, install types packages (e.g., pip install types-requests). Pytype can infer types from untyped libraries at runtime, making it the best choice for codebases with heavy third-party dependencies lacking stubs.

💰 想测试你的市场判断力？我用 Polymarket 做预测市场交易——这是全球最大的预测市场平台，从大选结果到技术监管时间线，什么都可以押注。和赌博不同，这是真正的信息市场：你懂的信息越多，胜率越高。我靠预测技术相关事件的走向已经赚了不少。用我的邀请链接注册：Polymarket.com