Install & Compatibility
Where this runs
No compatibility data collected yet for this library.
Code
Verified usage
This quickstart demonstrates how to generate Python protobuf code and mypy stubs from a `.proto` file, and then use `mypy` to type-check Python code that consumes these generated types. It first creates a sample `.proto` file, then uses `protoc` with the `mypy-protobuf` plugin to generate the `.py` and `.pyi` files. Finally, it provides a Python script that imports and uses the generated message, along with a `mypy` command to verify type correctness.
mkdir -p project/proto project/output
cat <<EOF > project/proto/example.proto
syntax = "proto3";
package example;
message MyMessage {
string name = 1;
int32 id = 2;
bool is_active = 3;
}
EOF
# Ensure protoc and protoc-gen-mypy are in PATH or specify full paths
# protoc --plugin=protoc-gen-mypy=/path/to/protoc-gen-mypy ...
protoc --python_out=project/output --mypy_out=project/output project/proto/example.proto
# Expected output will include example_pb2.py and example_pb2.pyi in project/output
cat <<EOF > project/main.py
from project.output import example_pb2
def process_message(msg: example_pb2.MyMessage) -> None:
print(f"Processing: {msg.name} (ID: {msg.id}, Active: {msg.is_active})")
# Correct usage
my_msg = example_pb2.MyMessage(name="Test", id=123, is_active=True)
process_message(my_msg)
# Incorrect usage (mypy would catch this)
# invalid_msg = example_pb2.MyMessage(name=123, id="abc")
# process_message(invalid_msg)
EOF
# Run mypy to type-check the project
mypy project
protoc-gen-mypy --version
Debug
Known issues
breakingmypy-protobuf versions have historically updated their minimum required `protobuf` major version without a corresponding major version bump in `mypy-protobuf` itself. For example, `mypy-protobuf 3.4.0` implicitly required `protobuf 4.x.x`, breaking compatibility with existing `protobuf 3.x.x` installations. Always check the PyPI project page for the latest compatible `protoc` and `python-protobuf` versions for your `mypy-protobuf` release.fixConsult the `mypy-protobuf` PyPI page or GitHub README for the exact `protoc` and `python-protobuf` version requirements for your installed `mypy-protobuf` version. Upgrade or downgrade `protobuf` components accordingly.
affects: 3.4.0 and later
breakingPython version support has been dropped in several major releases. `mypy-protobuf 2.10` was the last version to support targeting Python 2.7. `mypy-protobuf 3.5.0` dropped support for Python 3.7. Python 3.8 testing was dropped in `mypy-protobuf 3.7.0` due to incompatibilities with newer `protobuf` versions.fixEnsure your Python environment meets the minimum version requirements for the `mypy-protobuf` version you are using. For version 5.0.0, Python >= 3.9 is required to run the plugin itself.
affects: 2.10, 3.5.0, 3.7.0 and later
gotchaThe `readable_stubs` option (if enabled) can generate stubs that are easier to read but might not pass `mypy`, particularly in cases of name collisions between global identifiers and field names. By default, `mypy-protobuf` uses fully qualified imports and mangled global identifiers to prevent such collisions.fixOnly use `readable_stubs` if you are comfortable with the potential for type-checking failures and are willing to resolve them manually. For stricter type checking, rely on the default stub generation behavior.
affects: All versions with `readable_stubs` option
gotchaTo run `protoc` with the `mypy-protobuf` plugin, the `protoc-gen-mypy` executable (installed by `pip install mypy-protobuf`) must be discoverable by `protoc`. This typically means it needs to be in your system's `PATH` environment variable. If it's not, `protoc` will report an error like 'plugin not found'.fixEnsure your Python environment's `bin` directory (where `protoc-gen-mypy` is installed) is included in your system's `PATH`. Alternatively, explicitly provide the full path to the plugin when invoking `protoc`: `protoc --plugin=protoc-gen-mypy=/path/to/protoc-gen-mypy ...`.
affects: All versions
gotchaWhen integrating `mypy-protobuf` or any Python library into scripts, ensure that shell commands (like `mkdir`, `cp`, `rm`) are properly separated from Python code. Attempting to execute shell commands directly within a Python script will result in a `SyntaxError`.fixReview your script (`script.py` in this case). If it's meant to be a Python script, use Python's `os` module (e.g., `os.makedirs`) or `subprocess` module to execute shell commands. If it's a shell script, ensure it's executed by a shell interpreter (e.g., `bash script.sh`) and not the Python interpreter (e.g., `python script.py`).
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'mypy-protobuf'
The 'mypy-protobuf' package has not been installed in the Python environment where the code is being run or where 'protoc' is trying to find its plugin.
fixRun `pip install mypy-protobuf` to install the library.
The command "protoc-gen-mypy" is either misspelled or could not be found.
The 'protoc' compiler cannot locate the 'protoc-gen-mypy' plugin executable in your system's PATH, or the plugin itself failed to execute.
fixEnsure the Python environment's 'bin' (or 'Scripts' on Windows), where 'protoc-gen-mypy' is installed, is in your system's PATH. Alternatively, specify the full path to the plugin in your 'protoc' command: `protoc --plugin=protoc-gen-mypy=/path/to/protoc-gen-mypy --mypy_out=output_dir your_proto.proto`.
Skipping analyzing "google": module is installed, but missing library stubs or py.typed marker [import-untyped]
Mypy cannot find type stubs for the standard `google.protobuf` library, which `mypy-protobuf` generated stubs depend on for full type checking. This usually means the `types-protobuf` package is not installed or discoverable.
fixInstall the `types-protobuf` package: `pip install types-protobuf`. Ensure `types-protobuf`'s version is compatible with your `protobuf` version.
error: Incompatible types in assignment (expression has type "V", variable has type "MyEnum")
Older versions of `mypy-protobuf` or specific configurations might generate enum stubs using a `NewType` alias (e.g., `MyEnum.V`) for stricter typing, which can lead to type checker errors if the explicit `NewType` constructor is not used.
fixWhen assigning enum values, explicitly use the `NewType` constructor (e.g., `my_variable = MyEnum.V(123)`). Updating `mypy-protobuf` and `python-protobuf` to their latest compatible versions often includes improvements to enum typing.
Upgrade
Version history
5.0.0latest on PyPI · released Jan 13, 2026
Audit
Dependencies
protocrequiredThe Protocol Buffers compiler is required to generate Python code and mypy stubs. Version >= 32.0 is recommended for mypy-protobuf 5.x.
python-protobufrequiredPython bindings for Protocol Buffers are required at runtime. Version >= 6.32 is recommended and should match your protoc version.
mypyrequiredA static type checker is needed to consume the generated .pyi stubs. Version >= 1.14.0 is recommended.
types-protobufrequiredType stubs for the google.protobuf library are often required by mypy. Version >= 6.32 is recommended.
grpciooptionalRequired if generating stubs for gRPC services.
grpcio-toolsoptionalRequired if generating stubs for gRPC services (for code generation, not mypy-protobuf runtime).
types-grpciooptionalType stubs for grpcio are required if generating gRPC stubs and typechecking them.