Install & Compatibility
Where this runs
tested against v7.35.1.20260826 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.000s · 18.2MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 1.6s · import 0.000s · 19MB
16MB installed
● package 16MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
message
✓ from google-stubs import message
✗ from google-stubs import message
This quickstart demonstrates how `types-protobuf` provides static type checking for code interacting with `google.protobuf` messages. It includes a simulated custom message type (which would typically be generated from a `.proto` file) and usage of a well-known type. With `types-protobuf` installed, type checkers can verify argument types, attribute access, and return types.
import os
from google.protobuf.timestamp_pb2 import Timestamp # A well-known type
# --- Simulate generated _pb2.py content for a custom message ---
# In a real scenario, this would come from `my_message_pb2.py`
# generated by `protoc --python_out=. my_message.proto`
# my_message.proto content:
# syntax = "proto3";
# package mypackage;
# message MyMessage {
# string name = 1;
# int32 id = 2;
# repeated string tags = 3;
# }
# Simplified representation for quickstart (type checkers would use real stubs)
class MyMessage:
name: str
id: int
tags: list[str]
def __init__(self, name: str = '', id: int = 0, tags: list[str] | None = None) -> None:
self.name = name
self.id = id
self.tags = tags if tags is not None else []
def SerializeToString(self) -> bytes:
return b""
@classmethod
def ParseFromString(cls, serialized_data: bytes) -> 'MyMessage':
return cls()
# --- End simulated content ---
def process_message(msg: MyMessage) -> str:
"""Processes a custom protobuf message with type hints."""
print(f"Processing Message: Name={msg.name}, ID={msg.id}")
return f"Message with {len(msg.tags)} tags processed."
def get_current_timestamp() -> Timestamp:
"""Gets the current UTC timestamp using google.protobuf.Timestamp."""
ts = Timestamp()
ts.GetCurrentTime()
return ts
# Example Usage:
my_instance = MyMessage(name="ExampleUser", id=42, tags=["dev", "python"])
result = process_message(my_instance)
print(result)
timestamp_obj = get_current_timestamp()
print(f"Current UTC Timestamp: {timestamp_obj}")
Debug
Known issues
breakingChanges in `.proto` schema definitions (e.g., field renumbering, removal, or type alteration) can lead to runtime deserialization failures and will cause type checking errors if not properly managed. This is a fundamental aspect of Protobuf evolution, and `types-protobuf` will reflect these underlying API changes.fixUse a robust schema evolution strategy (e.g., deprecate fields instead of deleting, avoid renumbering, maintain compatibility across versions). Tools like `buf` can help lint `.proto` files for breaking changes.
affects: All versions of protobuf and types-protobuf
gotcha`types-protobuf` is a partial stub package, meaning not all annotations for the `protobuf` library might be present. You might encounter `Missing type annotation` errors for some less common parts of the API.fixIf you encounter missing annotations, consider contributing to the `typeshed` project where `types-protobuf` stubs are maintained. For immediate local fixes, you can use `type: ignore` or local stub files.
affects: All versions
gotchaA mismatch between the installed `types-protobuf` version and the `protobuf` runtime library version can lead to incorrect type checking results. The stubs are generated against specific runtime versions (e.g., `protobuf~=6.32.1`).fixEnsure that `types-protobuf` and `protobuf` versions are compatible. Typeshed recommends pinning stub packages to a known good version (e.g., `types-protobuf==X.Y.Z.build`) or aligning version bounds (e.g., `protobuf>=A.B.C,<A.B.D` and `types-protobuf>=A.B.C,<A.B.D`).
affects: All versions
gotchaThe handling of `Optional[type]` for protobuf wrapper classes (like `StringValue` or `Int32Value`) can be a source of type errors. In older `proto3` definitions or with specific `mypy-protobuf` configurations, values like `StringValue(value=None)` might pass at runtime but fail type checking if the stub expects `str` instead of `Optional[str]`.fixEnsure consistency in how `None` values are handled. If using `mypy-protobuf` for generating custom stubs, check `relax_strict_optional_primitives` options. For well-known wrapper types, refer to `typeshed`'s latest stubs and `protobuf` documentation on explicit presence.
affects: Versions prior to `protobuf` edition 2023's explicit presence default.
breakingThe `ModuleNotFoundError: No module named 'google'` indicates that the 'protobuf' runtime library itself is not installed or not accessible in the Python environment. `types-protobuf` provides type stubs for the 'protobuf' library, but it does not install the runtime library itself, which is a mandatory dependency.fixEnsure the `protobuf` package is installed in your environment (e.g., `pip install protobuf`). Verify that the Python environment where `types-protobuf` is used also has `protobuf` installed and accessible.
affects: All versions
breakingThe `protobuf` runtime library, which provides the `google.protobuf` package, must be installed for any Protobuf-related code to run. `types-protobuf` only provides type stubs and does not install the runtime library.fixEnsure the `protobuf` library is installed in your environment (e.g., `pip install protobuf`). Verify that the Python environment running the script has `protobuf` accessible.
affects: All versions
Upgrade
Version history
7.35.1.20260826latest on PyPI · released Aug 26, 2026
Audit
Dependencies
protobufrequiredProvides runtime functionality for which these stubs offer type hints. The stubs are designed for `protobuf~=6.32.1`.