# How to Use pyrefly init to Migrate from Mypy or Pyright Configuration

> Easily migrate Mypy or Pyright configurations to Pyrefly using the pyrefly init command. Automatically convert include paths and settings to pyrefly.toml or pyproject.toml.

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

---

**The `pyrefly init` command automatically detects existing Mypy or Pyright configurations in your project and migrates their include paths and core settings into a fresh [`pyrefly.toml`](https://github.com/facebook/pyrefly/blob/main/pyrefly.toml) or a `[tool.pyrefly]` section within [`pyproject.toml`](https://github.com/facebook/pyrefly/blob/main/pyproject.toml).**

The `facebook/pyrefly` repository provides the `init` subcommand as the primary entry point for adopting Pyrefly in codebases already using static type analysis. When executed in a directory containing configuration files for other type checkers, the command reads your existing setup and generates equivalent Pyrefly configuration without requiring manual translation of settings.

## Automatic Configuration Detection and Migration

### How Existing Type Checkers Are Discovered

The initialization process begins by scanning the target directory for recognizable configuration patterns. According to the implementation in [`pyrefly/lib/commands/init.rs`](https://github.com/facebook/pyrefly/blob/main/pyrefly/lib/commands/init.rs), the command specifically checks for Mypy configurations (either [`mypy.ini`](https://github.com/facebook/pyrefly/blob/main/mypy.ini) or `[tool.mypy]` in [`pyproject.toml`](https://github.com/facebook/pyrefly/blob/main/pyproject.toml)) and Pyright configurations (either [`pyrightconfig.json`](https://github.com/facebook/pyrefly/blob/main/pyrightconfig.json) or `[tool.right]` in [`pyproject.toml`](https://github.com/facebook/pyrefly/blob/main/pyproject.toml)).

The detection logic uses the `ConfigFileKind` enum defined in [`pyrefly_config/file_kind.rs`](https://github.com/facebook/pyrefly/blob/main/pyrefly_config/file_kind.rs) to identify these files:

```rust
// pyrefly/lib/commands/init.rs:263-267
let found_mypy = ConfigFileKind::MyPy.check_for_existing_config(&path)?;
let found_pyright = ConfigFileKind::Pyright.check_for_existing_config(&path)?;

```

### Migration Priority and Execution Logic

When multiple configuration sources exist, the command follows a deterministic priority scheme. The `MigrationSource` enum controls this behavior, with the default value set to `Auto`:

```rust
// pyrefly/lib/commands/init.rs:50-53
#[arg(long, value_enum, default_value_t = MigrationSource::Auto)]
migrate_from: MigrationSource,

```

In `Auto` mode, the system attempts Mypy migration first, then falls back to Pyright if no Mypy configuration is found. Once a valid configuration is detected, the `config_migration` function (located in [`pyrefly_config/migration/run.rs`](https://github.com/facebook/pyrefly/blob/main/pyrefly_config/migration/run.rs)) handles the translation of include lists and relevant options into the Pyrefly format:

```rust
// pyrefly/lib/commands/init.rs:268-279
if found_mypy || found_pyright {
    info!("Found an existing type checking configuration - setting up pyrefly ...");
    return Ok((
        CommandExitStatus::Success,
        Some(config_migration(
            &path,
            self.migrate_from,
            self.dry_run,
            self.print_config,
        )?),
    ));
}

```

If neither Mypy nor Pyright configurations exist, the command generates a minimal default configuration:

```rust
// pyrefly/lib/commands/init.rs:283-288
let cfg = ConfigFile {
    project_includes: ConfigFile::default_project_includes(),
    ..Default::default()
};

```

## Command-Line Options for Controlled Migration

### Selecting the Migration Source Explicitly

Use the `--migrate-from` flag to override the automatic detection and force migration from a specific tool. This is useful when your project contains configuration files from multiple type checkers but you want to prioritize Pyright settings over Mypy settings.

```bash

# Force migration from Pyright even if Mypy config exists

pyrefly init --migrate-from=pyright

# Explicitly select Mypy

pyrefly init --migrate-from=mypy

```

### Preview and Non-Interactive Modes

The command provides several flags for CI/CD integration and safe testing:

- **`--dry-run`**: Calculates the migration without writing to the filesystem, allowing you to verify changes before committing them.
- **`--print-config`**: Outputs the resulting TOML configuration to **stdout**, enabling redirection to files or inspection in pipelines.
- **`--non-interactive`**: Disables all prompts, ensuring the command completes successfully in automated environments.

These flags can be combined to generate configurations safely:

```bash

# CI-friendly: non-interactive dry run with stdout output

pyrefly init --non-interactive --dry-run --print-config > pyrefly.toml

```

## Practical Migration Examples

The following patterns cover common migration scenarios when moving from Mypy or Pyright to Pyrefly:

```bash

# Basic automatic migration (detects Mypy first, then Pyright)

pyrefly init

# Preview what would be generated without creating files

pyrefly init --dry-run

# Generate config and print to stdout for manual inspection

pyrefly init --print-config

# Complete CI pipeline example: migrate from Pyright non-interactively

pyrefly init --migrate-from=pyright --non-interactive --print-config > pyproject.toml

```

## Summary

- **`pyrefly init`** automatically detects existing **Mypy** ([`mypy.ini`](https://github.com/facebook/pyrefly/blob/main/mypy.ini), `[tool.mypy]`) and **Pyright** ([`pyrightconfig.json`](https://github.com/facebook/pyrefly/blob/main/pyrightconfig.json), `[tool.pyright]`) configurations.
- The command uses `ConfigFileKind` checks in [`pyrefly/lib/commands/init.rs`](https://github.com/facebook/pyrefly/blob/main/pyrefly/lib/commands/init.rs) to identify source configurations before invoking `config_migration`.
- By default, **Mypy configurations take precedence** over Pyright when both exist (`--migrate-from=auto`).
- Use **`--dry-run`** and **`--print-config`** to preview migrations without modifying your filesystem.
- The **`--non-interactive`** flag ensures reliable execution in automated build pipelines.

## Frequently Asked Questions

### Does pyrefly init overwrite my existing mypy.ini or pyrightconfig.json files?

No, the `pyrefly init` command is non-destructive. It reads your existing configuration to populate the new Pyrefly settings but never modifies or deletes the original Mypy or Pyright files. This allows you to run both type checkers in parallel during your transition period.

### What happens if both Mypy and Pyright configurations exist in my project?

When multiple configurations are detected, the command defaults to the `Auto` setting, which prioritizes Mypy over Pyright. If you wish to migrate from Pyright instead, explicitly specify the source using `pyrefly init --migrate-from=pyright`.

### Can I use pyrefly init in CI/CD pipelines without interactive prompts?

Yes, combine the `--non-interactive` flag with `--print-config` to generate configuration deterministically. This pattern is safe for automated environments: `pyrefly init --non-interactive --print-config > pyrefly.toml`.

### Which configuration options are preserved during migration?

The migration primarily preserves **include paths** and **project root settings** that define which files should be type-checked. Other tool-specific options (such as Mypy's strictness flags or Pyright's analysis modes) may not have direct equivalents in Pyrefly and are handled according to the logic in [`pyrefly_config/migration/run.rs`](https://github.com/facebook/pyrefly/blob/main/pyrefly_config/migration/run.rs).