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:

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

2. 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.