Pyrefly: A Fast Static Type Checker for Python Projects

Pyrefly is a fast static type checker for Python that helps you catch type-related issues before running your code. It also includes features for generating type hints and measuring type coverage across a codebase.

In this tutorial, you’ll use Pyrefly to catch type errors, add type hints to existing code, track your project’s type coverage, and see how its speed compares. You’ll get the most out of it if you’re comfortable writing functions and adding basic type hints in Python 3.10 or later. The table below gives you a quick comparison with two popular alternatives, Pyright and mypy:

The table highlights where the Pyrefly CLI goes beyond other tools: it can generate type hints and measure coverage, and it’s built to be very fast. The coverage comparison needs context: Pyright’s --verifytypes checks a package’s public interface, while mypy’s reporting flags can summarize how much of your code has type hints.

Take the Quiz: Test your knowledge with our interactive “Pyrefly: A Fast Static Type Checker for Python Projects” quiz. You’ll receive a score upon completion to help you track your learning progress:

---

Interactive Quiz

Pyrefly: A Fast Static Type Checker for Python Projects

Test your understanding of Pyrefly, a fast Python type checker, from catching type errors to generating type hints and measuring type coverage.

Get Started With Pyrefly

Pyrefly is available on PyPI. To follow along, first create and activate a virtual environment, then install Pyrefly with pip:

$ mkdir pyrefly-demo $ cd pyrefly-demo $ python -m venv .venv $ source .venv/bin/activate (.venv) $ python -m pip install pyrefly==1.2.0 

Note that on Windows, you’ll need to activate the environment with .venv\Scripts\activate instead.

One of the quickest ways to try Pyrefly is with pyrefly snippet, which type-checks a short piece of Python code without creating a file. The following snippet hints x as a string but assigns it an integer:

(.venv) $ pyrefly snippet "x: str = 1" ERROR `Literal[1]` is not assignable to `str` [bad-assignment]  --> snippet:1:10  | 1 | x: str = 1  | --- ^  | |  | declared type  |  INFO 1 error 

Pyrefly reports an error because the variable x is hinted as str, but the assigned value is an int. The error shows it as Literal[1], the most specific type Pyrefly can infer for 1. Assigning a value of the correct type removes the error:

(.venv) $ pyrefly snippet 'x: str = "Hello, World!"'  INFO 0 errors 

Like other type-checking tools, Pyrefly checks your code against its type hints without executing it. As your projects grow, this can help you catch type-related issues before they become runtime bugs.

In addition to being a command-line tool for type-checking your code, Pyrefly includes a language server for editor integration. This tutorial focuses on the command-line workflow, but you can find setup instructions for popular editors in the official documentation.

Catch Type Errors in a Python Project Before Execution

While pyrefly snippet is useful for quickly checking a small piece of code, most type checking happens across modules, packages, and even entire projects. You can use Pyrefly to analyze Python files in a codebase with pyrefly check.

First, initialize Pyrefly in your project folder. The --non-interactive flag accepts the default settings instead of prompting you for each one:

(.venv) $ pyrefly init --non-interactive  INFO New config written to `.../pyrefly.toml`  INFO Running pyrefly check...  ... 

The command creates a pyrefly.toml configuration file that instructs Pyrefly to check all Python files and Jupyter notebooks in the current project. You may also notice that pyrefly init automatically runs a type check after creating the configuration file. Since the folder doesn’t contain any Python files yet, this first check has nothing to report, so instead, focus on the configuration file that pyrefly init creates.

Here’s what that file may look like: