Pyright vs Mypy: Learn Static Type Checking in Python

Last Updated on 6 May 2025

Python is known for simple and flexible programming language. But this flexibility can sometimes lead to bugs that are only caught when the program runs. That’s where static type checkers like Pyright and Mypy come in.

In this tutorial, we’ll learn:

• What is Pyright
• What is static type checking
• How to install and use Pyright
• Practical examples of static type checking
• Key differences between Pyright and Mypy
• When to use each one

The interesting part is that the use cases of both Pyright and Mypy are the same. At the end, you will also have an understanding of Mypy.

What is a Static Type Checker?

A static type checker is a tool that analyzes code without running it. It looks at the type hints in the code and warns if something doesn’t match.

Here’s an example:

def add(a: int, b: int) -> int:
    return a + b

add(5, "hello")

add(5, "hello")This line will cause an error.

Python will only raise an error at runtime. However, with Pyright or Mypy, you can catch that mistake before running the code.

What is Pyright?

Pyright is a modern static type checker for Python developed by Microsoft, written in TypeScript. It does the following:

• Tells if a function gets the wrong kind of data
• Checks if a function returns the wrong type
• Warns about missing None checks
• Works with large projects quickly

It’s like having a smart assistant that catches bugs before they happen.

Installation

You can install Pyright using npm (Node.js must be installed):

npm install -g pyright

If you’re confused about npm, don’t worry. Check this guide on how to download and install Node.js and npm.

This is how to check a Python file with Pyright:

pyright your_file.py

A Practical Example

Let’s see an example:

def greet(name: str) -> str:
    return "Hello " + name

greet(123)  # Type mismatch!

In the above code, we declared the parameter name as a string data type, but when calling the function, we’re passing an integer value to it. Generally, the program will raise an error at runtime.

pyright greet.py

Output

Argument of type "int" cannot be assigned to parameter "name" of type "str"

Congrats! You just caught a bug without even running your code!

Real Use Case: Catching Bugs in Large Codebases

Imagine you’re working on a big project with multiple developers. You may not know what types of values are being passed between functions.

If you use Pyright, you can:

• Detect incorrect usage early
• Avoid runtime crashes
• Make your code easier to understand for teammates

Example:

from typing import List, Dict, Optional

def square_numbers(nums: List[int]) -> List[int]:
    return [n * n for n in nums]

def get_user(id: int) -> Optional[Dict[str, str]]:
    users = {
        1: {"name": "Alice", "email": "a@example.com"},
        2: {"name": "Bob", "email": "b@example.com"}
    }
    return users.get(id)

Pyright will alert if you break these contracts. If someone calls these functions incorrectly, Pyright will raise a warning or error.

Let’s say you change get_user to return the wrong type.

def get_user(id: int) -> Optional[Dict[str, str]]:
    return {"id": 123, "username": "admin"}  # Problem: 123 is an int, not str!

Pyright will warn:

Expression of type "Dict[str, int]" cannot be assigned to return type "Optional[Dict[str, str]]"

Setting Up Pyright in a Project

If you’re working on a Python project and want to use Pyright to catch type errors, you can set it up just once for the whole project. To do that, you need to create a config file called pyrightconfig.json.

This file tells Pyright where your code is, what rules to follow, and how strict it should be.

Steps:

Create a file called pyrightconfig.json and put it in the main folder of your Python project. Now, paste the following code inside the file:

{
  "include": ["."],
  "exclude": ["**/venv"],
  "strict": true
}

What Do These Lines Mean?

• "include": ["."], – tells Pyright to check all Python files in the current folder
• "exclude": ["**/venv"] – Skip checking your virtual environment folder
• "strict": true – turn on strict mode – Pyright will catch more issues (like mypy’s –strict)

Example File Structure

my-project/
├── main.py
├── utils.py
├── pyrightconfig.json
└── venv/                ← (ignored by Pyright)

Now, when you run:

pyright

Pyright will:

• Use the config
• Check only your code (skip venv)
• Be more strict and helpful!

Installing and Using Mypy

mypy is a static type checker for Python, just like Pyright. It checks your code for type-related errors without running it. This helps catch bugs early (before run time) and makes your code more reliable and readable.

How to Install Mypy

You can install Mypy using pip:

pip install mypy

Once installed, you can run it on any Python file:

mypy your_file.py

It will check your type hints and show errors if something doesn’t match.

Is Mypy the Same as Pyright?

Not exactly, but they do the same job. It checks if your code follows the type hints you wrote using Python’s typing module.

Both tools will catch errors like:

• Passing a string when an int was expected
• Returning the wrong type from a function
• Forgetting to check for None in optional types

So, if you understand how Pyright works, using Mypy will feel very familiar!

Pyright vs Mypy

Feature	Pyright	Mypy
Speed	Very Fast	Slower on large projects
Developed By	Microsoft	Open Source Community
Written In	Typescript	Python
Config File	pyrightconfig.json	mypy.ini or setup.cfg
Editor Integration	Excellent in VS Code (Pylance)	Good with various editors
Type Inference	Advanced and smart	Conservative
Type Checking	Deep + handles edge cases well	Reliable but less aggressive

Which One Should You Use?

• If you’re using VS Code, Pyright (via Pylance) offers the best real-time experience.
• If you’re working in a more traditional setup or need mature ecosystem support, Mypy is a good choice.
• Some large projects use both during development and CI pipelines.

But for most users today, Pyright is enough, especially if you work with VS Code and want a modern experience.

Final Thought

Python doesn’t force you to use types, but if you add them and use Pyright, it helps a lot. It’s like having a spelling checker, but for your code. It finds mistakes before you even run the program.

If you found this article helpful, check this out also to find more similar topics: Comprehensive Tutorials.