Pyrefly

https://pyrefly.org/en/docs
Admin
Pyrefly is a fast type checker and language server for Python that identifies type-related errors in...
Tokens:148,419
Snippets:1,341
Trust Score:8.4
Update:1 week ago
Show doc for...
Tokens:
Raw
### Manual setup: Complete workflow

Source: https://pyrefly.org/en/docs/installation

A complete GitHub Actions workflow for manual setup, including steps to check out code, set up Python, install dependencies, install Pyrefly, and run the type checker with GitHub output format.

```yaml
name: Pyrefly Type Check  
  
on:  
  pull_request:  
    branches: [main]  
  workflow_dispatch:  # Allows manual triggering from the GitHub UI  
  
jobs:  
  typecheck:  
    runs-on: ubuntu-latest  
  
    steps:  
      - name: Check out code  
        uses: actions/checkout@v4  
  
      - name: Set up Python  
        uses: actions/setup-python@v5  
  
      # Install Python dependencies and create environment  
      - name: Install dependencies  
        run: |  
          python -m venv .venv  
          source .venv/bin/activate  
          python -m pip install --upgrade pip  
          # Install your dependencies; adjust the following lines as needed  
          pip install -r requirements-dev.txt  
  
      - name: Install Pyrefly  
        run: pip install pyrefly  
  
      - name: Run Pyrefly Type Checker  
        run: pyrefly check --output-format=github  

```

--------------------------------

### Per-target configuration example

Source: https://pyrefly.org/en/docs/configuration

Example showing how to define named configurations and assign them to specific targets.

```json
{
    "db": {
        "//Project:MyLib": {
            "srcs": { "Foo": ["Foo.py"] },
            "config": "lenient",
            "python_version": "3.12",
            "python_platform": "linux"
        }
    },
    "configs": {
        "lenient": {
            "errors": { "missing-import": "warn" },
            "check-unannotated-defs": false
        },
        "repo-wide": {
            "ignore-errors-in-generated-code": true
        }
    },
    "default_config": "repo-wide"
}
```

--------------------------------

### Fixture navigation example

Source: https://pyrefly.org/en/docs/pytest

Example demonstrating go-to-definition and find-references for a fixture parameter.

```python
import pytest

@pytest.fixture
def database_url() -> str:
    return "sqlite://"

def test_connection(database_url):
    assert database_url.startswith("sqlite")
```

--------------------------------

### Neovim init.lua: Setup Mason and mason-lspconfig

Source: https://pyrefly.org/en/docs/IDE

Add these lines to your Neovim init.lua to set up Mason and mason-lspconfig plugins, which are required for installing and configuring Pyrefly.

```lua
require("mason").setup()  
require("mason-lspconfig").setup()  

```

--------------------------------

### Install django-stubs and set up virtual environment

Source: https://pyrefly.org/en/docs/django

Install django-stubs and create a virtual environment. Run these commands in your terminal.

```bash
# Install django-stubs  
pip install django-stubs  
  
# Create and activate a virtual environment  
python3 -m venv .venv  
source .venv/bin/activate  
```

--------------------------------

### Install Pyrefly with uv and run init and check

Source: https://pyrefly.org/en/docs/installation

Use uvx to run Pyrefly without installing it as a dependency, then run `init` and `check --summarize-errors`.

```bash
uvx pyrefly init  
uvx pyrefly check --summarize-errors  

```

--------------------------------

### Simple Pyrefly configuration in pyrefly.toml

Source: https://pyrefly.org/en/docs/configuration

Example configuration file for Pyrefly. Sets project-includes, python-platform, and disables bad-assignment and bad-return errors. This is a simple example; more complex examples are available in the Example Configurations section.

```toml
# set the directory Pyrefly will search for files to type check  
project-includes = [  
    "a", "b/c/d", "e"  
]  
  
# manually set the `sys.platform` Pyrefly will assume when type checking  
python-platform = "linux"  
  
# a table mapping error codes to an `is-enabled` boolean  
[errors]  
# disable `bad-assignment` errors  
bad-assignment = false  
# disable `bad-return` errors  
bad-return = false  

```

--------------------------------

### Pyrefly Sub-Config Example

Source: https://pyrefly.org/en/docs/configuration

A configuration example demonstrating how to define root-level settings and multiple sub-configs that override specific options for different file paths.

