protobuf

library7.36.0pypypi✓ verified 10d ago

Google's language-neutral, platform-neutral mechanism for serializing structured data. You define message schemas in .proto files, compile them with protoc into _pb2.py modules, and use the runtime library (google.protobuf.*) to serialize, deserialize, and manipulate messages. Currently at version 7.34.1 (Python major version bumped from 6.x to 7.x in the 7.34.0 release). Releases follow a quarterly cadence; breaking major-version bumps are targeted at Q1 of each year.

serialization gcp data

pip install protobuf

package ↗homepage ↗

INSTALL

IMPORT

SIG · PROTOBUF

protobuf

serializationpythonv7.36.0

Install

3.1s avg

Import

65ms

Disk

49MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v7.36.0 · 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

musl

py 3.10–3.910 runs

installs and imports cleanly · install 0.0s · import 0.066s · 50.4MB

glibc

py 3.10–3.910 runs

installs and imports cleanly · install 3.1s · import 0.064s · 46MB

49MB installed

● package 49MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

json_format

✓ from google.protobuf import json_format

✗ from google.protobuf import json_format

MessageToJson

✓ from google.protobuf.json_format import MessageToJson

✗ from google.protobuf import json_format

ParseDict

✓ from google.protobuf.json_format import ParseDict

✗ from google.protobuf import json_format

Serialize and deserialize a message using a well-known type (no custom .proto compilation required). Demonstrates SerializeToString / ParseFromString and JSON round-trip.

# pip install protobuf # No custom .proto needed for this example — uses the built-in Timestamp well-known type. from google.protobuf.timestamp_pb2 import Timestamp from google.protobuf import json_format import time # --- Create and populate a message --- ts = Timestamp() ts.GetCurrentTime() # sets seconds + nanos to now # --- Binary serialization round-trip --- binary = ts.SerializeToString() ts2 = Timestamp() ts2.ParseFromString(binary) # returns number of bytes consumed assert ts == ts2, "Round-trip failed" # --- JSON serialization --- json_str = json_format.MessageToJson(ts) print("JSON:", json_str) ts3 = json_format.Parse(json_str, Timestamp()) assert ts == ts3, "JSON round-trip failed" print("All assertions passed.") # --- Typical workflow with a custom proto --- # 1. Write my_message.proto: # syntax = "proto3"; # message Person { string name = 1; int32 id = 2; } # 2. Compile: # protoc --python_out=. my_message.proto # 3. Use generated code: # from my_message_pb2 import Person # p = Person(name='Alice', id=42) # data = p.SerializeToString() # p2 = Person() # p2.ParseFromString(data)

protoc --version

Debug

Known issues

breakingPython major version bumped to 7 with the 7.34.0 release (previous line was 6.x). Boolean values are now rejected when setting enum or int fields—the API raises a TypeError instead of implicitly converting them. The deprecated float_precision option in json_format and float_format/double_format in text_format were also removed.

fix

Upgrade to >=7.34.1. Replace boolean literals with int values when assigning to int/enum fields (e.g. use 1 instead of True). Remove any use of float_precision= in json_format.MessageToJson() and float_format=/double_format= in text_format calls.

affects: <7.34.0

breakingGencode/runtime version mismatch raises google.protobuf.runtime_version.VersionError at import time. Generated _pb2.py files embed a minimum runtime version; loading them against an older installed protobuf package fails hard. This is especially common when grpcio-tools generates code with a newer bundled protoc than the protobuf runtime you have installed.

fix

Always regenerate _pb2.py files with the same protoc version as your installed runtime. Pin grpcio-tools and protobuf together in requirements. Generated code for major version V works only with runtime major versions V and V+1.

affects: >=4.26.0

breakingPython 4.21.0 (2022) switched the C extension to the upb library. Sharing message objects between Python and C++ (e.g. via SWIG or pybind11) stopped working by default. Libraries like older TensorFlow that relied on this crash with AttributeError on import.

fix

Set PROTOCOL_BUFFERS_PYTHON_IMPLEMENTATION=cpp and install the Python/C++ extension if you need Python↔C++ message sharing, or upgrade dependent libraries (e.g. TF >=2.12) that have been updated to use upb.

affects: >=4.21.0

breakingmessage.UnknownFields() was deprecated in v5.25 and removed in v6.26+. Calling it raises AttributeError.

fix

Replace msg.UnknownFields() with: from google.protobuf import unknown_fields; unknown_fields.UnknownFieldSet(msg)

affects: >=5.26.0

gotchaAccessing an undefined key in a proto map field creates that key with a zero/false/empty value (defaultdict-like behaviour). This silently mutates the message during read-only access, which can cause unexpected serialization differences and test failures.

fix

Use 'key in msg.map_field' to check existence before accessing. Use msg.map_field.get(key) where available, or msg.map_field.GetOrCreate(key) for message-typed maps.

affects: all

gotchaThe Python package name declared in a .proto file does NOT affect generated Python module names or import paths. Python packages are determined purely by directory structure relative to the --proto_path flag. Hyphens in filenames are silently converted to underscores (foo-bar.proto → foo_bar_pb2.py).

fix

Pass --proto_path rooted at the common ancestor of all .proto files. Ensure generated _pb2.py files are on PYTHONPATH. Well-known google/* protos must always be imported as 'google/protobuf/...' in .proto files.

affects: all

gotchaDo not subclass generated message classes. They use a metaclass and internal descriptor machinery that makes subclassing produce subtle bugs ('fragile base class' problems). The official docs explicitly warn against it.

fix

Compose rather than inherit: hold a proto message as a field, or use helper functions. For custom serialization logic, wrap the message in a plain Python class.

affects: all

Upgrade

Version history

7.36.0latest on PyPI · released Aug 20, 2026

Audit

Dependencies

grpcio-toolsoptionalProvides the grpc_tools.protoc Python interface to the protoc compiler for generating _pb2.py and _pb2_grpc.py files without installing a system protoc.

Agent activity

69 hits · last 30 days

node