Basedpyright: Python Type Checker (pyright Fork)

Basedpyright is a static type checker and language server for Python, maintained by DetachHead as a community fork of Microsoft’s pyright. It tracks upstream pyright closely and adds diagnostic rules, stricter defaults, and language-server features that Microsoft keeps exclusive to its closed-source Pylance extension.

Both pyright and Basedpyright are installable from PyPI and can be pinned as project dependencies. pyright’s Python wrapper uses Node.js from PATH or downloads it on first run; Basedpyright installs its runtime through nodejs-wheel-binaries. Basedpyright also re-implements Pylance-style inlay hints, semantic highlighting, and docstring completion in its open-source server.

When to use Basedpyright

Basedpyright suits teams that want pyright’s analysis without pyright’s packaging friction, want stricter defaults than pyright’s standard mode provides, or need Pylance-style editor features in a non-Microsoft VS Code build. For projects already on pyright, pyrightconfig.json and [tool.pyright] settings are supported, but stricter diagnostics and suppression defaults need review. The baseline feature supports incremental adoption.

Projects that are happy with pyright inside Microsoft VS Code have little reason to switch. Basedpyright is designed for the cases that Microsoft’s distribution choices leave uncovered. For a broader comparison, see How do Python type checkers compare?.

Key Features

• PyPI distribution: installs with pip install basedpyright or uv add --dev basedpyright. Its nodejs-wheel-binaries dependency supplies Node.js, so no separate npm or node install is required.
• Pylance features in the open-source server: inlay hints for inferred types and semantic token highlighting work in any LSP-compatible editor, along with docstring completion.
• Stricter defaults: recommended enables diagnostic rules at warning or error severity and fails the CLI on warnings. all promotes those warnings to errors; compatibility settings such as enableTypeIgnoreComments remain disabled.
• New diagnostic rules: additions beyond upstream pyright include reportAny, reportIgnoreCommentWithoutRule, reportUnreachable, and reportImplicitStringConcatenation.
• Baseline mode: basedpyright --writebaseline records current errors to .basedpyright/baseline.json, letting an existing codebase adopt stricter rules without fixing every pre-existing issue at once.
• Tracks upstream pyright: incorporates upstream typing fixes alongside its own rules and narrowing behavior.

Configuration

Basedpyright discovers pyrightconfig.json or pyproject.toml under [tool.basedpyright]. pyrightconfig.json takes precedence. [tool.pyright] is supported for compatibility, but including both TOML sections is an error. basedpyrightconfig.json is not automatically discovered; --project can select a configuration explicitly. See Basedpyright configuration files.

[tool.basedpyright]
pythonVersion = "3.12"
typeCheckingMode = "recommended"
reportMissingTypeStubs = false

typeCheckingMode = "recommended" and "all" are Basedpyright’s additions on top of pyright’s off/basic/standard/strict scale, and recommended is the default. Upstream pyright rejects both values. Both enable diagnostic rules; recommended distinguishes warnings from errors and sets failOnWarnings = true. See the diagnostic defaults.

Installation and Usage

# Install with uv
uv add --dev basedpyright

# Or run without installing
uvx basedpyright src/

# Check a project
uv run basedpyright src/

# Watch mode
uv run basedpyright --watch

# Emit JSON for CI
uv run basedpyright --outputjson src/

# Record current errors as a baseline
uv run basedpyright --writebaseline

Basedpyright is also available via Homebrew (brew install basedpyright) and npm (@detachhead/pyright).

Editor Integration

• VS Code / VSCodium: install the BasedPyright extension from the VS Code Marketplace or Open VSX. If Pylance is detected, the extension prompts to disable it so the two don’t double-flag the same file.
• Neovim: configure through nvim-lspconfig pointing at basedpyright-langserver --stdio. Mason.nvim has a ready-made package.
• Sublime Text: install LSP and LSP-basedpyright via Package Control.
• Emacs, Helix, Zed, and other LSP clients: launch the server with basedpyright-langserver --stdio.

Positron (the Posit data-science IDE that forks VS Code) bundles Basedpyright as a selectable language server, which is one of the reasons the project exists in the form it does.

Pros

• Installable from PyPI with no separate Node.js dependency for project use
• Pylance-style inlay hints and semantic highlighting available in any LSP editor
• Stricter defaults catch issues pyright suppresses until strict mode
• Baseline mode enables incremental adoption of stricter rules in existing codebases
• MIT licensed, so no concerns about use in commercial or closed-source projects
• Supports existing pyright configuration while allowing stricter policies

Cons

• Stricter defaults produce more warnings out of the box, which some teams find noisy on exploratory code
• Smaller community than upstream pyright; issue response comes from a small number of maintainers
• Some added rules fire on patterns mature libraries accept (for example, reportAny on unavoidable Any returns from third-party APIs), requiring per-file suppression

Comparison to Other Tools

Basedpyright shares pyright’s analysis engine and adds diagnostic rules, narrowing changes, stricter defaults, and editor features. A passing pyright check can therefore fail under Basedpyright. Against mypy, Basedpyright checks unannotated bodies and infers return types by default. The type-checker comparison explains the operational differences.

Suppressions and Exit Codes

Use # pyright: ignore[reportAssignmentType] for a targeted suppression. In the default recommended mode, # type: ignore comments are disabled through enableTypeIgnoreComments = false. Enable reportUnnecessaryTypeIgnoreComment to report obsolete suppressions. See Basedpyright comment controls.

Errors exit with 1. Warning-only runs also exit with 1 under recommended because it enables failOnWarnings; set that option to false to allow warning-only runs. Invalid configuration and CLI usage use other nonzero codes. See Basedpyright CLI behavior.