Skip to main content

Installation

Pyrefly is available on PyPI with a new release every Monday. We often release more frequently when shipping new features and bug fixes.

Install​

You can use uv, poetry, pip, pixi or conda to install Pyrefly. The following commands show you how to install Pyrefly and run 2 basic commands: init and check.

  • pyrefly init will update your pyproject.toml file (or create a pyrefly.toml file) in your project directory, including some basic configuration. It will also attempt to migrate your existing type checker configuration.
  • pyrefly check --summarize-errors will run the Pyrefly type checker on your project, providing a list of type errors and a summary of error types. The --summarize-errors flag is optional, remove it if you don't want summary stats.

Simply cd into your project directory and run:

pip install pyrefly
pyrefly init
pyrefly check --summarize-errors

Configure​

You can set up a basic configuration file to type-check your project. You can add configuration options to a pyproject.toml file or create a pyrefly.toml file in your project directory. All configuration options are documented here.

[tool.pyrefly]
search_path = [
    "example_directory/..."
]

Then, run pyrefly check again, and the tool will use your configuration options.

The tool may return a list of type errors; this is perfectly normal. You have a few options at this point:

  1. Use # pyrefly: ignore comments to silence the errors. This will get your project to a clean type-checking state, and you can reduce the number of errors as you go. We've included a script that can do this for you:
pyrefly check --suppress-errors
  1. Use extra configuration options to silence specific categories of errors or exclude files with more errors than average.

Upgrading Pyrefly​

Upgrading the version of Pyrefly you're using or a third-party library you depend on can reveal new type errors in your code. Fixing them all at once is often unrealistic. We've written scripts to help you temporarily silence them.

# Step 1
pyrefly check --suppress-errors
# Step 2
<run your formatter of choice>
# Step 3
pyrefly check --remove-unused-ignores

Repeat these steps until you achieve a clean formatting run and a clean type check.

This will add # pyrefly: ignore comments to your code, enabling you to silence errors and return to fix them later. This can make the process of upgrading a large codebase much more manageable.

Add Pyrefly to CI​

After your project passes type checks without errors, you can prevent new bugs from being introduced. Enforce this through CI (Continuous Integration) to prevent other maintainers from merging code with errors. Here is an example for GitHub.

Save your workflow in the following path within your repository:

.github/workflows/typecheck.yml

GitHub automatically detects .yml files within .github/workflows/ and sets up the defined workflows.

name: Pyrefly Type Check

on:
  pull_request:
    branches: [main]
  workflow_dispatch:  # Allows manual triggering from the GitHub UI

jobs:
  typecheck:
    runs-on: ubuntu-latest

    steps:
      - name: Check out code
        uses: actions/checkout@v4

      - name: Set up Python
        uses: actions/setup-python@v5

      # Install Python dependencies and create environment
      - name: Install dependencies and run type checking
        run: |
          python -m venv .venv
          source .venv/bin/activate
          python -m pip install --upgrade pip
          # Install your dependencies; adjust the following lines as needed
          pip install -r requirements-dev.txt

      - name: Install Pyrefly
        run: pip install pyrefly

      - name: Run Pyrefly Type Checker
        run: pyrefly check

A few notes about this setup:​

  • Building your environment and installing dependencies will enhance type safety by checking the types of imports. This is not required, but encouraged!
  • Simply drop in pyrefly check to existing workflows that build and test your environment.
      - name: Run Pyrefly Type Checker
        run: pyrefly check
  • Your pyrefly.toml or Pyrefly configs in your pyproject.toml will be automatically detected. Learn how to configure Pyrefly here.

Pre-commit​

Pyrefly provides a pre-commit hook so you can automatically type check files before they are committed.

We maintain a dedicated repository for this integration here: facebook/pyrefly-pre-commit

That repository contains:

  • Two pre-commit hooks depending on your setup
  • Installation instructions
  • Example configuration snippets for your project and CI

To get started, follow the setup steps in the repo’s README.

Install pre-commit​

You only need to do this once per clone. You can also include this in your as script or in your build/setup commands like setup.py or setup.cfg so it's installed for everyone.

# 1. Once per clone
pip install pre-commit          # or pipx install pre‑commit
pre-commit install              # writes .git/hooks/pre-commit

# 2. Upgrade hooks when you bump versions in YAML
pre-commit autoupdate

# 3. Manual full run (good before the first push or when you add the hook)
pre-commit run --all-files

Testing the hook​

1. Introduce a cheap error

Edit any .py file and deliberately return None where the function is annotated to return int.

def foo() -> int:
    return None

2. Stage & commit

Output:

git add test.py
git commit -m "test: pre‑commit hook check"
pyrefly check............................................................Failed
- hook id: pyrefly-typecheck-system
- exit code: 1

 INFO Checking project configured at `/myproject/pyrefly.toml`
ERROR /myproject/test.py:2:12-16: Returned type `None` is not assignable to declared return type `int` [bad-return]

You should see Pyrefly fail as above, preventing the commit from being created.

3. Fix & recommit

Correct the code, git add it again, and re‑run git commit; this time the hook passes.

How this helps your project​

  • Earlier feedback: Developers see type mistakes immediately, not minutes later in CI.
  • Consistent enforcement: Every commit—local or on CI—runs the same pyrefly check command.
  • Clean history: Because Pyrefly checks before the commit object is created, you avoid "fix type error" fix‑up commits.
  • Culture of quality: Blocking problems at the doorstep raises the baseline for new contributors.