Migrating to Pyrefly

Pyrefly is designed to be adopted incrementally. You can install it beside your current checker, keep both in CI, and drop the old one once the team has accepted the differences.

Still deciding? Mypy vs Pyright vs Pyrefly covers the comparison.

Pick your starting point

• Migrate from mypy for a project configured with mypy.ini, setup.cfg, or [tool.mypy].
• Migrate from Pyright for a project configured with pyrightconfig.json or [tool.pyright], including Pylance users.

Both guides follow the same shape: install Pyrefly and convert the config, check the mapping is faithful, then handle the remaining errors and drop your old checker.

The short version

1. Install Pyrefly alongside your current checker:

   # uv
   uv add --dev pyrefly
   
   # pip
   python -m pip install pyrefly

2. Convert your existing mypy or Pyright config into a native Pyrefly one:

   pyrefly init

   Read the generated config before committing it. Not every setting has an exact Pyrefly equivalent, and unrecognized ones are skipped without a warning. The guides above cover what to check.

3. Type check with the config you just generated:

   pyrefly check

   Your existing config is left in place, so both checkers can keep working while you review the result.

4. Decide how to handle any new errors introduced by differing checker behavior. Pyrefly offers two ways to clear the signal without fixing everything up front:

   • Suppression comments silence errors inline with # pyrefly: ignore, and pyrefly suppress adds them across the project in bulk.
   • A baseline records the current errors in a file, so CI reports only newly introduced ones and your source stays untouched. This is useful if you are migrating a very large codebase.

5. When you're ready, remove your old type checker and any unused ignore comments.

Reference material

Each guide links to the detail it needs, and the full mappings are also available directly:

Coming from	Configuration	Diagnostics
mypy	Mypy config reference	Mypy error codes
Pyright	Pyright config reference	Pyright diagnostics

If config migration goes wrong for your project, please let us know.