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

> Explore Pyrefly configuration options in pyrefly.toml or pyproject.toml. Learn how Pyrefly migrates mypy and pyright settings for seamless setup and enhanced code analysis.

- Repository: [Meta/pyrefly](https://github.com/facebook/pyrefly)
- Tags: how-to-guide
- Published: 2026-05-21

---

**Pyrefly discovers settings from [`pyrefly.toml`](https://github.com/facebook/pyrefly/blob/main/pyrefly.toml), `[tool.pyrefly]` in [`pyproject.toml`](https://github.com/facebook/pyrefly/blob/main/pyproject.toml), or synthesizes configuration by migrating [`mypy.ini`](https://github.com/facebook/pyrefly/blob/main/mypy.ini) and [`pyrightconfig.json`](https://github.com/facebook/pyrefly/blob/main/pyrightconfig.json) files into the `ConfigFile` struct defined in [`crates/pyrefly_config/src/config.rs`](https://github.com/facebook/pyrefly/blob/main/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`](https://github.com/facebook/pyrefly/blob/main/pyrefly.toml) file in the project root
2. A `[tool.pyrefly]` table within [`pyproject.toml`](https://github.com/facebook/pyrefly/blob/main/pyproject.toml)
3. Synthesized configuration migrated from nearby [`mypy.ini`](https://github.com/facebook/pyrefly/blob/main/mypy.ini) or [`pyrightconfig.json`](https://github.com/facebook/pyrefly/blob/main/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`](https://github.com/facebook/pyrefly/blob/main/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`](https://github.com/facebook/pyrefly/blob/main/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`](https://github.com/facebook/pyrefly/blob/main/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`](https://github.com/facebook/pyrefly/blob/main/crates/pyrefly_config/src/migration/sub_configs.rs).

### Migrating from pyrightconfig.json

Pyrefly parses [`pyrightconfig.json`](https://github.com/facebook/pyrefly/blob/main/pyrightconfig.json) into a `PyrightConfig` struct defined in [`crates/pyrefly_config/src/migration/pyright.rs`](https://github.com/facebook/pyrefly/blob/main/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`](https://github.com/facebook/pyrefly/blob/main/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

```toml

# 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`](https://github.com/facebook/pyrefly/blob/main/mypy.ini) existed in the same directory with the following content:

```ini
[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`](https://github.com/facebook/pyrefly/blob/main/pyrefly.toml); the explicit user entry takes precedence.

## Key Source Files

- [`crates/pyrefly_config/src/config.rs`](https://github.com/facebook/pyrefly/blob/main/crates/pyrefly_config/src/config.rs): Defines the `ConfigFile` struct and all top-level configuration fields.
- [`crates/pyrefly_config/src/base.rs`](https://github.com/facebook/pyrefly/blob/main/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`](https://github.com/facebook/pyrefly/blob/main/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`](https://github.com/facebook/pyrefly/blob/main/crates/pyrefly_config/src/migration/pyright.rs): Parsing of [`pyrightconfig.json`](https://github.com/facebook/pyrefly/blob/main/pyrightconfig.json) and conversion of rule overrides to Pyrefly severity levels.

## Summary

- Pyrefly reads configuration from [`pyrefly.toml`](https://github.com/facebook/pyrefly/blob/main/pyrefly.toml), `[tool.pyrefly]` in [`pyproject.toml`](https://github.com/facebook/pyrefly/blob/main/pyproject.toml), or automatically migrates from [`mypy.ini`](https://github.com/facebook/pyrefly/blob/main/mypy.ini)/[`pyrightconfig.json`](https://github.com/facebook/pyrefly/blob/main/pyrightconfig.json) when no native config exists.
- The `ConfigFile` struct in [`crates/pyrefly_config/src/config.rs`](https://github.com/facebook/pyrefly/blob/main/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`](https://github.com/facebook/pyrefly/blob/main/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`](https://github.com/facebook/pyrefly/blob/main/pyrefly.toml) or `[tool.pyrefly]` section is present, Pyrefly automatically scans for [`mypy.ini`](https://github.com/facebook/pyrefly/blob/main/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`](https://github.com/facebook/pyrefly/blob/main/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`](https://github.com/facebook/pyrefly/blob/main/pyrefly.toml) or a `[tool.pyrefly]` table exists, Pyrefly uses those settings exclusively and does not migrate from [`mypy.ini`](https://github.com/facebook/pyrefly/blob/main/mypy.ini) or [`pyrightconfig.json`](https://github.com/facebook/pyrefly/blob/main/pyrightconfig.json). User-defined values in [`pyrefly.toml`](https://github.com/facebook/pyrefly/blob/main/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`](https://github.com/facebook/pyrefly/blob/main/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`](https://github.com/facebook/pyrefly/blob/main/pyproject.toml) using the same key structure and nesting as a dedicated [`pyrefly.toml`](https://github.com/facebook/pyrefly/blob/main/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`](https://github.com/facebook/pyrefly/blob/main/pyproject.toml) for build system and dependency management.