Pyrefly Configuration Options: Complete Guide to Setup and mypy/pyright Migration

Pyrefly discovers settings from pyrefly.toml, [tool.pyrefly] in pyproject.toml, or synthesizes configuration by migrating mypy.ini and pyrightconfig.json files into the ConfigFile struct defined in crates/pyrefly_config/src/config.rs.

The facebook/pyrefly type checker provides comprehensive Pyrefly configuration options that control project discovery, import resolution, error reporting, and Python environment detection. Understanding how Pyrefly structures its configuration—and how it interoperates with existing mypy or pyright setups—is essential for effective static analysis in large codebases.

Configuration Discovery and File Locations

Pyrefly searches for configuration in the following priority order:

1. A dedicated pyrefly.toml file in the project root
2. A [tool.pyrefly] table within pyproject.toml
3. Synthesized configuration migrated from nearby mypy.ini or pyrightconfig.json files when no Pyrefly-specific config exists

The configuration is represented internally by the ConfigFile struct in crates/pyrefly_config/src/config.rs. This struct contains all top-level options, including project globs, search paths, interpreter settings, and per-module overrides.

Core Configuration Options

Project Discovery and File Inclusion

• project_includes: Glob patterns selecting source files (defaults to **/*.py* and **/*.ipynb). Defined as project_includes: Globs in the ConfigFile struct.
• project_excludes: Glob patterns excluding files such as **/__pycache__ or **/venv/**.
• disable_project_excludes_heuristics: When set to true, Pyrefly does not automatically add the site-package directory to the exclude list.
• extra_file_extensions: Additional file extensions to treat as Python source (e.g., .pyi, .pyx).

Import Resolution and Search Paths

• search_path_from_file: Explicit import search paths defined in the configuration file (Vec<PathBuf>).
• search_path_from_args: Import paths supplied via the command line using --search-path (CLI only).
• import_root: Heuristic root derived from project layout (src/, flat, or parent) when disable_search_path_heuristics is false.
• fallback_search_path: Fallback import path used when the heuristic import root is insufficient, such as for loose files.
• disable_search_path_heuristics: If true, Pyrefly uses only explicit search_path entries and never adds the inferred import root.
• typeshed_path: Path to a custom typeshed directory for stub files.

Python Environment and Interpreters

The interpreters field (flattened in ConfigFile) contains:

• python_interpreter_path: Path to the Python executable.
• fallback_python_interpreter_name: Alternative interpreter name for discovery when the primary is unavailable.
• conda_environment: Conda environment name for dependency resolution.
• skip_interpreter_query: Boolean flag to skip interpreter detection entirely.

The python_environment field holds the detected Python version, platform, and site-package paths, populated automatically after interpreter discovery.

Error Reporting and Output

• output_format: Output style selection, including min-text, full-text (default), json, github, or omit-errors.
• min_severity: Minimum severity level to display (defaults to "error").
• baseline: Path to a baseline file that suppresses matching errors across runs.

Configuration Presets and Overrides

• preset: Named preset (Default, Legacy, Basic, etc.) supplying default error severities and behavior. When migrating from mypy, this becomes Legacy; from pyright, Default.
• root: Global configuration values (ConfigBase) including errors, check_unannotated_defs, infer_return_types, and tensor_shapes.
• sub_configs: Per-module overrides as Vec<SubConfig>, where each entry contains a matches glob and a ConfigBase with the same fields as the root.

Miscellaneous Options

• use_ignore_files: When true, Pyrefly respects .gitignore, .ignore, and .git/exclude patterns.
• build_system: Selects the build system integration (e.g., buck, cargo, custom).
• skip_lsp_config_indexing: Disables configuration indexing in LSP mode, useful for large workspaces to improve performance.

Migrating from mypy and pyright Configurations

When no pyrefly.toml or [tool.pyrefly] section exists, Pyrefly automatically synthesizes configuration by migrating settings from existing type checker configurations. This migration populates the synthesized_preset_reason field with Migrated(MigratedFromKind::Mypy) or Migrated(MigratedFromKind::Pyright).

Migrating from mypy.ini

Pyrefly scans mypy.ini for sections starting with mypy-. The suffix after the prefix is treated as a module pattern where dots convert to directory separators (a.b becomes a/b) and * becomes **.

Settings such as disable_error_code and enable_error_code are parsed into an ErrorDisplayConfig and stored in the errors field of the corresponding SubConfig. Each mypy section becomes a SubConfig entry in the sub_configs vector. If at least one per-module section is found, the top-level preset is set to Legacy. The implementation resides in crates/pyrefly_config/src/migration/sub_configs.rs.

Migrating from pyrightconfig.json

Pyrefly parses pyrightconfig.json into a PyrightConfig struct defined in crates/pyrefly_config/src/migration/pyright.rs. Each entry in the executionEnvironments array becomes a SubConfig where:

• The root path becomes the matches glob pattern
• Rule overrides (e.g., reportMissingImports: "ignore") convert to severity levels in the errors field

When a non-empty executionEnvironments list is present, the top-level preset becomes Default with the migration reason recorded as Migrated(MigratedFromKind::Pyright).

Configuration Precedence and Override Behavior

Migration runs before the final configure() step that merges the preset with user settings. Any setting explicitly defined in pyrefly.toml or the [tool.pyrefly] section takes precedence over migrated values. User-supplied sub_configs entries override automatically generated ones from mypy or pyright per-module sections, ensuring that explicit configuration always wins.

Example pyrefly.toml Configuration

# pyrefly.toml

[tool.pyrefly]

# Global options

project-includes = ["src/**/*.py"]
project-excludes = ["src/**/__pycache__"]
output-format = "json"

