Skip to content

pyrefly

pyrefly documentation

Pyrefly

Bases: Tool[_R]

Classes:

Name Description
Check

Methods:

Name Description
__call__

A fast Python type checker

flags

Bind tool-level global options before the subcommand.

Attributes:

Name Type Description
check Check[_R]
argv Pyrefly[Argv]

check instance-attribute

check: Check[_R]

argv property

argv: Pyrefly[Argv]

Check

Bases: Tool[_R2]

Methods:

Name Description
__call__

Full type checking on a file or a project

Attributes:

Name Type Description
argv Check[Argv]

argv property

argv: Check[Argv]

__call__

__call__(*args: str | PathLike[str], baseline: Value = ..., baseline_error_level: BaselineErrorLevel | Sequence[BaselineErrorLevel] | None = ..., check_all: Flag = ..., check_unannotated_defs: ValuedFlag = ..., color: Color | Sequence[Color] | None = ..., conda_environment: Value = ..., config: Value = ..., count_errors: ValuedFlag = ..., debug_info: Value = ..., dependency_graph: Value = ..., disable_project_excludes_heuristics: ValuedFlag = ..., disable_search_path_heuristics: ValuedFlag = ..., enable_fallback_search_path: ValuedFlag = ..., enabled_ignores: EnabledIgnores | Sequence[EnabledIgnores] | None = ..., error: Value = ..., error_stale_baseline: Flag = ..., expectations: Flag = ..., fallback_python_interpreter_name: Value = ..., ignore: Value = ..., ignore_errors_in_generated_code: ValuedFlag = ..., ignore_missing_imports: Value = ..., infer_return_types: InferReturnTypes | Sequence[InferReturnTypes] | None = ..., infer_with_first_use: ValuedFlag = ..., info: Value = ..., legacy_overload_expansion: ValuedFlag = ..., min_severity: MinSeverity | Sequence[MinSeverity] | None = ..., no_progress_bar: Flag = ..., only: Value = ..., output: Value = ..., output_format: OutputFormat | Sequence[OutputFormat] | None = ..., permissive_ignores: ValuedFlag = ..., preset: Preset | Sequence[Preset] | None = ..., progress_bar: ProgressBar | Sequence[ProgressBar] | None = ..., project_excludes: Value = ..., prune_baseline: Flag = ..., python_interpreter_path: Value = ..., python_platform: Value = ..., python_version: Value = ..., pytorch_efficiency_lints: PytorchEfficiencyLints | Sequence[PytorchEfficiencyLints] | None = ..., recursion_depth_limit: Value = ..., recursion_overflow_handler: RecursionOverflowHandler | Sequence[RecursionOverflowHandler] | None = ..., relative_to: Value = ..., remove_unused_ignores: ValuedFlag = ..., replace_imports_with_any: Value = ..., replace_untyped_imports_with_any: Value = ..., report_binding_memory: Value = ..., report_demand_tree: Value = ..., report_glean: Value = ..., report_pysa: Value = ..., report_pysa_format: ReportPysaFormat | Sequence[ReportPysaFormat] | None = ..., report_timings: Value = ..., report_trace: Value = ..., search_path: Value = ..., site_package_path: Value = ..., skip_interpreter_query: Flag = ..., spec_compliant_overloads: ValuedFlag = ..., strict_callable_subtyping: ValuedFlag = ..., strict_partial_subtyping: ValuedFlag = ..., summarize_errors: ValuedFlag = ..., summary: ValuedFlag = ..., suppress_errors: Flag = ..., tensor_shapes: TensorShapes | Sequence[TensorShapes] | None = ..., threads: Value = ..., treat_all_caps_as_final: ValuedFlag = ..., type_ignore_unknown_tag_behavior: TypeIgnoreUnknownTagBehavior | Sequence[TypeIgnoreUnknownTagBehavior] | None = ..., typeshed_path: Value = ..., untyped_def_behavior: UntypedDefBehavior | Sequence[UntypedDefBehavior] | None = ..., update_baseline: Flag = ..., use_ignore_files: ValuedFlag = ..., verbose: Flag = ..., warn: Value = ..., watch: Flag = ..., **flags: Any) -> _R2

Full type checking on a file or a project

Parameters:

Name Type Description Default
baseline Value

Path to baseline file for comparing type errors.

...
baseline_error_level BaselineErrorLevel | Sequence[BaselineErrorLevel] | None

Severity assigned to errors that match the baseline. Added in 1.3.0.

...
check_all Flag

Check all reachable modules, not just the ones that are passed in explicitly on CLI positional arguments.

