{"id":1946,"library":"basedpyright","title":"BasedPyright","description":"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.","status":"active","version":"1.39.0","language":"python","source_language":"en","source_url":"https://github.com/DetachHead/basedpyright","tags":["static analysis","type checking","linter","pyright","pylance"],"install":[{"cmd":"pip install basedpyright","lang":"bash","label":"Install with pip"},{"cmd":"uv add --dev basedpyright","lang":"bash","label":"Add to dev dependencies with uv"}],"dependencies":[{"reason":"Required to run the type checker.","package":"python","optional":false}],"imports":[],"quickstart":{"code":"mkdir my_project\ncd my_project\n\n# Create a Python file\necho 'def greet(name: str) -> str:\n    return \"Hello, \" + name\n\n# Intentional type error for demonstration\ndef add(a: int, b: str) -> int:\n    # Pyright will flag this: Expression of type \"str\" cannot be added to an expression of type \"int\"\n    return a + b' > main.py\n\n# Create a pyproject.toml for configuration\necho '[tool.basedpyright]\ninclude = [\"main.py\"]\nreportMissingTypeStubs = true\nreportPrivateUsage = true' > pyproject.toml\n\n# Run basedpyright\npip install basedpyright\nbasedpyright main.py","lang":"bash","description":"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."},"warnings":[{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Add these settings to your `.vscode/settings.json`:\n```json\n{\n  \"python.analysis.typeCheckingMode\": \"off\",\n  \"basedpyright.disableLanguageServices\": true,\n  \"python.languageServer\": \"None\" \n}\n```","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Update your configuration to use the `hint` category for these rules, e.g., `reportUnreachable = 'hint'`.","message":"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.","severity":"deprecated","affected_versions":">=1.21.0"},{"fix":"Replace `type: ignore` with `pyright: ignore [ErrorCode]` where `[ErrorCode]` is the specific diagnostic rule you want to ignore.","message":"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.","severity":"gotcha","affected_versions":"All versions (disabled by default since early versions)"},{"fix":"Ensure your `pyproject.toml` or `pyrightconfig.json` adheres strictly to the documented schema. BasedPyright will report the specific configuration error.","message":"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.","severity":"breaking","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"search_vec":"'1.39.0':58 'activ':50 'aim':14 'analysi':60 'basedpyright':1,2 'check':19,62 'checker':7 'code':28 'current':55 'diagnost':32 'exclus':25 'featur':23 'fork':10 'frequent':53 'improv':20 'integr':21 'introduc':30 'linter':63 'maintain':51 'new':31 'node.js':47 'offici':39 'previous':24 'provid':16 'publish':40 'pylanc':22,65 'pypi':42 'pyright':12,36,64 'python':9 'releas':54 'remov':43 'requir':45 'rule':33 'static':5,59 'type':6,18,61 'unlik':34 'upstream':35 'various':17 'version':57 'vs':27","created_at":"2026-04-09T18:36:55.894755+00:00","updated_at":"2026-04-15T23:54:11.511553+00:00","problems":[{"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.","cause":"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.","error":"error: Import \"module_name\" could not be resolved basedpyright[reportMissingImports]"},{"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).","cause":"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.","error":"spawn: python3 failed with exit code 1"},{"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`.","cause":"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.","error":"error: TypeVar \"T\" appears only once in generic function signature"},{"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.","cause":"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.","error":"basedpyright: Configuration file contains unknown option \"your_option_name\""}],"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"basedpyright","cli_version":"basedpyright 1.39.4","type":"library","homepage":null,"github":"https://github.com/detachhead/basedpyright","docs":null,"changelog":null,"pypi":"https://pypi.org/project/basedpyright/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["testing"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-04-09","next_check":"2026-07-08","install_tag":null}}