website/docs/migrating-from-pyright.mdx - third_party/github.com/facebook/pyrefly - Git at Google

 ---
 title: Migrating from Pyright

 description: How to switch your type checker configuration from Pyright to Pyrefly
 ---

 {/*
  * Copyright (c) Meta Platforms, Inc. and affiliates.
  *
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */}

 ## Running Pyrefly

 Like pyright, pyrefly can be given a list of files to check:

 ```sh
 $ pyrefly check file1.py file2.py
 ```

 The easiest way to run pyrefly on all files in a project is to run it from the project root:

 ```sh
 $ cd your/project
 $ pyrefly check
 ```

 Pyrefly doesn't need a config file to start checking your code. Its sensible defaults are designed to work well for most projects.
 However, projects with existing pyright configs may want to configure pyrefly to suit their own needs.

 ## Pyright Config Migration

 To make it as easy as possible to get started with pyrefly, we've provided a script for automatically migrating a pyright config to pyrefly.

 ```sh
 $ pyrefly init path/to/your/project
 ```

 This will search for an existing `pyrightconfig.json` or `pyproject.toml` with a `tool.pyright` section, and then transform it into a `pyrefly.toml` (or `[tool.pyrefly]` section) while preserving as many options as possible. See `init --help` for more options.

 There is a significant overlap between pyright's and pyrefly's configuration options, so migration is pretty straightforward. However, it may be worth checking the generated config for errors, just in case.

 If you'd rather start fresh with a hand-written config, please see the [pyrefly configuration docs](configuration.mdx).
 If you run into any issues with config migration, please [let us know](https://github.com/facebook/pyrefly/issues)!

 ## Config Migration Details

 When it comes to listing files, pyright uses just paths, while pyrefly supports glob patterns. Thankfully, paths are a subset of glob patterns, so pyrefly can just use the paths as-is. You could consider manually simplifying the paths into glob patterns, but it's not necessary.

 Pyright supports four platforms: Windows, Linux, Darwin (macOS), and All. Since pyrefly only supports Python's [supported platforms](https://docs.python.org/3/library/sys.html#sys.platform), we choose to treat "All" as "linux".

 ### Type Check Diagnostic Settings and Error Kinds

 Pyrefly maps pyright's [type check diagnostics settings](https://microsoft.github.io/pyright/#/configuration?id=type-check-diagnostics-settings) to equivalent pyrefly [error kinds](error-kinds.mdx).
 While not every diagnostic setting has an equivalent error kind, we make an effort to ensure that pyrefly suppresses the same errors that pyright does.

 This may lead to overly broad error suppressions, and you may want to consider removing some error kinds from the disable list.
 You can also use a [SubConfig](configuration.mdx#sub_config) to selectively silence errors in specific files,
 or see [Silencing Errors](#silencing-errors) for how to suppress errors at the source.

 See [Error Kind Mapping](#error-kind-mapping) for a table showing the relationship between type check diagnostic settings and error kinds.

 ### Execution Environments

 Pyright's [execution environments](https://microsoft.github.io/pyright/#/configuration?id=execution-environment-options) let you customize the Python version, platform, module search paths, and diagnostic settings for some part of your project.
 Pyrefly's [SubConfigs](configuration.mdx#sub_config) are a similar mechanism that let you configure pyrefly's behavior for files matching a filepath glob.
 However, subconfigs do not support changing the Python version, platform, or module search paths.

 Diagnostic settings are carried over to the equivalent subconfig, using the mapping mentioned [above](#type-check-diagnostic-settings-and-error-kinds).

 ### Extending Builtins

 Pyright automatically imports any builtins defined in `__builtins__.pyi` at the project root or in a custom stubs directory specified by `stubPath` (defaulting to `./typings`).

 Pyrefly supports this behavior - the directory for `stubPath` should be added to your Pyrefly config's `site-package-path`.

 ## Silencing Errors

 Like pyright, pyrefly has ways to silence specific error codes. Full details can be found in the [Error Suppression docs](error-suppressions.mdx).

 To silence an error on a specific line, add a disable comment above that line. You can either suppress all errors on that line:

 ```
 # pyrefly: ignore
 x: str = 1
 ```

 Or target a specific error type:

 ```
 # pyrefly: ignore[bad-assignment]
 x: str = 1
 ```

 To suppress all instances of an error, disable that error in the config:

 ```
 [errors]
 missing-import = false
 ```

 This is similar to pyright's [type check rule overrides](https://microsoft.github.io/pyright/#/configuration?id=type-check-rule-overrides), though of course the [error codes](error-kinds.mdx) are different!

 You can also use:

 ```toml
 permissive-ignores = true
 ```

 To allow `pyright: ignore` comments to be used by Pyrefly.

 ## Error Kind Mapping

 This table shows the mapping between pyright's [type check diagnostics settings](https://microsoft.github.io/pyright/#/configuration?id=type-check-diagnostics-settings)
 and pyrefly's [error kinds](error-kinds.mdx).

 :::info
 When no configuration file is present, Pyrefly shows the following diagnostics as **warnings** in the IDE, matching pyright's default behavior:
 - `reportInvalidTypeForm` → [`invalid-annotation`](error-kinds.mdx#invalid-annotation)
 - `reportMissingImports` → [`missing-import`](error-kinds.mdx#missing-import)
 - `reportUndefinedVariable` → [`unknown-name`](error-kinds.mdx#unknown-name)

 This means users migrating from pyright will see familiar diagnostics even before creating a Pyrefly config file.
 :::

 | Pyright | Pyrefly |
 | ------- | ------- |
 | reportAbstractUsage | bad-instantiation |
 | reportArgumentType | bad-argument-type |
 | reportAssertTypeFailure | assert-type |
 | reportAssignmentType | bad-assignment |
 | reportAttributeAccessIssue | missing-attribute |
 | reportDeprecated | deprecated |
 | reportExplicitAny | explicit-any |
 | reportIncompatibleMethodOverride | bad-override |
 | reportIncompatibleVariableOverride | bad-override |
 | reportInconsistentOverload | inconsistent-overload |
 | reportIndexIssue | bad-index |
 | reportInvalidTypeArguments | bad-specialization |
 | reportInvalidTypeForm | invalid-annotation |
 | reportInvalidTypeVarUse | invalid-type-var |
 | reportMissingImports | missing-import |
 | reportMissingModuleSource | missing-source |
 | reportMissingParameterType | unannotated-parameter |
 | reportMissingTypeStubs | untyped-import |
 | reportNoOverloadImplementation | invalid-overload |
 | reportOperatorIssue | unsupported-operation |
 | reportPossiblyUnboundVariable | unbound-name |
 | reportPrivateUsage | no-access |
 | reportReturnType | bad-return |
 | reportUnboundVariable | unbound-name |
 | reportUndefinedVariable | unknown-name |
 | reportUninitializedInstanceVariable | implicitly-defined-attribute |
 | reportUnknownArgumentType | implicit-any |
 | reportUnknownMemberType | implicit-any |
 | reportUnknownParameterType | unannotated-parameter |
 | reportUnknownVariableType | implicit-any |
 | reportUnnecessaryCast | redundant-cast |
 | reportUnusedCoroutine | unused-coroutine |
	---
	title: Migrating from Pyright

	description: How to switch your type checker configuration from Pyright to Pyrefly
	---

	{/*
	* Copyright (c) Meta Platforms, Inc. and affiliates.
	*
	* This source code is licensed under the MIT license found in the
	* LICENSE file in the root directory of this source tree.
	*/}

	## Running Pyrefly

	Like pyright, pyrefly can be given a list of files to check:

	```sh
	$ pyrefly check file1.py file2.py
	```

	The easiest way to run pyrefly on all files in a project is to run it from the project root:

	```sh
	$ cd your/project
	$ pyrefly check
	```

	Pyrefly doesn't need a config file to start checking your code. Its sensible defaults are designed to work well for most projects.
	However, projects with existing pyright configs may want to configure pyrefly to suit their own needs.

	## Pyright Config Migration

	To make it as easy as possible to get started with pyrefly, we've provided a script for automatically migrating a pyright config to pyrefly.

	```sh
	$ pyrefly init path/to/your/project
	```

	This will search for an existing `pyrightconfig.json` or `pyproject.toml` with a `tool.pyright` section, and then transform it into a `pyrefly.toml` (or `[tool.pyrefly]` section) while preserving as many options as possible. See `init --help` for more options.

	There is a significant overlap between pyright's and pyrefly's configuration options, so migration is pretty straightforward. However, it may be worth checking the generated config for errors, just in case.

	If you'd rather start fresh with a hand-written config, please see the [pyrefly configuration docs](configuration.mdx).
	If you run into any issues with config migration, please [let us know](https://github.com/facebook/pyrefly/issues)!

	## Config Migration Details

	When it comes to listing files, pyright uses just paths, while pyrefly supports glob patterns. Thankfully, paths are a subset of glob patterns, so pyrefly can just use the paths as-is. You could consider manually simplifying the paths into glob patterns, but it's not necessary.

	Pyright supports four platforms: Windows, Linux, Darwin (macOS), and All. Since pyrefly only supports Python's [supported platforms](https://docs.python.org/3/library/sys.html#sys.platform), we choose to treat "All" as "linux".

	### Type Check Diagnostic Settings and Error Kinds

	Pyrefly maps pyright's [type check diagnostics settings](https://microsoft.github.io/pyright/#/configuration?id=type-check-diagnostics-settings) to equivalent pyrefly [error kinds](error-kinds.mdx).
	While not every diagnostic setting has an equivalent error kind, we make an effort to ensure that pyrefly suppresses the same errors that pyright does.

	This may lead to overly broad error suppressions, and you may want to consider removing some error kinds from the disable list.
	You can also use a [SubConfig](configuration.mdx#sub_config) to selectively silence errors in specific files,
	or see [Silencing Errors](#silencing-errors) for how to suppress errors at the source.

	See [Error Kind Mapping](#error-kind-mapping) for a table showing the relationship between type check diagnostic settings and error kinds.

	### Execution Environments

	Pyright's [execution environments](https://microsoft.github.io/pyright/#/configuration?id=execution-environment-options) let you customize the Python version, platform, module search paths, and diagnostic settings for some part of your project.
	Pyrefly's [SubConfigs](configuration.mdx#sub_config) are a similar mechanism that let you configure pyrefly's behavior for files matching a filepath glob.
	However, subconfigs do not support changing the Python version, platform, or module search paths.

	Diagnostic settings are carried over to the equivalent subconfig, using the mapping mentioned [above](#type-check-diagnostic-settings-and-error-kinds).

	### Extending Builtins

	Pyright automatically imports any builtins defined in `__builtins__.pyi` at the project root or in a custom stubs directory specified by `stubPath` (defaulting to `./typings`).

	Pyrefly supports this behavior - the directory for `stubPath` should be added to your Pyrefly config's `site-package-path`.

	## Silencing Errors

	Like pyright, pyrefly has ways to silence specific error codes. Full details can be found in the [Error Suppression docs](error-suppressions.mdx).

	To silence an error on a specific line, add a disable comment above that line. You can either suppress all errors on that line:

	```
	# pyrefly: ignore
	x: str = 1
	```

	Or target a specific error type:

	```
	# pyrefly: ignore[bad-assignment]
	x: str = 1
	```

	To suppress all instances of an error, disable that error in the config:

	```
	[errors]
	missing-import = false
	```

	This is similar to pyright's [type check rule overrides](https://microsoft.github.io/pyright/#/configuration?id=type-check-rule-overrides), though of course the [error codes](error-kinds.mdx) are different!

	You can also use:

	```toml
	permissive-ignores = true
	```

	To allow `pyright: ignore` comments to be used by Pyrefly.

	## Error Kind Mapping

	This table shows the mapping between pyright's [type check diagnostics settings](https://microsoft.github.io/pyright/#/configuration?id=type-check-diagnostics-settings)
	and pyrefly's [error kinds](error-kinds.mdx).

	:::info
	When no configuration file is present, Pyrefly shows the following diagnostics as warnings in the IDE, matching pyright's default behavior:
	- `reportInvalidTypeForm` → [`invalid-annotation`](error-kinds.mdx#invalid-annotation)
	- `reportMissingImports` → [`missing-import`](error-kinds.mdx#missing-import)
	- `reportUndefinedVariable` → [`unknown-name`](error-kinds.mdx#unknown-name)

	This means users migrating from pyright will see familiar diagnostics even before creating a Pyrefly config file.
	:::

	\| Pyright \| Pyrefly \|
	\| ------- \| ------- \|
	\| reportAbstractUsage \| bad-instantiation \|
	\| reportArgumentType \| bad-argument-type \|
	\| reportAssertTypeFailure \| assert-type \|
	\| reportAssignmentType \| bad-assignment \|
	\| reportAttributeAccessIssue \| missing-attribute \|
	\| reportDeprecated \| deprecated \|
	\| reportExplicitAny \| explicit-any \|
	\| reportIncompatibleMethodOverride \| bad-override \|
	\| reportIncompatibleVariableOverride \| bad-override \|
	\| reportInconsistentOverload \| inconsistent-overload \|
	\| reportIndexIssue \| bad-index \|
	\| reportInvalidTypeArguments \| bad-specialization \|
	\| reportInvalidTypeForm \| invalid-annotation \|
	\| reportInvalidTypeVarUse \| invalid-type-var \|
	\| reportMissingImports \| missing-import \|
	\| reportMissingModuleSource \| missing-source \|
	\| reportMissingParameterType \| unannotated-parameter \|
	\| reportMissingTypeStubs \| untyped-import \|
	\| reportNoOverloadImplementation \| invalid-overload \|
	\| reportOperatorIssue \| unsupported-operation \|
	\| reportPossiblyUnboundVariable \| unbound-name \|
	\| reportPrivateUsage \| no-access \|
	\| reportReturnType \| bad-return \|
	\| reportUnboundVariable \| unbound-name \|
	\| reportUndefinedVariable \| unknown-name \|
	\| reportUninitializedInstanceVariable \| implicitly-defined-attribute \|
	\| reportUnknownArgumentType \| implicit-any \|
	\| reportUnknownMemberType \| implicit-any \|
	\| reportUnknownParameterType \| unannotated-parameter \|
	\| reportUnknownVariableType \| implicit-any \|
	\| reportUnnecessaryCast \| redundant-cast \|
	\| reportUnusedCoroutine \| unused-coroutine \|