Basilisk

English · 简体中文

The only Python type checker scoring 100% on the official python/typing conformance suite — and the fastest we’ve measured.
Complete open-source Python dev environment in Rust: type checker, language server, debugger, profiler, plus VS Code, Cursor, Zed & Neovim extensions. Strict by default. Weighing up the best Python type checker for your codebase? Start with the scoreboard.

You are reading the Basilisk source repository — the checker, language server, editor extensions, and website all live here.

Website  •  Install  •  Quick Start  •  Rules  •  Refactoring  •  Compare  •  GitHub

100.0% PEP conformance — 141 of 141 tests in the official python/typing conformance suite (commit 39164cd), scored on the wheel-installed CLI in its default config by the real upstream harness. We target python/typing@main and ratchet the score up only.

The only 100% checker — and the fastest according to our benchmarks

Basilisk is the only Python type checker with a perfect score on the official python/typing conformance suite: 100.0% (141/141 files, 970 required errors caught, 0 false positives), measured by the real upstream harness on the wheel-installed CLI in its default config.

And it is the fastest checker we’ve measured — median cold full-file check, from scratch:

Type checker	Median cold check
⚡ Basilisk	10 ms
zuban	28 ms
ty	40 ms
Pyrefly	110 ms
Pyright	573 ms
mypy	574 ms

Median cold full-file check across 26 single-construct typing-spec stress fixtures on an Apple M4 Max — lower is better. Basilisk’s warm re-check drops to ~4 ms. Every figure is produced by hyperfine and committed per machine, so nothing here is hand-typed. Clone the repo, run make bench on your own hardware, and send us the CSV — independent audits are welcome. Full benchmarks & methodology →

Everything in one extension

One extension replaces Pylance and gives you the whole workflow — no Node.js, no Python runtime, no pip, no npm. A single bundled Rust binary drives it all:

• Strict-by-default diagnostics — inline as you type, incremental analysis powered by Salsa (the rust-analyzer engine)
• Autocomplete, hover, go-to-definition, find references, rename
• Refactoring code actions — extract, inline, move symbol, organize imports
• Integrated debugging — F5 to debug via bundled debugpy; no separate extension
• Integrated profiling — CPU heat map, flame graph, and a memory dashboard with leak detection
• Activity panel — module tree with per-module type-health coverage, plus feature toggles
• Inlay hints and Ruff formatting/import-organization, built in
• Standard-library types from typeshed — a complete stdlib/ snapshot is compiled into the binary, so hover and diagnostics work offline with no configuration

Every diagnostic teaches: rustc-style output with a help, a note, and a link to a per-rule explainer, so a red squiggle always tells you why. Basilisk starts strict and stays strict — the unconfigured default enables the complete typing-spec rule set, and strictness is dialled per rule, never by a mode.

Install

Editor extension — install Basilisk from the VS Code Marketplace or Open VSX (Cursor, Windsurf, and other forks read Open VSX). The Basilisk binary is bundled for macOS (Apple Silicon), Linux (x86_64, aarch64), and Windows (x86_64, aarch64) — nothing else to install. Zed and Neovim 0.10+ extensions are available too.

CLI — on PyPI as basilisk-python; the installed command is basilisk:

uv tool install basilisk-python     # or: pipx install basilisk-python, pip install basilisk-python

Also via Homebrew (brew install Nimblesite/tap/basilisk), Scoop (scoop bucket add nimblesite https://github.com/Nimblesite/scoop-bucket && scoop install basilisk), and GitHub Releases. Every channel ships the same single Rust CLI, built from this repository at the same version, with no runtime dependencies. Point basilisk.executablePath at your own build to have the extension use it. Full options: install guide.

Try it

The examples/ folder has ready-to-go Python files:

basilisk check   examples/bad.py    # 8 typing-spec errors — always on, no config needed
basilisk analyze examples/bad.py    # the opt-in strictness warnings on the same file
basilisk analyze examples/good.py   # clean, even at full strictness
basilisk check   examples/mixed.py  # one real type error
basilisk check   examples/          # the whole folder at once

Machine-readable output for CI and tooling:

basilisk check path/to/your_code.py --output json --color never

The two commands read one rule universe split by provenance (CHKARCH-COMMANDS): check reports the pep-tagged typing-spec rules and nothing else — that set is always on, and while a config table may grade one of them down to warning/info, none may switch it off. analyze reports the non-pep house rules, which stay silent until a table selects them. Only analyze emits BSK- diagnostics.

Standard-library types, always offline

Basilisk resolves the standard library from typeshed, and checking never downloads anything. Out of the box it uses the complete typeshed stdlib/ snapshot compiled into the binary, reporting the source as unpinned — so stdlib types work on a plane, behind a firewall, or in an air-gapped CI runner, with no configuration.

Pin an exact commit with typeshed-commit = "<40-char sha>" under [tool.basilisk]. A pin does exactly one thing: it verifies, offline, that the typeshed tree in the local store hashes to that commit. If the commit is not on this machine the run fails hard with NO SOURCE rather than substituting another source — bring it down first with basilisk typeshed download (with no --commit it downloads the latest and writes the pin for you), or use the editor's Download latest button. Alternatively, point typeshed-path at your own typeshed tree. Full options: configuration guide.

Development

cargo build          # build all crates
cargo test           # run all tests
cargo clippy         # lint (zero warnings policy)
cargo fmt            # format

Rust 1.87+ required.

Contributing

Basilisk is built by a human + AI partnership, with the work split on purpose. See CONTRIBUTING.md — For Humans (testing, code-quality review, conformance/security audits, IDE feature parity, sharpening the AI instructions) and For AI (the technical execution, under the standing rules in CLAUDE.md).

Acknowledgments

Basilisk builds on the open-source community — with thanks to:

• Astral — Ruff, whose parser, AST, and formatter crates Basilisk embeds (MIT). The foundation we rely on most.
• typeshed — standard-library type stubs (Apache-2.0, with MIT-licensed parts).
• Salsa — incremental query engine.
• Rayon — data parallelism.
• tower-lsp — LSP scaffolding.
• debugpy — debug adapter (bundled in the VS Code extension).
• The python/typing conformance suite.

Full component list, selected licenses, and required notices: NOTICES and RUST-DEPENDENCY-LICENSES. Each published artifact carries its own copies: the VSIX ships Rust notices in RUST-DEPENDENCY-LICENSES, npm notices in VSCODE-DEPENDENCY-LICENSES, and debugpy's license and ThirdPartyNotices.txt inside bundled/debugpy; the wheel carries the complete locked notices in its .dist-info/licenses/ directory.

---

License

Basilisk source code is MIT licensed. Binary distributions also contain third-party components under the licenses shipped beside each artifact.

Built by NIMBLESITE PTY LTD.