```toml
replace-imports-with-any = [  
  "sympy.*",  
  "*.series",  
]  
ignore-errors-in-generated-code = true  
  
# disable `bad-assignment` and `invalid-argument` for the whole project  
[errors]  
bad-assignment = false  
invalid-argument = false  
  
[[sub-config]]  
# apply this to `sub/project/tests/file.py`  
matches = "sub/project/tests/file.py"  
  
# any unittest imports will by typed as `typing.Any`  
replace-imports-with-any = ["unittest.*"]  
  
[[sub-config]]  
# apply this config to all files in `sub/project`  
matches = "sub/project/**"  
  
# enable `assert-type` errors in `sub/project`  
[sub-config.errors]  
assert-type = true  
  
[[sub-config]]  
# apply this config to all files in `sub`  
matches = "sub/**"  
  
# disable `assert-type` errors in `sub`  
[sub-config.errors]  
assert-type = false  
  
[[sub-config]]  
# apply this config to all files under `tests` dirs in `sub/`  
matches = "sub/**/tests/**"  
  
# any pytest imports will be typed as `typing.Any`  
replace-imports-with-any = ["pytest.*"]
```

--------------------------------

### Install Pyrefly with pip and run init and check

Source: https://pyrefly.org/en/docs/installation

Use pip to install Pyrefly, then run `pyrefly init` to set up configuration and `pyrefly check --summarize-errors` to run the type checker with error summary.

```bash
pip install pyrefly  
pyrefly init  
pyrefly check --summarize-errors  

```

--------------------------------

### Example pyproject.toml configuration with [tool.pyrefly]

Source: https://pyrefly.org/en/docs/configuration

Shows the same configuration as the pyrefly.toml example but placed under the [tool.pyrefly] section in pyproject.toml, including sub-configurations for different paths.

```toml
...  
  
# Pyrefly header  
[tool.pyrefly]  
  
#### configuring what to type check and where to import from  
project-includes = ["src"]  
project-excludes = ["**/.[!/.]*", "**/tests"]  
search-path = ["src"]  
site-package-path = ["venv/lib/python3.12/site-packages"]  
  
#### configuring your python environment  
python-platform = "linux"  
python-version = "3.12"  
python-interpreter-path = "venv/bin/python3"  
  
#### configuring your type check settings  
replace-imports-with-any = [  
  "sympy.*",  
  "*.series",  
]  
  
ignore-errors-in-generated-code = true  
  
[tool.pyrefly.errors]  
bad-assignment = false  
invalid-argument = false  
  
[[tool.pyrefly.sub-config]]  
# apply this config to all files in `sub/project`  
matches = "sub/project/**"  
  
# enable `assert-type` errors in `sub/project`  
[tool.pyrefly.sub-config.errors]  
assert-type = true  
  
[[tool.pyrefly.sub-config]]  
# apply this config to all files in `sub`  
matches = "sub/**"  
  
# disable `assert-type` errors in `sub/project`  
[tool.pyrefly.sub-config.errors]  
assert-type = false  
  
# other non-Pyrefly configs  
...  

```

--------------------------------

### Manual setup: Workflow file path

Source: https://pyrefly.org/en/docs/installation

The path where the GitHub Actions workflow file should be saved for manual setup.

```text
.github/workflows/typecheck.yml  

```

--------------------------------

### Mypy example migration for vendor_sdk

Source: https://pyrefly.org/en/docs/migrate/mypy/ignore-missing-imports

Mypy configuration with mypy_path and a per-module override for vendor_sdk.*. This is the source configuration for the migration example.

```ini
[mypy]  
mypy_path = src  

[mypy-vendor_sdk.*]  
ignore_missing_imports = True  

```

--------------------------------

### Fish completion setup

Source: https://pyrefly.org/en/docs/shell-completion

Save the completion script in the fish completions directory.

```fish
mkdir -p ~/.config/fish/completions  
pyrefly completion --shell fish > ~/.config/fish/completions/pyrefly.fish  
```

--------------------------------

### Test changes in the sandbox with Yarn commands

Source: https://pyrefly.org/en/docs/wasm

Commands to set up and run the website sandbox with WASM dependencies. `yarn install-with-wasm-deps` builds WASM and installs dependencies; `yarn start-with-wasm` rebuilds WASM and starts Docusaurus.

```bash
cd website  
yarn install-with-wasm-deps   # first time: build WASM + yarn install  
yarn start-with-wasm          # rebuild WASM and start Docusaurus  

```

--------------------------------

### Zsh completion setup

Source: https://pyrefly.org/en/docs/shell-completion

Add these lines to ~/.zshrc after initializing completion with compinit to enable zsh completion.

```zsh
autoload -Uz compinit  
compinit  
source <(pyrefly completion --shell zsh)  
```

--------------------------------

### Install Pyrefly with conda and run init and check

