basedpyright: a stricter pyright fork that folds Pylance features into the language server

What basedpyright changes about pyright's defaults

pyright ships with a type checking mode that many teams find permissive out of the box. basedpyright is a fork of pyright that, according to the README, carries "various type checking improvements, pylance features and more." The practical consequence is that a project migrating to basedpyright can expect a different set of diagnostics on the same source tree without changing any code, because the fork adjusts what is reported by default. That is the whole reason the fork exists, and the documentation linked from the README is where the maintainer lists the specific divergences.

Who is this for? Teams already running pyright in CI or in an editor, who want stricter analysis without hand-writing a large configuration block to turn rules on. It is also for people who want Pylance behaviour in editors that cannot use Pylance, since Pylance is a closed-source Microsoft extension tied to VS Code. basedpyright packages those features into the language server itself, which is why the repository lists VS Code, Open VSX, Sublime Text and Neovim integrations among its badges. If you are starting a new Python project and have no opinion about type checkers, the fork's stricter defaults are a reasonable starting point, but they are not a reason on their own to pick it over pyright.

How the fork is structured: a TypeScript core with a Python wrapper

The primary language of the repository is TypeScript, and the top-level layout shows why. There is a packages/ directory, a tsconfig.json, a pnpm workspace file and a package.json whose name is pyright-root, with scripts that build the CLI and the VS Code extension separately: build:cli:dev targets packages/pyright, build:extension targets packages/vscode-pyright, and tests live under packages/pyright-internal. In other words, this is the pyright codebase, forked and extended, not a reimplementation.

The Python side is a thin wrapper. pyproject.toml declares two console scripts, basedpyright and basedpyright-langserver, pointing at basedpyright.pyright:main and basedpyright.langserver:main. The only runtime dependency is nodejs-wheel-binaries>=20.13.1, and the comment in that file explains the choice: only binaries are required, so a node or npm binary is not unknowingly added to the user's PATH. That is a deliberate packaging decision worth noting. Installing basedpyright through pip gives you a Python entry point that launches a bundled Node runtime, rather than asking you to install Node yourself.

The build backend is pdm.backend, and requires-python is >=3.10. The classifiers list Python 3.10 through 3.14. If your project still supports 3.9, the wrapper itself will not install.

Installing basedpyright and running a first check

The README links to PyPI, the Visual Studio Marketplace, Open VSX, Package Control for Sublime Text and Homebrew, so there are several distribution channels. The Python package is the one that matters for CI. Because the package declares basedpyright as a console script, installing it puts a basedpyright command on your PATH.

pip install basedpyright

After that, running the checker against a file or a directory uses the same command name. The repository's own CI task, typecheck-python, invokes it without arguments, which means it reads configuration from the project rather than from flags:

basedpyright

The language server has its own entry point, and the repository shows the stdio form used during development:

basedpyright-langserver --stdio

That is the command an editor plugin spawns. If you are wiring basedpyright into an editor that already speaks LSP, point it at basedpyright-langserver rather than at pyright-langserver. For VS Code there is a dedicated extension (detachhead.basedpyright on the Marketplace, detachhead/basedpyright on Open VSX), which is the path most users will take. The README does not document a --version flag or a configuration file format in the excerpt available, so treat the project documentation site as the source for config keys rather than guessing at pyright's.

The strictness trade-off, and where basedpyright is the wrong tool

Stricter defaults cut both ways. A codebase that has been running under pyright's default mode for years will likely produce a larger diagnostic set the first time basedpyright runs over it. The fork does not, as far as the repository shows, provide a migration mode that reports only the delta relative to upstream pyright. You get the fork's behaviour, and you deal with the output.

There is a baseline mechanism visible in the repository: the typecheck-python:writebaseline script runs the checker with a --writebaseline flag. That is the escape hatch for adopting the tool on an existing codebase, since it records current diagnostics so that only new ones fail. The README excerpt does not explain the baseline format or how it interacts with CI, so read the documentation before relying on it.

Where is basedpyright the wrong tool? If your team's type checking policy is defined by mypy's semantics, or by a checker whose rule set changes on a predictable schedule, a fork that tracks upstream pyright releases closely is a moving target. The release history shows this: v1.40.0 wraps pyright 1.1.412, and v1.40.1 wraps pyright 1.1.414, three days later. Every upstream release is a potential behaviour change in your CI. Teams that pin their tooling for long periods should budget for that. Also, if you need Pylance specifically, for example for its licensing terms or its Microsoft support channel, basedpyright is a reimplementation of features, not Pylance.

basedpyright vs pyright, mypy and ruff

Against pyright, the difference is defaults and packaging. Same TypeScript core, same LSP protocol, but a different set of rules enabled and Pylance-derived features in the server. If you have a pyright configuration you are happy with, switching to basedpyright means re-validating that configuration against the fork's behaviour, because a setting that was a no-op upstream may not be here.

Against mypy, the difference is architectural. mypy is a Python program with its own type system implementation and its own set of strictness flags. basedpyright is a Node program wrapped in Python, which means the analysis runs in a JavaScript runtime even when you invoke it from pip. That matters for container images and for anyone who cannot ship Node binaries. It also means the two tools will disagree on some programs, and running both is a legitimate strategy rather than a sign that one is broken.

Against ruff, the comparison is mostly a category error, and the search data suggests people make it anyway. Ruff is a linter and formatter written in Rust; its type checking story is separate from its lint rules. basedpyright does not format code and does not replace ruff. The repository itself uses both: ruff-check and ruff-fix scripts sit alongside typecheck-python in package.json. If you are choosing one, you are choosing the wrong axis.

Maintenance, licensing and what the repository does not say

The repository is not archived, and the last push was on 2026-09-22, one day before the release cadence implied by the tags. Recent releases are v1.40.1 on 2026-09-10, v1.40.0 on 2026-09-07 and v1.39.10 on 2026-08-13. That is a project tracking upstream pyright closely and shipping its own changes on top.

Licensing needs care. The repository metadata reports NOASSERTION, while pyproject.toml carries the classifier "License :: OSI Approved :: MIT License" and the top-level LICENSE.txt is the file to read. Because this is a fork of pyright, which is itself MIT licensed by Microsoft, the fork's own additions and the upstream code may be described in different files. If you are redistributing basedpyright, read LICENSE.txt and the upstream pyright licence rather than trusting the classifier alone. This is not legal advice; it is a pointer to where the answer lives.

Upgrade cost is the real ongoing expense. Every basedpyright release pulls in a pyright version, so an upgrade can change diagnostics from two directions at once: upstream pyright changes and fork-specific changes. The repository's own CI runs typecheck-python with uv, and the dev dependency group pins nodejs-wheel to >=24.14.1,<25, which is the kind of pin you should mirror in your own environment if you want reproducible output. Nothing in the available material documents a rollback procedure or a deprecation policy for configuration keys.

Editorial conclusion

Adopt basedpyright if you already use pyright and want stricter defaults plus Pylance-style editor features without a closed-source extension. Do not adopt it if you need a type checker with a stable, slow-moving rule set, because it tracks pyright releases closely (v1.40.1 wraps pyright 1.1.414) and adds its own settings on top. Before committing, verify two things: whether the stricter default mode produces a diagnostic count you can live with on your existing codebase, and whether your editor integration reads basedpyright's own configuration keys rather than pyright's. The pyproject.toml declares requires-python >=3.10, so check that first if you support older interpreters.

Frequently asked questions

Official sources

1. DetachHead/basedpyright on GitHub
2. Issues
3. Project website
4. README
5. Releases