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 the package if you want to experiment with our tool.

Simply cd into your project directory and run:

Using UV

uvx pyrefly init
uvx pyrefly check

This will install Pyrefly using UV, migrate your existing type checker configuration, and run the Pyrefly type checker.

Using Poetry

poetry add --group dev pyrefly
poetry run pyrefly init
poetry run pyrefly check

Using Pip

pip install pyrefly
pyrefly init
pyrefly check

Using Pixi

pixi add pyrefly
pixi run pyrefly init
pixi run pyrefly check

Using Conda

conda install -c conda-forge pyrefly
pyrefly init
pyrefly check

Configure

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:

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

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 Integration

Pyrefly is fast! This means you can run it before every commit to get immediate feedback on type errors without slowing down your workflow. Pre-commit let's you do this automatically.

⚠️ Warning: pyrefly check must be installed and available on your path in CI or locally.

Quick‑start

Add this to your .pre-commit-config.yaml:

- repo: https://github.com/facebook/pyrefly
  rev: main
  hooks:
    - id: pyrefly-typecheck

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

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

Stage & commit

Output:

git add test.py
git commit -m "test: pre‑commit hook check"
pyrefly check............................................................Failed
- hook id: pyrefly-typecheck
- 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.

Fix & recommit

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

CI parity (optional)

Add this to your GitHub Action so the exact same hook set runs server‑side. This prevents anyone from pushing with --no‑verify. Note that you still need pyrefly installed and available on your path. We plan to create a standalone pre-commit project in the future.

# You can skip this if you already have pyrefly installed
- name: Install pyrefly
run: |
    python -m venv .venv
    source .venv/bin/activate
    python -m pip install --upgrade pip
    pip install pyrefly
    # persists the venv’s scripts dir
    echo "$GITHUB_WORKSPACE/.venv/bin" >> "$GITHUB_PATH"

- uses: pre-commit/action@v3.0.1
  with:
    extra_args: --all-files

Most likely you'll have some dependencies installed already, but you can pip install pyrefly directly using the yaml snippet above.

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.

Install​

Using UV​

Using Poetry​

Using Pip​

Using Pixi​

Using Conda​

Configure​

Upgrading Pyrefly​

Add Pyrefly to CI​

A few notes about this setup:​