mypy-protobuf

What it is and what it does

mypy-protobuf is a protoc plugin that generates mypy-compatible stub files from .proto definitions. Instead of relying on the protobuf compiler's built-in pyi generator, it produces stubs with more precise type information—including correctly typed HasField, WhichOneof, and ClearField methods; gRPC service and client stubs; and field presence awareness. It also preserves comments from .proto files as docstrings and marks deprecated items with @warnings.deprecated.

The plugin installs as a protoc-gen-mypy executable that integrates into the protoc build pipeline. You run it alongside the standard Python code generator, and it outputs .pyi files that type checkers like mypy and pyright can use to validate code that imports and uses the generated protobuf messages. It requires protoc >= 32.0, python-protobuf >= 6.32, and Python >= 3.9 to run; downstream type checking also needs mypy >= v1.14.0 or pyright >= 1.1.383.

Use it for:

• Add static type checking to a Python project that uses protobuf messages, catching type errors at development time.
• Generate gRPC service stubs with full type annotations for both server and client code.
• Preserve proto file documentation as docstrings in generated stubs so IDEs and type checkers display help text.
• Enforce field presence constraints in constructors and HasField calls by generating precise union and literal types.
• Migrate a large protobuf codebase from untyped to typed Python incrementally using stub-based type checking.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

Generates mypy-compatible stub files (.pyi) from protobuf specifications, enabling static type checking of protobuf-generated Python code.

Yes. The package is actively maintained, has no known vulnerabilities, low install friction, and solves a real problem—enabling static type checking on protobuf code where the built-in pyi generator falls short. Install it if you use protobuf in Python and want mypy or pyright to catch type errors in your message handling and gRPC calls. Verify that your protoc and protobuf versions match the required minimums (>= 32.0) before installing.

Install

mypy-protobuf on PyPI

pip install mypy-protobuf

uv add mypy-protobuf

poetry add mypy-protobuf

Installing mypy-protobuf

Before you install

Low friction: pure Python wheel with only two runtime dependencies (protobuf and types-protobuf). Actively maintained with a recent release; last commit 2026-04-28. Requires protoc >= 32.0 and Python >= 3.9 to run the plugin itself.

License in practice

Apache License 2.0 is permissive; you can use this package in commercial and private projects with minimal restrictions, provided you include a copy of the license and note any modifications.

Quickstart

pip install mypy-protobuf

protoc --python_out=output/location --mypy_out=output/location your_file.proto

Requires protoc >= 32.0 installed and on PATH, and python-protobuf >= 6.32 matching your protoc release. Plugin runs on Python >= 3.9.

Verify before relying

• Whether the generated stubs work correctly with mypy >= v1.14.0 or pyright >= 1.1.383 in your specific codebase.
• Compatibility with grpc code generation (requires grpcio >= 1.70, grpcio-tools >= 1.70, types-grpcio >= 1.0.0.20251009).

Package facts

Evidence: mypy_protobuf-5.1.0-py3-none-any.whl

Keywords: mypy, proto, dropbox

Tags

More Build Tools packages