Pyrefly: Python Type Checker by Meta

Pyrefly is a static type checker and language server for Python, developed by Meta. It performs static analysis on Python code to identify type-related issues before runtime and provides IDE features like code navigation, autocompletion, and semantic highlighting.

Pyrefly is a clean-slate implementation inspired by Meta’s earlier Pyre type checker. It uses a new type inference engine, a custom incremental computation model, and multi-threaded parallel checking.

When to use Pyrefly

Pyrefly is the handbook’s recommended type checker for new Python projects. Its native configuration enables inference in unannotated function bodies and return types, and its language server provides the same checker in editors and CI. Framework support includes Pydantic, Django, attrs, and PyTorch. Google uses Pyrefly across its Python monorepo.

A bare pyrefly check can use a quieter configuration: without a native Pyrefly configuration, it migrates nearby mypy or pyright settings in memory, or falls back to the basic preset. Run pyrefly init to establish the project’s configuration before evaluating its diagnostics.

For a comparison of all major type checkers, see How do mypy, pyright, and ty compare?.

Key Features

• Type inference: with the default preset, infers variable and return types and checks unannotated function bodies. The basic and legacy presets disable checking of unannotated definitions and return-type inference.
• Flow types: refines static types through control flow analysis, narrowing types after guards and checks.
• Framework support: built-in handling for Pydantic, Django, and attrs patterns, with framework-specific limits documented by the project.
• Tensor shape types (experimental): tracks PyTorch tensor dimensions through Int[N] and Tensor[[B, S]] annotations and surfaces inferred shapes as IDE inlay hints. See the Pyrefly tensor shapes tutorial.
• Auto-annotation tool: pyrefly infer writes type annotations directly into source files for parameters, return types, container element types, and the imports they require. See how to add type annotations with pyrefly infer.
• Module-level incrementality: rechecks only modules that changed, with optimized parallel checking across available cores.
• Language server: full LSP implementation with code navigation, semantic highlighting, code completion, inline documentation, workspace-wide symbol search, and cross-file references and hierarchies. Change Signature updates a function and its call sites together. Quick fixes remove unused imports or insert assertions to narrow optional values.
• Auto-migration: pyrefly init converts supported mypy or pyright settings into Pyrefly configuration. When checking files without a governing Pyrefly configuration, Pyrefly can migrate existing checker settings in memory.
• Targeted suppressions: # type: ignore[pyrefly:<code>] suppresses one Pyrefly diagnostic without hiding unrelated diagnostics on the same line.
• Adoption tooling: pyrefly coverage report emits annotation-completeness metrics as JSON, pyrefly coverage check --fail-under enforces a coverage threshold as a CI gate, and baseline files (experimental) snapshot existing errors so only new ones are surfaced.
• CI output: --output-format junit-xml writes diagnostics in the JUnit XML format that Jenkins, GitHub Actions, and GitLab CI parse for test reporting.

Pros

• Native project configuration enables inference that catches bugs in unannotated code
• pyrefly init auto-migrates existing mypy or pyright configuration
• Stable CLI and language-server releases
• Cross-platform: macOS, Linux, and Windows (including ARM64)
• MIT licensed

Cons

• Configuration migration preserves only supported settings; diagnostics and inference differ from mypy and pyright
• Tensor-shape checking for PyTorch is still experimental

Installation and Usage

# Install with pip or uv
pip install pyrefly
uv pip install pyrefly

# Initialize configuration
pyrefly init

# Check a project
pyrefly check

# Run without installing
uvx pyrefly check

Pyrefly discovers pyrefly.toml or [tool.pyrefly] in pyproject.toml by searching parent directories. An explicit --config selects a configuration file. pyrefly init generates a starter configuration and migrates supported settings from an existing mypy or pyright configuration. See the configuration discovery rules.

Pyrefly publishes prebuilt wheels for macOS, Linux, and Windows, including musllinux wheels for Alpine and other musl-based containers.