...
check_unannotated_defs ValuedFlag

Whether to type check the bodies of unannotated function definitions. Value optional: True for the bare flag, or pass one. Added in 0.58.0.

...
color Color | Sequence[Color] | None

Control whether colored output is used. Defaults to auto.

...
conda_environment Value

Use a specific Conda environment to query Python environment information, even if it isn't activated.

...
config Value

Explicitly set the Pyrefly configuration to use when type checking.

...
count_errors ValuedFlag

Count the number of each error kind. Value optional: True for the bare flag, or pass one.

...
debug_info Value

Produce debugging information about the type checking process.

...
dependency_graph Value

Experimental: generate a JSON dependency graph of all modules to the specified file.

...
disable_project_excludes_heuristics ValuedFlag

Configures Pyrefly to replace project-excludes fully rather than append whatever is in your configuration or passed by CLI to Pyrefly's defaults. Value optional: True for the bare flag, or pass one.

...
disable_search_path_heuristics ValuedFlag

Disable Pyrefly default heuristics, specifically those around constructing a modified search path. Value optional: True for the bare flag, or pass one.

...
enable_fallback_search_path ValuedFlag

Enable walk-up fallback search paths, where Pyrefly walks up from each importing file's directory to the config root to best-effort resolve imports. Value optional: True for the bare flag, or pass one. Added in 1.1.0.

...
enabled_ignores EnabledIgnores | Sequence[EnabledIgnores] | None

Respect ignore directives from only these tools. May be repeated: a list emits the flag once per item.

...
error Value

Force this rule to emit an error. May be repeated: a list emits the flag once per item.

...
error_stale_baseline Flag

Exit with a non-zero status when the checked scope makes baseline entries stale. Added in 1.3.0.

...
expectations Flag

Check against any E: lines in the file.

...
fallback_python_interpreter_name Value

The Python executable name available on your PATH that will be queried for your python-version, python-platform, or site-package-path if any of the values are missing.

...
ignore Value

Do not emit diagnostics for this rule. May be repeated: a list emits the flag once per item.

...
ignore_errors_in_generated_code ValuedFlag

Whether to ignore type errors in generated code. Value optional: True for the bare flag, or pass one.

...
ignore_missing_imports Value

If the specified imported module can't be found, replace it with typing.Any, suppressing related import errors.

...
infer_return_types InferReturnTypes | Sequence[InferReturnTypes] | None

Controls when return types are inferred for functions without return annotations. Added in 0.58.0.

...
infer_with_first_use ValuedFlag

If this is true, infer type variables not determined by a call or constructor based on their first usage. Value optional: True for the bare flag, or pass one.

...
info Value

Force this rule to emit an info-level diagnostic. May be repeated: a list emits the flag once per item.

...
legacy_overload_expansion ValuedFlag

Whether to expand union arguments to narrow an already-matched overloaded call. Value optional: True for the bare flag, or pass one. Added in 1.2.0.

...
min_severity MinSeverity | Sequence[MinSeverity] | None

Minimum severity level for errors to be displayed. Added in 0.58.0.

...
no_progress_bar Flag

Suppress the progress bar during type checking. Gone since 0.63.1.

...
only Value

Filter errors to show only a specific error kind (e.g., bad-assignment, missing-return, etc.). May be repeated: a list emits the flag once per item.

...
output Value

Write errors to an output destination.

...
output_format OutputFormat | Sequence[OutputFormat] | None

Set the default error output format.

...
permissive_ignores ValuedFlag

Whether Pyrefly will respect ignore statements for other tools, e.g. # pyright: ignore. Value optional: True for the bare flag, or pass one.

...
preset Preset | Sequence[Preset] | None

A named collection of error severities and behavior settings that serves as the base configuration. Added in 1.1.0.

...
progress_bar ProgressBar | Sequence[ProgressBar] | None

Set the progress bar style. Added in 0.63.1.

...
project_excludes Value

Files to exclude when type checking.

...
prune_baseline Flag

Rewrite the baseline file to drop stale entries without recording new errors. Added in 1.3.0.

...
python_interpreter_path Value

The path to a Python executable that will be queried for python-version python-platform, or site-package-path if any of the values are missing.

...
python_platform Value

The platform any sys.platform checks should evaluate against.

...
python_version Value

The Python version any sys.version checks should evaluate against.

...
pytorch_efficiency_lints PytorchEfficiencyLints | Sequence[PytorchEfficiencyLints] | None

Deprecated: use --warn=pytorch-efficiency-lints instead. Added in 1.1.0.

...
recursion_depth_limit Value

Maximum recursion depth before triggering overflow protection.

