Skip to content

Basedpyright: Python Type Checker (Pyright Fork)

by Tim Hopper
Type Checking

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.

The fork exists because pyright ships as an npm package and depends on Node.js, which makes it awkward to pin as a project dependency, and because the editor features most Python developers associate with “pyright” actually live in Pylance, whose license restricts it to official Microsoft VS Code builds. Basedpyright packages the language server on PyPI so uv add --dev basedpyright works, and re-implements Pylance-style features (inlay hints, semantic highlighting, docstring completion) in the open-source server so VS Code forks like Cursor, VSCodium, and Positron can use them.

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, migration is low-risk: pyrightconfig.json is compatible and [tool.pyright] entries in pyproject.toml are honored, so teams can evaluate stricter rules incrementally with the baseline feature.

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. The wheel bundles a Node.js runtime, 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: all diagnostic rules are enabled by default rather than hidden behind strict mode, which the project describes as “maximum discoverability.”
  • 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: frequent rebases on Microsoft’s pyright keep typing spec conformance close to upstream (pyright scores 97.8% on the official typing conformance suite).

Configuration

Basedpyright reads configuration from pyrightconfig.json, basedpyrightconfig.json, or pyproject.toml under [tool.basedpyright]. Existing [tool.pyright] sections are honored for backward compatibility.

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

typeCheckingMode = "recommended" is Basedpyright’s addition on top of pyright’s off/basic/standard/strict/all scale. It enables the rules the project considers worth using in practice without turning on every experimental diagnostic.

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
  • Configuration compatible with pyright, so migrating an existing project is mostly a name change

Cons

  • Stricter defaults produce more warnings out of the box, which some teams find noisy on exploratory code
  • Implemented in TypeScript rather than Rust, so the per-file analysis cost is higher than ty or Pyrefly on large codebases
  • 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 sits closest to pyright on type-system behavior; the two disagree on defaults and editor features, not on how Python types work. Against ty and Pyrefly, Basedpyright wins on typing spec conformance (inherited from pyright at roughly 97.8%) but loses on raw speed, where the Rust-based checkers are an order of magnitude faster. Against mypy, Basedpyright checks unannotated code by default where mypy skips it.

Learn More

Last updated on
AnacondaBlack

Please submit corrections and feedback...