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.

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

100.0% PEP conformance — 141 of 141 tests in the official python/typing conformance suite (commit 6ef9f77), 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 →

Install

The CLI is on PyPI as basilisk-python — install it as a standalone tool; the installed command is basilisk:

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

Also available via Homebrew (brew tap Nimblesite/tap && brew install basilisk), Scoop, and GitHub Releases — every channel ships the same single Rust CLI, built from this repository at the same version, with no runtime dependencies. 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

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, online or offline

Basilisk resolves the standard library from typeshed. By default it verifies python/typeshed@main over HTTPS once per run, gates and caches the archive for up to 24 hours, and reports the source as unpinned. With no network — or on any download failure — it falls back to the complete typeshed stdlib/ snapshot compiled into the binary, so stdlib types still work offline.

Pin an exact commit with typeshed-commit = "<40-char sha>" under [tool.basilisk]; its cache is re-hashed on every reuse and remains until eviction or caching is disabled. The pin fails closed rather than substituting another commit. Alternatively, point typeshed-path at your own typeshed tree. Full options: configuration guide.

Editors

One extension, the whole workflow: strict-by-default diagnostics, autocomplete, hover, go-to-definition, refactoring code actions, debugging, and profiling. No Node.js or Python runtime — a single Rust binary drives it all.

• VS Code, Cursor & Windsurf — install from Open VSX
• Zed • Neovim 0.10+

Every diagnostic teaches: rustc-style output with a help, a note, and a link to a per-rule explainer. See the full diagnostic reference and the install 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.

---

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.