Python Advanced: Mypy vs Pyright — A Detailed Comparison with Examples

Static type checking has become essential for maintaining Python codebases, especially as projects grow in complexity. Two popular tools, Mypy and Pyright, stand out as the go-to options. In this article, we will explore their features, differences, and strengths in detail.

Pexels

Introduction to Static Type Checking

Python’s dynamic typing makes it flexible but prone to runtime errors if types are misused. Static type checkers like Mypy and Pyright mitigate this by validating types before runtime, ensuring:

• Errors are caught during development.
• Code is easier to understand and maintain.
• Developers benefit from better IDE support, including autocompletion and refactoring tools.

By combining Python’s type hints (PEP 484) with these tools, you can enforce strict type safety without sacrificing Python's simplicity.

Overview: Mypy and Pyright

Mypy

• Developed by the Python community.
• The oldest and most widely adopted type checker.
• Works closely with PEP 484 and integrates seamlessly into Python workflows.
• Configurable via mypy.ini or pyproject.toml.
• Written in Python.

Pyright

• Developed by Microsoft.
• Written in TypeScript, making it extremely fast.
• Features advanced type narrowing and inference capabilities.
• Supports real-time feedback with a watch mode.
• Configurable via **pyrightconfig.json or `pyproject.toml`**.

Installation and Setup

Mypy Installation

Install Mypy via pip:

pip install mypy

Run Mypy on a file:

mypy script.py

Pyright Installation

Install Pyright using npm or pipx:

npm install -g pyright

Run Pyright on a file:

pyright script.py

Configuring Mypy

Mypy configuration can be stored in mypy.ini or pyproject.toml.

Example pyproject.toml for Mypy:

[tool.mypy]
strict = true  # Enables all strict checks
ignore_missing_imports = true  # Ignore third-party libraries without stubs
warn_unused_configs = true
disallow_untyped_defs = true  # Require type hints for all functions

Configuring Pyright

Pyright traditionally uses pyrightconfig.json, but it can also be configured via pyproject.toml starting from recent versions. This makes it easier to centralize configuration.

Pyright Configuration in pyproject.toml

To configure Pyright using pyproject.toml:

[tool.pyright]
include = ["src"]          # Directories to include
exclude = ["tests", "build"]
reportMissingImports = true  # Report missing type stubs
reportUnusedVariable = true  # Warn about unused variables
strict = true               # Enable strict type checking
pythonVersion = "3.10"      # Target Python version

This setup mirrors the JSON-based pyrightconfig.json and brings Pyright in line with other modern tools that use pyproject.toml.

Equivalent pyrightconfig.json Example:

{
  "include": ["src"],
  "exclude": ["tests", "build"],
  "reportMissingImports": true,
  "reportUnusedVariable": true,
  "strict": true,
  "pythonVersion": "3.10"
}

Both configurations achieve the same result.

Advanced Configuration Examples

1. Per-File and Per-Directory Configurations

Both tools allow for fine-grained control over specific files and directories.

Mypy Example (pyproject.toml):

[tool.mypy]
strict = true

[[tool.mypy.overrides]]
module = "tests.*"
ignore_missing_imports = true  # Ignore missing imports in tests
disallow_untyped_defs = false  # Allow untyped functions in tests

Pyright Example (pyproject.toml):

[tool.pyright]
include = ["src"]

[[tool.pyright.overrides]]
path = "tests/*"
reportMissingImports = false
strict = false

Here:

• Mypy and Pyright apply less strict rules to test files.
• Overrides are useful for excluding generated code, third-party stubs, or specific directories.

2. Type Narrowing and Inference

Both tools support type narrowing, where types are refined based on conditions, but Pyright does this more precisely.

Example Code:

def process(value: int | str) -> None:
    if isinstance(value, int):
        print(value + 10)  # Narrowed to int
    else:
        print(value.upper())  # Narrowed to str

• Mypy: Handles basic narrowing.
• Pyright: Handles more complex logical conditions and ensures precise narrowing.

3. Ignoring Errors Inline

Both tools allow inline comments to suppress errors.

Mypy Inline Ignore:

def greet(name: str) -> None:
    print("Hello, " + name)  # type: ignore

Pyright Inline Ignore:

def greet(name: str) -> None:
    print("Hello, " + name)  # pyright: ignore

4. Performance Optimization

For large codebases, Pyright’s speed is a significant advantage.

Pyright Watch Mode:

Pyright includes a watch mode for real-time type checking:

pyright --watch

This updates the type-checking results instantly as you edit files, making development smoother.

Mypy Incremental Mode:

Mypy supports incremental mode for faster checks:

mypy --incremental

5. Strict Mode

Strict mode enables all available checks for type safety.

Mypy:

[tool.mypy]
strict = true

Pyright:

[tool.pyright]
strict = true

Both tools ensure that:

• All functions have type annotations.
• Implicit Any types are disallowed.
• Code meets the highest standards for type safety.

Key Differences Summary

@source own

Choosing Between Mypy and Pyright

When to Choose Mypy:

• If you already use Mypy in your project.
• If your team prefers a tool deeply rooted in the Python community.
• For projects with legacy Python codebases.

When to Choose Pyright:

• If performance is critical (e.g., large projects).
• If you use VSCode (Pyright powers Pylance, the fastest type-checking experience).
• For modern projects that need advanced type inference and narrowing.

In Plain English 🚀

Thank you for being a part of the **In Plain English** community! Before you go:

• Be sure to clap and follow the writer ️👏️️
• Follow us: **X | [LinkedIn](https://www.linkedin.com/company/inplainenglish/) | [YouTube](https://www.youtube.com/channel/UCtipWUghju290NWcn8jhyAw) | [Discord](https://discord.gg/in-plain-english-709094664682340443) | [Newsletter](https://newsletter.plainenglish.io/) | [Podcast](https://open.spotify.com/show/7qxylRWKhvZwMz2WuEoua0)**
• **Create a free AI-powered blog on Differ.**
• More content at **PlainEnglish.io**
• Have a story to share? **Join our global community of writers today!**