...
recursion_overflow_handler RecursionOverflowHandler | Sequence[RecursionOverflowHandler] | None

How to handle when recursion depth limit is exceeded.

...
relative_to Value

When specified, strip this prefix from any paths in the output.

...
remove_unused_ignores ValuedFlag

Remove unused ignores from the input files, optionally selecting pyrefly, type, or all. Value optional: True for the bare flag, or pass one.

...
replace_imports_with_any Value

Always replace specified imports with typing.Any, suppressing related import errors even if the module is found.

...
replace_untyped_imports_with_any Value

Replace specified third-party imports with typing.Any when no stubs or py.typed marker exist. Added in 1.3.0.

...
report_binding_memory Value

Report the memory usage of bindings.

...
report_demand_tree Value

Report the cross-module demand tree (aggregated summary of LookupAnswer and LookupExport calls). Added in 0.64.0.

...
report_glean Value

Generate a Glean-compatible JSON file for each module.

...
report_pysa Value

Generate a Pysa-compatible JSON file for each module.

...
report_pysa_format ReportPysaFormat | Sequence[ReportPysaFormat] | None

Format for pysa report output (json or capnp). Defaults to capnp. Added in 0.59.1.

...
report_timings Value

Process each module individually to figure out how long each step takes.

...
report_trace Value

Report type traces.

...
search_path Value

The list of directories where imports are imported from, including type checked files.

...
site_package_path Value

Directories containing third-party package imports, searched after first checking search_path and typeshed.

...
skip_interpreter_query Flag

Skip doing any automatic querying for python-interpreter-path, fallback-python-interpreter-name, or conda-environment.

...
spec_compliant_overloads ValuedFlag

Whether to use spec-compliant overload evaluation semantics. Value optional: True for the bare flag, or pass one. Added in 0.59.0.

...
strict_callable_subtyping ValuedFlag

Whether to strictly check callable subtyping for signatures with *args: Any, **kwargs: Any. Value optional: True for the bare flag, or pass one.

...
strict_partial_subtyping ValuedFlag

Whether to strictly check the parameters of a functools.partial(...) residual when it is assigned to a callable. Value optional: True for the bare flag, or pass one. Added in 1.2.0.

...
summarize_errors ValuedFlag

Summarize errors by directory. Value optional: True for the bare flag, or pass one.

...
summary ValuedFlag

By default show a progress bar and the number of errors. Value optional: True for the bare flag, or pass one. Defaults to default.

...
suppress_errors Flag

Suppress errors found in the input files.

...
tensor_shapes TensorShapes | Sequence[TensorShapes] | None

Deprecated no-op.

...
threads Value

Number of threads to use for parallelization. Defaults to 0.

...
treat_all_caps_as_final ValuedFlag

Treat ALL_CAPS names as final after their first assignment. Value optional: True for the bare flag, or pass one. Added in 1.3.0.

...
type_ignore_unknown_tag_behavior TypeIgnoreUnknownTagBehavior | Sequence[TypeIgnoreUnknownTagBehavior] | None

How # type: ignore[...] comments with non-Pyrefly tags affect diagnostics. Added in 1.3.0.

...
typeshed_path Value

Override the bundled typeshed with a custom path.

...
untyped_def_behavior UntypedDefBehavior | Sequence[UntypedDefBehavior] | None

Deprecated: use --check-unannotated-defs and --infer-return-types instead.

...
update_baseline Flag

When specified, emit a sorted/formatted JSON of the errors to the baseline file.

...
use_ignore_files ValuedFlag

Whether to respect ignore files (.gitignore, .ignore, .git/exclude). Value optional: True for the bare flag, or pass one.

...
verbose Flag

Enable verbose logging.

...
warn Value

Force this rule to emit a warning. May be repeated: a list emits the flag once per item.

...
watch Flag

Watch for file changes and re-check them.

...

__call__

__call__(*args: str | PathLike[str], color: Color | Sequence[Color] | None = ..., threads: Value = ..., verbose: Flag = ..., **flags: Any) -> _R

A fast Python type checker

Parameters:

Name Type Description Default
color Color | Sequence[Color] | None

Control whether colored output is used. Defaults to auto.

...
threads Value

Number of threads to use for parallelization. Defaults to 0.

...
verbose Flag

Enable verbose logging.

...

flags

flags(*, color: Color | Sequence[Color] | None = ..., threads: Value = ..., verbose: Flag = ..., **flags: Any) -> Self

Bind tool-level global options before the subcommand.

tools.docker.flags(host=...) puts a tool's own options ahead of the verb, where they belong.