Skip to content

Zuban: Mypy-Compatible Python Type Checker

by Tim Hopper
Type Checking

Zuban is a static type checker and language server for Python, written in Rust by David Halter, author of Jedi (the longstanding Python autocompletion library) and parso. It runs in two modes: zuban mypy (aliased as zmypy) behaves as a mypy-compatible drop-in, and zuban check applies a pyright-style inference strategy.

Zuban launched as open source under AGPL-3.0 in September 2025, with a paid commercial license available for organizations that cannot accept AGPL’s source-disclosure requirements. That licensing split is the tool’s most load-bearing distinguishing factor: it funds full-time development in a way that MIT-licensed competitors cannot, but it also rules Zuban out for many proprietary codebases unless the team buys a commercial license.

When to use Zuban

Zuban fits teams already running mypy who want the same semantics and error messages at a fraction of the runtime cost. The zmypy mode reads mypy.ini, setup.cfg, and [tool.mypy] in pyproject.toml unchanged, so a CI step can be swapped one command at a time. Teams that value typing spec conformance over raw speed may also consider Zuban over ty and Pyrefly, which trade conformance for other design goals.

Zuban is a poor fit for closed-source commercial work that cannot absorb AGPL-3.0 obligations and will not buy a commercial license. It is also still early: the LSP covers the common features but lags ty and Pyrefly on editor polish. For a broader comparison of all five major type checkers, see How do Python type checkers compare?.

Key Features

  • Two modes: zuban mypy (or the shorter zmypy) behaves like mypy, including config and error messages. zuban check runs a pyright-compatible inference strategy that analyzes unannotated code.
  • Performance: the project benchmarks 20-200x faster than mypy on comparable workloads, using roughly half the memory of ty and Pyrefly.
  • Mypy test-suite compatibility: passes over 95% of mypy’s own relevant test suite, which is the highest mypy-compatibility score among the new Rust-based checkers.
  • Typing spec conformance: scores 96.4% (134/139 files) on the official typing conformance suite as of March 2026, second only to pyright (97.8%).
  • Language server: zuban server provides diagnostics, completions, go-to-definition, find references, rename, hover, and document highlights over LSP.
  • Parser lineage: shares design and contributors with Jedi, which has shipped autocompletion for Python for over a decade.

Configuration

In zmypy mode, Zuban reads mypy’s configuration verbatim from mypy.ini, .mypy.ini, setup.cfg, or pyproject.toml under [tool.mypy]:

pyproject.toml
[tool.mypy]
python_version = "3.12"
strict = true
warn_unused_ignores = true

In zuban check mode, Zuban reads its own [tool.zuban] table:

pyproject.toml
[tool.zuban]
python-version = "3.12"

Installation and Usage 

# Install with uv
uv add --dev zuban

# Or run without installing
uvx zuban check src/

# Mypy-compatible mode (reads mypy config)
uv run zmypy src/

# pyright-style mode
uv run zuban check src/

# Start the LSP server for editor integration
uv run zuban server

Zuban is also published on PyPI and ships pre-built wheels for macOS, Linux, and Windows on both x86_64 and ARM64.

Editor Integration

Zuban’s LSP is usable from any editor that supports the protocol. The project documents configurations for VS Code, Neovim, and Zed; Emacs and Helix work through standard LSP clients. Point the client at the zuban server command to start.

Positron (the Posit data-science IDE) evaluated Zuban as a candidate default language server in March 2026 but selected Pyrefly instead, citing Zuban’s smaller LSP feature surface and earlier maturity stage.

Pros

  • Order-of-magnitude speedup over mypy while preserving mypy’s config, diagnostics, and error codes
  • Second-highest typing spec conformance of any open-source Python type checker (behind only pyright)
  • Shares parser and design heritage with Jedi, giving it a mature foundation for LSP features
  • Half the memory footprint of ty and Pyrefly on comparable workloads
  • Single Rust binary with no Node.js or Python runtime dependency

Cons

  • AGPL-3.0 license creates obligations that many proprietary projects cannot accept without a commercial license
  • LSP feature surface is narrower than ty or Pyrefly; some editor features (for example, inlay hints) are not yet implemented
  • Maintained largely by one person, which makes bus-factor a real consideration for teams adopting it at scale
  • Smaller community and fewer third-party integrations than mypy, pyright, or ty
  • Conformance numbers above 95% are self-reported and still settling as the project matures

Comparison to Other Tools

Zuban’s closest peer is mypy. The two share configuration, diagnostics, and error codes; Zuban is an order of magnitude faster and written in a more maintainable codebase. Against ty and Pyrefly, Zuban has higher typing-spec conformance and a lighter memory footprint but narrower LSP features and tighter licensing constraints. Against pyright, Zuban matches conformance closely and ships a faster, self-contained binary but lacks pyright’s Microsoft-backed editor ecosystem.

Zuban is in active development. Performance numbers and conformance scores are self-reported and shifting as the project matures. Verify claims against the current release before depending on them for a migration decision.

Learn More

Last updated on
Wheel

Please submit corrections and feedback...