# Choose a preset explicitly (overrides any auto-detected preset)

preset = "basic"

# Per-module overrides

[[tool.pyrefly.sub-config]]
matches = "src/**/models"
[tool.pyrefly.sub-config.errors]

# Disable the "union-attr" error only for this package

disable = ["union-attr"]

If a mypy.ini existed in the same directory with the following content:

[mypy-app.models]
disable_error_code = union-attr

Pyrefly would automatically generate an equivalent sub-config entry (as shown above) unless the user already supplied the sub-config in pyrefly.toml; the explicit user entry takes precedence.

Key Source Files

• crates/pyrefly_config/src/config.rs: Defines the ConfigFile struct and all top-level configuration fields.
• crates/pyrefly_config/src/base.rs: Defines ConfigBase, which contains global settings like errors, check_unannotated_defs, and infer_return_types.
• crates/pyrefly_config/src/migration/sub_configs.rs: Logic for converting mypy sections and pyright execution environments into SubConfig entries.
• crates/pyrefly_config/src/migration/pyright.rs: Parsing of pyrightconfig.json and conversion of rule overrides to Pyrefly severity levels.

Summary

• Pyrefly reads configuration from pyrefly.toml, [tool.pyrefly] in pyproject.toml, or automatically migrates from mypy.ini/pyrightconfig.json when no native config exists.
• The ConfigFile struct in crates/pyrefly_config/src/config.rs contains all Pyrefly configuration options, including project discovery globs, search paths, interpreter settings, and error reporting formats.
• Migration from mypy creates a Legacy preset with mypy-* sections converted to SubConfig entries using glob patterns.
• Migration from pyright creates a Default preset with executionEnvironments mapped to SubConfig entries.
• Explicit user configuration in pyrefly.toml always overrides migrated settings from other type checkers.

Frequently Asked Questions

Does Pyrefly automatically detect my existing mypy configuration?

Yes. If no pyrefly.toml or [tool.pyrefly] section is present, Pyrefly automatically scans for mypy.ini and migrates per-module sections (such as [mypy-app.models]) into equivalent sub_configs. The migration logic in crates/pyrefly_config/src/migration/sub_configs.rs converts module dot-notation to directory glob patterns and maps mypy error codes to Pyrefly's severity system.

What happens if I have both pyrefly.toml and mypy.ini?

Pyrefly prioritizes explicit configuration. If pyrefly.toml or a [tool.pyrefly] table exists, Pyrefly uses those settings exclusively and does not migrate from mypy.ini or pyrightconfig.json. User-defined values in pyrefly.toml always take precedence over any synthesized configuration that would have been generated from other tools.

How do I convert mypy per-module settings to Pyrefly?

In pyrefly.toml, use the [[tool.pyrefly.sub-config]] array to define per-module overrides. Set matches to a glob pattern corresponding to the module path (e.g., "src/**/models" for mypy-src.models) and configure the [tool.pyrefly.sub-config.errors] table to enable or disable specific error codes. This provides the same granularity as mypy's per-module disable_error_code directives.

Can I use pyproject.toml instead of pyrefly.toml?

Yes. Pyrefly fully supports a [tool.pyrefly] table within pyproject.toml using the same key structure and nesting as a dedicated pyrefly.toml file. This allows you to consolidate tool configuration in a single file, which is particularly useful for Python projects already using pyproject.toml for build system and dependency management.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}