To add Pyrefly as a development dependency in a uv project:

uv add --dev pyrefly
uv run pyrefly check

To bootstrap annotations on an existing codebase, pyrefly infer writes annotations into source files using static analysis:

uv run pyrefly infer src/

See how to add type annotations with pyrefly infer for the full workflow.

Configuration Presets

Pyrefly groups error severities and behavior settings into named presets. The active preset is selected with preset = "..." in pyrefly.toml or [tool.pyrefly]. From the configuration docs:

• off: silences every error kind. Useful for IDE-only users or projects that want to opt in to specific checks manually.
• basic: low-noise, high-confidence diagnostics only (syntax errors, missing imports, unknown names). Applied automatically when no Pyrefly config or migratable mypy/pyright config is found, or migration fails.
• legacy: preserves selected mypy defaults, including skipping unannotated definitions, disabling return-type inference, treating untyped imports as Any, and honoring mypy-coded ignores as blanket suppressions. It also disables three override/name checks. pyrefly init selects it when migrating mypy configuration.
• default: the standard Pyrefly experience. Equivalent to specifying no preset.
• strict: enables additional checks for implicit Any, override decorators, unused ignores, and other stricter policies on top of default, plus stricter callable subtyping.
• all: enables every check, the strictest available setting.

Editor Integration

• VS Code: install the Pyrefly extension from the VS Code Marketplace or Open VSX.
• Neovim: supported through LSP configuration.
• Zed: supported through built-in LSP integration.

For other editors, Pyrefly’s language server speaks LSP and can be used with any compatible client.

Pyrefly also runs as a Pylance backend through the Type Server Protocol (TSP), available to all VS Code users. Select Pylance + Pyrefly in Pylance’s Diagnostics Source setting to retain Pylance features with Pyrefly analysis. The Pyrefly team recommends the standalone extension for most users; the Pylance integration suits teams that need Pylance or its Copilot integration. See the Pyrefly integration announcement and Microsoft setup requirements.

Complementary Tools

Pyrefly ships with three tools that support adoption in existing codebases:

• pyrefly coverage report: emits a JSON report with annotation-completeness and type-completeness metrics per function, class, and module, plus aggregate summary statistics. Pipe output to jq .summary.strict_coverage to extract a single metric for dashboards or CI logging.
• pyrefly coverage check: exits non-zero when coverage falls below the threshold passed to --fail-under. Use as a CI gate to enforce minimum coverage on every pull request.
• Baseline files (experimental): snapshot the current set of errors to a JSON file (typically baseline.json) using pyrefly check --baseline=<path> --update-baseline. Subsequent runs report only errors not present in the baseline, as an alternative to inline suppression comments. Baselines can match by concise description to reduce churn when code moves. Use --prune-baseline to remove stale entries and --error-stale-baseline to reject them in CI. Suppressed errors remain visible in the IDE. baseline-error-level sets their CLI severity; --min-severity controls whether they are displayed and cause a nonzero exit.

Comparison to Other Tools

Pyrefly’s configuration migration is a starting point, rather than a promise of identical diagnostics to mypy or pyright. In its default preset, Pyrefly infers unannotated return types that ty represents as Unknown by default; ty offers opt-in return-type inference. Compare representative project code and required framework behavior before switching checkers.

Suppressions and Exit Codes

Use # pyrefly: ignore[bad-assignment] or # type: ignore[pyrefly:bad-assignment] for a targeted assignment suppression. Bare # type: ignore suppresses the line. Foreign codes can also suppress more broadly depending on type-ignore-unknown-tag-behavior; migrations should review existing ignores. See suppression configuration.

pyrefly check exits with 0 when no diagnostics meet its min-severity threshold and 1 when they do. The threshold defaults to error; --min-severity warn also displays warnings and makes them fail the check. Invalid command-line arguments exit with 2.