BasedPyright

1.39.0 · active · verified Thu Apr 09

BasedPyright is a static type checker for Python, forked from Pyright. It aims to provide various type checking improvements, integrate Pylance features (previously exclusive to VS Code), and introduce new diagnostic rules. Unlike upstream Pyright, it is officially published on PyPI, removing the requirement for Node.js. It is actively maintained with frequent releases, currently at version 1.39.0.

Warnings

gotcha Configuration precedence: If both `pyrightconfig.json` and `pyproject.toml` are present in the project root, `pyrightconfig.json` will take precedence, and settings in `pyproject.toml` will be ignored.
Fix: Consolidate your configuration into a single file, preferably `pyproject.toml` under the `[tool.basedpyright]` section, or ensure `pyrightconfig.json` is the sole source of truth.
gotcha VS Code / Pylance integration: When using BasedPyright with the Python extension (which includes Pylance) in VS Code, you must disable Pylance's type-checking (`"python.analysis.typeCheckingMode": "off"`) and BasedPyright's LSP features (`"basedpyright.disableLanguageServices": true`) in your `.vscode/settings.json` to prevent duplicated errors and conflicts.
Fix: Add these settings to your `.vscode/settings.json`: ```json { "python.analysis.typeCheckingMode": "off", "basedpyright.disableLanguageServices": true, "python.languageServer": "None" } ```
deprecated Diagnostic categories for 'unreachable', 'unused', and 'deprecated' code were deprecated in favor of a more flexible 'hint' category in version 1.21.0. Configuration should now use 'hint' for these diagnostics.
Fix: Update your configuration to use the `hint` category for these rules, e.g., `reportUnreachable = 'hint'`.
gotcha Unsafe `type: ignore` comments: `type: ignore` comments are considered unsafe and are disabled by default. BasedPyright recommends using `pyright: ignore` comments with specific error codes for better maintainability and safety.
Fix: Replace `type: ignore` with `pyright: ignore [ErrorCode]` where `[ErrorCode]` is the specific diagnostic rule you want to ignore.
breaking Invalid configuration files will cause `basedpyright` to exit with an error code (3). Unlike upstream Pyright, which might silently ignore invalid settings, BasedPyright is strict about configuration validity.
Fix: Ensure your `pyproject.toml` or `pyrightconfig.json` adheres strictly to the documented schema. BasedPyright will report the specific configuration error.
gotcha Unreachable code analysis: Pyright may not type-check code paths determined to be unreachable (e.g., in `if sys.version_info < (3, 10):` blocks if running on Python 3.10+), potentially leading to silent type errors. BasedPyright's `reportUnreachable` rule is designed to flag such unchecked code.
Fix: Enable and configure `reportUnreachable` in your `pyproject.toml` to catch these cases, or explicitly specify target `pythonVersion` and `pythonPlatform` in your config if the code is intended for specific environments.

Install

pip install basedpyright Install with pip
uv add --dev basedpyright Add to dev dependencies with uv

Quickstart

To get started, create a Python file and a `pyproject.toml` configuration. Then run `basedpyright` from your terminal. BasedPyright will analyze your code based on the rules specified in the configuration.

mkdir my_project
cd my_project

# Create a Python file
echo 'def greet(name: str) -> str:
    return "Hello, " + name

# Intentional type error for demonstration
def add(a: int, b: str) -> int:
    # Pyright will flag this: Expression of type "str" cannot be added to an expression of type "int"
    return a + b' > main.py

# Create a pyproject.toml for configuration
echo '[tool.basedpyright]
include = ["main.py"]
reportMissingTypeStubs = true
reportPrivateUsage = true' > pyproject.toml

# Run basedpyright
pip install basedpyright
basedpyright main.py

view raw JSON →