Zuban: Mypy-Compatible Python Type Checker

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 has two main modes: zuban mypy (aliased as zmypy) aims for mypy compatibility, while zuban check defaults to checking unannotated function bodies and inferring return types.

Zuban is dual-licensed under AGPL-3.0 and a commercial license. Organizations should evaluate the license terms for their intended use.

When to use Zuban

Zuban suits projects evaluating a checker alongside mypy. zmypy supports mypy configuration, flags, and diagnostic codes, while the default mode offers additional inference. Compatibility is an aim rather than a guarantee: compare both tools on project code, especially where mypy plugins are required.

For a broader comparison, see How do Python type checkers compare?.

Key Features

• Two modes: zuban mypy or zmypy follows mypy-style checking; zuban check enables checking of unannotated bodies and return-type inference by default.
• Configuration compatibility: accepts mypy-style configuration and many mypy command-line flags, including --strict and --check-untyped-defs.
• Language server: zuban server provides diagnostics, completions, navigation, rename, hover, auto-imports, and inlay hints over LSP.
• Targeted suppressions: supports # zuban: ignore[assignment] and mypy-style # type: ignore[assignment].

Configuration

Zuban accepts mypy.ini, .mypy.ini, setup.cfg, and [tool.mypy] in pyproject.toml. zuban mypy selects mypy-compatible defaults; zuban check uses its default inference mode even when mypy configuration exists, unless --mode or a configuration setting selects another mode.

[tool.mypy]
python_version = "3.12"
strict = true

Zuban-specific settings use [tool.zuban]. Option names use mypy-style underscores:

[tool.zuban]
python_version = "3.12"
mode = "default"

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/

# Default inference mode
uv run zuban check src/

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

Zuban publishes prebuilt wheels on PyPI. Available architectures vary by operating system; check the release files for the target platform.

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.

Pros

• Accepts mypy-style configuration and diagnostic codes
• Offers separate mypy-compatible and inference-oriented modes
• Combines a type checker and language server in one executable

Cons

• General mypy plugin support is unavailable; framework behavior needs separate evaluation
• Unused # type: ignore comments are not reported, even with warn_unused_ignores
• AGPL-3.0 and commercial licensing differ from the MIT-licensed alternatives

See Zuban’s documented limitations.

Suppressions and Exit Codes

Use # zuban: ignore[assignment] or # type: ignore[assignment] for one diagnostic code. A bare ignore suppresses all type errors on its line. Existing suppressions should be reviewed during migration because unused ignores are not reported.

A successful check exits with 0; reported type errors exit with 1. Invalid CLI options exit with 2. Treat every nonzero exit as a failed CI check, since configuration failures can also terminate the process.

Comparison to Other Tools

Zuban’s closest configuration counterpart is mypy. Its default mode checks more unannotated code than mypy’s defaults, while zmypy keeps the mypy adoption model. Pyrefly, ty, and pyright use their own configuration and inference policies. Check migration-critical behavior with runnable project examples; a speed claim or conformance score does not establish compatibility.