Source: https://pyrefly.org/en/docs/installation

Use conda to install Pyrefly from conda-forge, then run `pyrefly init` and `pyrefly check --summarize-errors`.

```bash
conda install -c conda-forge pyrefly  
pyrefly init  
pyrefly check --summarize-errors  

```

--------------------------------

### Neovim init.lua: Ensure Pyrefly installed via Mason

Source: https://pyrefly.org/en/docs/IDE

Add this to your init.lua to automatically install Pyrefly through Mason's ensure_installed option. This is an alternative to running :MasonInstall pyrefly manually.

```lua
require("mason-lspconfig").setup {  
  ensure_installed = { "pyrefly" },  
}  

```

--------------------------------

### Install the Pyrefly plugin in pants.toml

Source: https://pyrefly.org/en/docs/pants

Add the plugin and backend packages to your pants.toml file to enable Pyrefly.

```toml
[GLOBAL]  
plugins = ["pants-pyrefly==PANTS_PYREFLY_VERSION"]  
backend_packages.add = [  
    "pants.backend.python",  
    "pants_pyrefly",  
]  
```

--------------------------------

### Bash completion setup

Source: https://pyrefly.org/en/docs/shell-completion

Add this line to ~/.bashrc to enable bash completion for Pyrefly.

```bash
source <(pyrefly completion --shell bash)  
```

--------------------------------

### Mypy configuration example

Source: https://pyrefly.org/en/docs/migrate/mypy/error-codes

Shows a mypy configuration with error codes enabled and disabled. This is the source configuration to be converted.

```toml
[tool.mypy]  
enable_error_code = ["explicit-override", "possibly-undefined"]  
disable_error_code = ["import-untyped"]  

```

--------------------------------

### PowerShell completion setup

Source: https://pyrefly.org/en/docs/shell-completion

Add this line to your PowerShell profile ($PROFILE) to enable completion.

```powershell
pyrefly completion --shell powershell | Out-String | Invoke-Expression  
```

--------------------------------

### Division by zero examples

Source: https://pyrefly.org/en/docs/error-kinds

Shows division, floor division, and modulo by literal zero, each raising ZeroDivisionError at runtime.

```python
x = 10 / 0   # error: division by zero  
y = 10 // 0  # error: division by zero  
z = 10 % 0   # error: division by zero  

```

--------------------------------

### GitHub Action: Basic usage

Source: https://pyrefly.org/en/docs/installation

Minimal usage of the official Pyrefly GitHub Action. It handles Python setup, installation, and running the type checker with inline PR annotations enabled by default.

```yaml
- uses: facebook/pyrefly@main  

```

--------------------------------

### Emacs use-package configuration for Pyrefly with eglot

Source: https://pyrefly.org/en/docs/IDE

Minimal use-package setup that installs eglot, hooks it to Python modes, and configures Pyrefly as the language server. Place the add-to-list inside the :config block.

```lisp
(use-package eglot  
  :ensure t  
  :hook ((python-mode python-ts-mode) . eglot-ensure)  
  :config  
  (add-to-list 'eglot-server-programs  
    `((python-ts-mode python-mode) . ("pyrefly" "lsp"))))  

```

--------------------------------

### LSP initializationOptions example with all supported keys at defaults

Source: https://pyrefly.org/en/docs/IDE

Shows the full set of initializationOptions keys for non-VSCode editors. Keys are VSCode setting names with leading 'python.' stripped; 'analysis' is also accepted under 'pyrefly'. All keys are optional; omitted keys keep defaults. Note that commentFoldingRanges is at top level, and pyrefly.pyreflyExecutable, pyrefly.lspPath, pyrefly.lspArguments, and pyrefly.trace.server have no initializationOptions equivalent.

```json
{  
  "pythonPath": "/usr/bin/python3",  
  "commentFoldingRanges": false,  
  "analysis": {  
    "diagnosticMode": "openFilesOnly",  
    "importFormat": "absolute",  
    "completeFunctionParens": false,  
    "autoImportCompletions": true,  
    "showHoverGoToLinks": true,  
    "inlayHintDebounceMs": 0,  
    "inlayHints": {  
      "callArgumentNames": "off",  
      "functionReturnTypes": true,  
      "pytestParameters": false,  
      "variableTypes": true  
    }  
  },  
  "pyrefly": {  
    "typeCheckingMode": "auto",  
    "disableTypeErrors": false,  
    "displayTypeErrors": "default",  
    "typeErrorDisplayStatusVersion": "v1",  
    "disableLanguageServices": false,  
    "diagnosticMode": "openFilesOnly",  
    "extraSearchPaths": [],  
    "extraProjectExcludes": [],  
    "configPath": "",  
    "streamDiagnostics": true,  
    "syncNotebooks": true,  
    "runnableCodeLens": false,  
    "disabledLanguageServices": {  
      "hover": false,  
      "documentSymbol": false,  
      "workspaceSymbol": false,  
      "inlayHint": false,  
      "completion": false,  
      "codeAction": false,  
      "definition": false,  
      "declaration": false,  
      "typeDefinition": false,  
      "references": false,  
      "documentHighlight": false,  
      "rename": false,  
      "codeLens": false,  
      "semanticTokens": false,  
      "signatureHelp": false,  
      "implementation": false,  
      "callHierarchy": false  
    }  
  }  
}  

