basedpyright

library1.39.0pypypiunverified

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.

testing

pip install basedpyright

github ↗package ↗

INSTALL

IMPORT

SIG · BASEDPYRIGHT

basedpyright

testingpythonv1.39.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

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

basedpyright --version

Debug

Known issues

gotchaConfiguration 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.

affects: All versions

gotchaVS 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" 
}
```

affects: All versions

deprecatedDiagnostic 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'`.

affects: >=1.21.0

gotchaUnsafe `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.

affects: All versions (disabled by default since early versions)

breakingInvalid 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.

affects: All versions

gotchaUnreachable 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.

affects: All versions

Errors

Common errors & fixes

error: Import "module_name" could not be resolved basedpyright[reportMissingImports]

BasedPyright cannot find the specified module due to incorrect path configuration, missing packages in the active environment, or issues with how the module is exposed in a monorepo or `uv` workspace.

fix

Ensure the module is installed in your Python environment. For project-specific imports, add the relevant paths to `extraPaths` in your `pyrightconfig.json` (e.g., `"extraPaths": ["src"]`), or restart your language server if using tools like `uv` workspaces.

spawn: python3 failed with exit code 1

This error often occurs during `basedpyright` installation via package managers like Mason, indicating that a system dependency for `python3` or its `venv` module is missing.

fix

Install the necessary `python3-venv` package on your system (e.g., `sudo apt install python3.12-venv` for Python 3.12 on Debian/Ubuntu-based systems).

error: TypeVar "T" appears only once in generic function signature

This diagnostic is reported by Pyright (and potentially BasedPyright with stricter settings) when a `TypeVar` is used only in the return position of a generic function, which might be considered an 'unbound' or unconstrained `TypeVar` by some type checkers.

fix

BasedPyright generally relaxes this specific error if the type variable is only in the return position and can safely return that type at runtime. If still encountered, consider if the `TypeVar` truly needs to be generic, or if a more specific type (like `Any` or `object`) can be used if no input argument constrains the `TypeVar`.

basedpyright: Configuration file contains unknown option "your_option_name"

BasedPyright was run with a configuration file (`pyrightconfig.json` or `pyproject.toml`) that contains an unrecognized or misspelled setting, or a setting that is not supported by the version of BasedPyright being used.

fix

Review your `pyrightconfig.json` or `pyproject.toml` for typos in configuration keys. Consult the official BasedPyright documentation for valid configuration options and ensure they match your installed version. BasedPyright intentionally exits with an error on invalid configuration to prevent silent misbehavior.

Upgrade

Version history

1.39.0latest on PyPI · released Apr 1, 2026

Audit

Dependencies

pythonrequiredRequired to run the type checker.

Agent activity

38 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/detachhead/basedpyright ↗

packagehttps://pypi.org/project/basedpyright/ ↗