Skip to main content

Pyright Config to Pyrefly

pyrefly init converts the Pyright project, import, environment, and diagnostic fields that have a Pyrefly counterpart. Not every Pyright setting has a precise Pyrefly equivalent. Use this guide to understand the gaps and when you need to update your config manually.

Quick conversion​

pyrefly init

Example source:

{
    "include": ["src"],
    "exclude": ["**/generated"],
    "extraPaths": ["src"],
    "pythonVersion": "3.13",
    "pythonPlatform": "Linux",
    "reportMissingImports": "error",
    "reportUnknownMemberType": "warning"
}

Representative Pyrefly result:

project-includes = ["src"]
project-excludes = ["**/generated"]
search-path = ["src"]
python-version = "3.13"
python-platform = "linux"
infer-with-first-use = false

[errors]
missing-import = "error"
unknown-attribute-type = "warn"

Mapping status​

  • Automatic: pyrefly init reads the Pyright option and writes the Pyrefly setting.
  • Manual: a related Pyrefly setting exists, but pyrefly init doesn't translate it, so you'll need to manually update your Pyrefly config.
  • Not mapped: no current automatic or direct equivalent in Pyrefly.

Project and type-evaluation settings​

Pyright optionClosest Pyrefly setting or workflowStatusMigration note
includeproject-includesAutomaticPaths and globs are carried over as-is.
excludeproject-excludesAutomaticReview differences in default excludes and in files that are excluded but still imported.
strictExplicit [sub-config.errors] overrides or separate configsManualA Pyrefly preset cannot be selected inside a sub-config, so a path list cannot become preset = "strict" directly.
extendsFlatten the inherited configManualPyrefly config has no config-inheritance key.
defineConstantNo direct settingNot mappedUse ordinary Python constants or separate target configs.
typeshedPathtypeshed-pathManualThe equivalent setting exists but is not read by the converter.
stubPathsite-package-pathAutomaticReview import precedence and whether the directory contains only stubs.
venvPathActivated environment or python-interpreter-pathManualPyrefly prefers querying the selected interpreter.
venvActivated environment or python-interpreter-pathManualPyrefly has no separate venvPath + venv pair.
verboseOutputCLI loggingNo 1:1 mapping
extraPathssearch-pathAutomatic
pythonVersionpython-versionAutomatic
pythonPlatformpython-platformAutomaticAll, Linux, Darwin, and Windows are normalized. Pyrefly also accepts a list of target platforms.
executionEnvironmentssub-config, for diagnostic overrides onlyAutomatic; partialPer-environment Python version, platform, and search paths cannot be represented in a Pyrefly sub-config.
useLibraryCodeForTypesNo direct settingNot mappedValidate behavior for untyped libraries.
strictListInferenceNo direct settingNot mappedDo not confuse this with infer-with-first-use, which controls unsolved types such as empty containers.
strictDictionaryInferenceNo direct settingNot mapped
strictSetInferenceNo direct settingNot mapped
analyzeUnannotatedFunctionscheck-unannotated-defsManualBoth default to analyzing unannotated function bodies, but the converter does not read the Pyright field.
strictParameterNoneValueNo direct settingNot mapped
enableTypeIgnoreCommentsenabled-ignoresUsually no change neededPyrefly respects # type: ignore by default.
deprecateTypingAliasesdeprecatedManual; not exact
enableReachabilityAnalysisunreachable / unreachable-match-caseManual; not exactPyrefly has no global analysis toggle with the same semantics.
enableExperimentalFeaturesNo direct settingNot mapped
disableBytesTypePromotionsNo direct settingNot mapped
typeCheckingModepresetManual; approximateoff, basic, and strict have similarly named Pyrefly presets, but the rule bundles are not identical. Pyright standard is closest to a reviewed Pyrefly default config.
ignoreBaseline, source suppressions, or project excludesManual; no exact 1:1Pyright suppresses diagnostics while still analyzing ignored files; project-excludes changes project membership.
root (execution environment)matches in a [[sub-config]]AutomaticOnly the environment's diagnostic overrides are carried over.

Diagnostic settings​

Recognized Pyright report* severities become Pyrefly [errors] entries. Boolean true becomes error, false becomes ignore, and string levels convert to the corresponding Pyrefly severity.

Because Pyright diagnostics are often umbrellas, one rule can become several Pyrefly kinds. Use the complete Pyright diagnostics matrix rather than assuming the names are interchangeable.

Execution environments​

Source:

{
    "executionEnvironments": [
        {
            "root": "src/legacy",
            "pythonVersion": "3.10",
            "extraPaths": ["vendor"],
            "reportUnknownMemberType": "none"
        }
    ]
}

The diagnostic override becomes:

[[sub-config]]
matches = "src/legacy"

[sub-config.errors]
unknown-attribute-type = "ignore"

The per-environment Python version and import path are not preserved, because Pyrefly sub-configs cannot override them. Use a separate configuration file for a genuinely different Python environment.

Path-specific strictness​

Pyright's top-level strict array behaves like adding # pyright: strict to every matched file. Pyrefly cannot put preset = "strict" inside a sub-config, so translate the policy into explicit error severities:

[[sub-config]]
matches = "src/core/**"

[sub-config.errors]
implicit-any = "error"
missing-override-decorator = "error"
unused-ignore = "error"

Treat this as an example, not a complete recreation of Pyright strict mode.

Linter-like Pyright rules​

Several Pyright settings cover unused imports, duplicate imports, string escapes, mutable default values, naming, and unused expressions. Pyrefly deliberately does not map most of these checker-adjacent checks. Keep them in Ruff or another linter rather than forcing them onto unrelated Pyrefly error kinds.

Upstream references​

Next steps​

note

Last reviewed against upstream Pyright documentation and Pyrefly's migration source on 2026-08-08.