```

--------------------------------

### Install Pyrefly with pixi and run init and check

Source: https://pyrefly.org/en/docs/installation

Add Pyrefly with pixi, then run `init` and `check --summarize-errors` using `pixi run`.

```bash
pixi add pyrefly  
pixi run pyrefly init  
pixi run pyrefly check --summarize-errors  

```

--------------------------------

### Install Pyrefly with uv or pip

Source: https://pyrefly.org/en/docs/compare

Install Pyrefly as a development dependency using either uv or pip. The uv command adds it to the project's dev dependencies, while the pip command installs it into the current environment.

```bash
# uv  
uv add --dev pyrefly  
  
# pip  
python -m pip install pyrefly  
```

--------------------------------

### Install pyrefly (version 0.42.0 or later)

Source: https://pyrefly.org/en/docs/django

Install pyrefly using pip. Requires version 0.42.0 or later.

```bash
pip install pyrefly  
```

--------------------------------

### Elvish completion setup

Source: https://pyrefly.org/en/docs/shell-completion

Save the completion script and load it from ~/.config/elvish/rc.elv. The first block creates the directory and writes the script; the second block loads it.

```elvish
mkdir -p ~/.config/elvish/lib  
pyrefly completion --shell elvish > ~/.config/elvish/lib/pyrefly.elv  
```

```elvish
use pyrefly  
```

--------------------------------

### Basic Pyrefly configuration in pyproject.toml or pyrefly.toml

Source: https://pyrefly.org/en/docs/installation

Add configuration options to a `pyproject.toml` file or create a `pyrefly.toml` file in the project directory. This example sets the `search_path` to include `example_directory/...`.

```toml
[tool.pyrefly]  
search_path = [  
    "example_directory/..."  
]  
```

--------------------------------

### Define Django User model for factory_boy examples

Source: https://pyrefly.org/en/docs/django

Base model used by the factory_boy examples. Defines a User model with a username CharField.

```python
# myapp/models.py  
from django.db import models  
  
class User(models.Model):  
    username = models.CharField(max_length=150)  

```

--------------------------------

### Install Pyrefly with poetry and run init and check

Source: https://pyrefly.org/en/docs/installation

Add Pyrefly as a dev dependency with poetry, then run `init` and `check --summarize-errors` using `poetry run`.

```bash
poetry add --group dev pyrefly  
poetry run pyrefly init  
poetry run pyrefly check --summarize-errors  

```

--------------------------------

### Example Pyright configuration

Source: https://pyrefly.org/en/docs/migrate/pyright/config

A sample Pyright configuration showing common fields like include, exclude, extraPaths, pythonVersion, pythonPlatform, and diagnostic settings.

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

--------------------------------

### Install pyrefly-torch-stubs

Source: https://pyrefly.org/en/docs/tensor-shapes-setup

Install the shape-aware stubs from PyPI. This PEP 561 stub-only package provides type information for PyTorch without affecting the runtime torch package.

```bash
pip install pyrefly-torch-stubs  
```

--------------------------------

### Install Pyrefly and check code

Source: https://pyrefly.org/en/docs/python-typing-for-beginners

Commands to install Pyrefly with pip and run type checks on a single file or entire directories. The check command is zero-config and can be used on files or folders.

```bash
# Fast, zero‑config  
pip install pyrefly  
  
pyrefly check ./my_sample.py  
  
# Check whole directories  
pyrefly check app/ tests/  
```

--------------------------------

### Use UserFactory.create() and build()

Source: https://pyrefly.org/en/docs/django

Shows that create() and build() return a User instance, as verified by assert_type.

```python
user = UserFactory.create()  
assert_type(user, User)  
  
user = UserFactory.build()  
assert_type(user, User)  

