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

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 or a [tool.pyrefly] section within 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, the command specifically checks for Mypy configurations (either mypy.ini or [tool.mypy] in pyproject.toml) and Pyright configurations (either pyrightconfig.json or [tool.right] in pyproject.toml).

The detection logic uses the ConfigFileKind enum defined in pyrefly_config/file_kind.rs to identify these files:

// 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:

// 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) handles the translation of include lists and relevant options into the Pyrefly format:

// 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:

// 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.

# 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:

# 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:

# 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, [tool.mypy]) and Pyright (pyrightconfig.json, [tool.pyright]) configurations.
• The command uses ConfigFileKind checks in 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.

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