{"id":1297,"library":"mypy-protobuf","title":"Mypy Protobuf Stubs Generator","description":"mypy-protobuf is a Python library and `protoc` plugin that generates mypy stub files (.pyi files) from Protocol Buffer (.proto) specifications. It ensures type safety for Python code interacting with protobuf messages and gRPC services, providing more accurate and detailed type information than the standard `protoc --pyi_out` option. Currently at version 5.0.0, it maintains an active release cadence with frequent updates.","status":"active","version":"5.0.0","language":"en","source_language":"en","source_url":"https://github.com/nipunn1313/mypy-protobuf","tags":["mypy","protobuf","type hints","static analysis","codegen","grpc"],"install":[{"cmd":"pip install mypy-protobuf","lang":"bash","label":"Install mypy-protobuf"}],"dependencies":[{"reason":"The Protocol Buffers compiler is required to generate Python code and mypy stubs. Version >= 32.0 is recommended for mypy-protobuf 5.x.","package":"protoc","optional":false},{"reason":"Python bindings for Protocol Buffers are required at runtime. Version >= 6.32 is recommended and should match your protoc version.","package":"python-protobuf","optional":false},{"reason":"A static type checker is needed to consume the generated .pyi stubs. Version >= 1.14.0 is recommended.","package":"mypy","optional":false},{"reason":"Type stubs for the google.protobuf library are often required by mypy. Version >= 6.32 is recommended.","package":"types-protobuf","optional":false},{"reason":"Required if generating stubs for gRPC services.","package":"grpcio","optional":true},{"reason":"Required if generating stubs for gRPC services (for code generation, not mypy-protobuf runtime).","package":"grpcio-tools","optional":true},{"reason":"Type stubs for grpcio are required if generating gRPC stubs and typechecking them.","package":"types-grpcio","optional":true}],"imports":[],"quickstart":{"code":"mkdir -p project/proto project/output\n\ncat <<EOF > project/proto/example.proto\nsyntax = \"proto3\";\n\npackage example;\n\nmessage MyMessage {\n  string name = 1;\n  int32 id = 2;\n  bool is_active = 3;\n}\nEOF\n\n# Ensure protoc and protoc-gen-mypy are in PATH or specify full paths\n# protoc --plugin=protoc-gen-mypy=/path/to/protoc-gen-mypy ...\nprotoc --python_out=project/output --mypy_out=project/output project/proto/example.proto\n\n# Expected output will include example_pb2.py and example_pb2.pyi in project/output\n\ncat <<EOF > project/main.py\nfrom project.output import example_pb2\n\ndef process_message(msg: example_pb2.MyMessage) -> None:\n    print(f\"Processing: {msg.name} (ID: {msg.id}, Active: {msg.is_active})\")\n\n# Correct usage\nmy_msg = example_pb2.MyMessage(name=\"Test\", id=123, is_active=True)\nprocess_message(my_msg)\n\n# Incorrect usage (mypy would catch this)\n# invalid_msg = example_pb2.MyMessage(name=123, id=\"abc\")\n# process_message(invalid_msg)\nEOF\n\n# Run mypy to type-check the project\nmypy project","lang":"bash","description":"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."},"warnings":[{"fix":"Consult 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.","message":"mypy-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.","severity":"breaking","affected_versions":"3.4.0 and later"},{"fix":"Ensure 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.","message":"Python 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.","severity":"breaking","affected_versions":"2.10, 3.5.0, 3.7.0 and later"},{"fix":"Only 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.","message":"The `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.","severity":"gotcha","affected_versions":"All versions with `readable_stubs` option"},{"fix":"Ensure 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 ...`.","message":"To 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'.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-08T00:00:00.000Z","next_check":"2026-07-07T00:00:00.000Z"}