```

--------------------------------

### untyped-namedtuple example

Source: https://pyrefly.org/en/docs/error-kinds

Shows a collections.namedtuple without field types, triggering the untyped-namedtuple error, and the recommended fix using typing.NamedTuple with declared field types. The example includes the necessary imports and a comment indicating the error.

```python
from collections import namedtuple  
from typing import NamedTuple  
  
Point = namedtuple("Point", ["x", "y"])  # untyped-namedtuple  
  
# Fix:  
class Point(NamedTuple):  
    x: int  
    y: int  

```

--------------------------------

### Example pyrefly.toml configuration

Source: https://pyrefly.org/en/docs/configuration

Shows a complete pyrefly.toml configuration with project includes/excludes, search paths, Python environment settings, error overrides, and sub-configurations for specific files and directories.

```toml
project-includes = ["src"]  
project-excludes = ["**/.[!/.]*", "**/tests"]  
search-path = ["src"]  
site-package-path = ["venv/lib/python3.12/site-packages"]  
  
python-platform = "linux"  
python-version = "3.12"  
python-interpreter-path = "venv/bin/python3"  
  
replace-imports-with-any = [  
  "sympy.*",  
  "*.series",  
]  
ignore-errors-in-generated-code = true  
  
# disable `bad-assignment` and `invalid-argument` for the whole project  
[errors]  
bad-assignment = false  
invalid-argument = false  
  
[[sub-config]]  
# apply this to `sub/project/tests/file.py`  
matches = "sub/project/tests/file.py"  
  
# any unittest imports will by typed as `typing.Any`  
replace-imports-with-any = ["unittest.*"]  
  
[[sub-config]]  
# apply this config to all files in `sub/project`  
matches = "sub/project/**"  
  
# enable `assert-type` errors in `sub/project`  
[sub-config.errors]  
assert-type = true  

```

--------------------------------

### untyped-function-decorator example

Source: https://pyrefly.org/en/docs/error-kinds

Shows two cases where a decorator obscures the decorated function's type: a decorator typed as Any and an unannotated decorator returning implicit Any. Both trigger the untyped-function-decorator error. The example includes the necessary import and comments indicating the error.

```python
from typing import Any  
  
my_decorator: Any = lambda f: f  
  
@my_decorator  # `my_decorator` is `Any`, so the type of `g` is lost [untyped-function-decorator]  
def g() -> int:  
    return 1  
  
def unannotated(f):  # returns an implicit `Any`  
    return f  
  
@unannotated  # the result is unknown, so the type of `h` is lost [untyped-function-decorator]  
def h() -> int:  
    return 1  

```

--------------------------------

### Example of missing-override-decorator

Source: https://pyrefly.org/en/docs/error-kinds

Shows when the missing-override-decorator error is emitted: for methods overriding a parent class method without @override, except for dunder methods inherited from object. The example includes a class hierarchy and comments indicating which lines trigger the error.

```python
from typing import override  
  
class Base:  
    def foo(self) -> None: ...  
    def __len__(self) -> int: ...  
  
class Derived(Base):  
    def foo(self) -> None: ...  # missing-override-decorator  
  
    def __len__(self) -> int: ...  # missing-override-decorator (inherited from Base, not object)  
  
    def __repr__(self) -> str: ...  # OK (inherited from object)  
  
    @override  
    def foo(self) -> None: ...  # OK  

```

--------------------------------

### Step 2: Run formatter

Source: https://pyrefly.org/en/docs/error-suppressions

Placeholder step to run your formatter of choice after suppressing errors. This is part of the upgrade workflow.

```bash
# step 2  
<run your formatter of choice>  

```

--------------------------------

### treat-all-caps-as-final example showing errors on reassignment

Source: https://pyrefly.org/en/docs/configuration

When treat-all-caps-as-final is enabled, assigning to an ALL_CAPS name again emits a bad-assignment error. This example shows FOO and LOCAL being reassigned, with errors on the second assignments. Names inside function bodies and non-constant names are unaffected.

```python
FOO = 1  
FOO = 2  # error  
  
def f() -> None:  
    LOCAL = 1  
    LOCAL = 2  # error  
```

--------------------------------

### Fixture alias example

Source: https://pyrefly.org/en/docs/pytest

Shows using an imported fixture alias with @reusable.

```python
from pytest import fixture as reusable

@reusable
def user_id() -> int:
    return 42

def test_lookup(user_id):
    assert user_id > 0
```

--------------------------------

### Initialize Pyrefly configuration

Source: https://pyrefly.org/en/docs/pants

Run this command to generate a Pyrefly configuration file. It will not overwrite an existing configuration.

```bash
pants pyrefly-init  
```
Tokens:
Raw