{"id":257,"library":"protobuf","title":"Protocol Buffers (protobuf) for Python","description":"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.","status":"active","version":"7.34.1","language":"python","source_language":"en","source_url":"https://github.com/protocolbuffers/protobuf","tags":["serialization","grpc","binary-format","schema","google","rpc","protoc","code-generation"],"install":[{"cmd":"pip install protobuf","lang":"bash","label":"Runtime library only (most common)"},{"cmd":"pip install grpcio-tools","lang":"bash","label":"Includes protoc compiler plugin for gRPC projects"},{"cmd":"# Install the standalone protoc compiler (platform-specific)\n# macOS: brew install protobuf\n# Ubuntu: apt-get install -y protobuf-compiler\n# Or download from https://github.com/protocolbuffers/protobuf/releases","lang":"bash","label":"Install protoc compiler (required to generate _pb2.py files)"}],"dependencies":[{"reason":"Provides the grpc_tools.protoc Python interface to the protoc compiler for generating _pb2.py and _pb2_grpc.py files without installing a system protoc.","package":"grpcio-tools","optional":true}],"imports":[{"note":"Always import via google.protobuf package namespace. Direct attribute access on a bare import can fail if the google namespace package is split.","wrong":"import google.protobuf.json_format as jf; jf.MessageToJson(msg)","symbol":"MessageToJson / ParseDict","correct":"from google.protobuf import json_format\njson_format.MessageToJson(msg)\njson_format.ParseDict(d, MyMessage())"},{"note":"text_format lives under google.protobuf, not at the top level of the protobuf package.","symbol":"MessageToString / Parse (text format)","correct":"from google.protobuf import text_format\ntext_format.MessageToString(msg)\ntext_format.Parse(text, MyMessage())"},{"note":"Used for dynamic message creation and reflection; pool is a singleton—do not construct new ones unnecessarily.","symbol":"descriptor_pool / DescriptorPool","correct":"from google.protobuf import descriptor_pool\npool = descriptor_pool.Default()"},{"note":"Generated files always have the _pb2.py suffix. The proto package declaration does NOT affect Python module names—only directory structure matters.","wrong":"import my_message; msg = my_message.MyMessage()","symbol":"Generated message class (user proto)","correct":"# After: protoc --python_out=. my_message.proto\nfrom my_message_pb2 import MyMessage\nmsg = MyMessage(field1='hello', field2=42)"},{"note":"Well-known types ship with the runtime under google.protobuf.*_pb2. They must be imported as google.protobuf.* in .proto files too (e.g. import 'google/protobuf/timestamp.proto').","wrong":"from protobuf.timestamp_pb2 import Timestamp","symbol":"Well-known types (Timestamp, Duration, Any, Struct …)","correct":"from google.protobuf.timestamp_pb2 import Timestamp\nfrom google.protobuf.any_pb2 import Any"},{"note":"message.UnknownFields() was deprecated in v5.25 and removed in v6.26+. Use the unknown_fields module instead.","wrong":"msg.UnknownFields()","symbol":"UnknownFieldSet","correct":"from google.protobuf import unknown_fields\nunk = unknown_fields.UnknownFieldSet(msg)"}],"quickstart":{"code":"# pip install protobuf\n# No custom .proto needed for this example — uses the built-in Timestamp well-known type.\n\nfrom google.protobuf.timestamp_pb2 import Timestamp\nfrom google.protobuf import json_format\nimport time\n\n# --- Create and populate a message ---\nts = Timestamp()\nts.GetCurrentTime()          # sets seconds + nanos to now\n\n# --- Binary serialization round-trip ---\nbinary = ts.SerializeToString()\nts2 = Timestamp()\nts2.ParseFromString(binary)  # returns number of bytes consumed\nassert ts == ts2, \"Round-trip failed\"\n\n# --- JSON serialization ---\njson_str = json_format.MessageToJson(ts)\nprint(\"JSON:\", json_str)\n\nts3 = json_format.Parse(json_str, Timestamp())\nassert ts == ts3, \"JSON round-trip failed\"\nprint(\"All assertions passed.\")\n\n# --- Typical workflow with a custom proto ---\n# 1. Write my_message.proto:\n#      syntax = \"proto3\";\n#      message Person { string name = 1; int32 id = 2; }\n# 2. Compile:\n#      protoc --python_out=. my_message.proto\n# 3. Use generated code:\n#      from my_message_pb2 import Person\n#      p = Person(name='Alice', id=42)\n#      data = p.SerializeToString()\n#      p2 = Person()\n#      p2.ParseFromString(data)\n","lang":"python","description":"Serialize and deserialize a message using a well-known type (no custom .proto compilation required). Demonstrates SerializeToString / ParseFromString and JSON round-trip."},"warnings":[{"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.","message":"Python 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.","severity":"breaking","affected_versions":"<7.34.0"},{"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.","message":"Gencode/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.","severity":"breaking","affected_versions":">=4.26.0"},{"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.","message":"Python 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.","severity":"breaking","affected_versions":">=4.21.0"},{"fix":"Replace msg.UnknownFields() with: from google.protobuf import unknown_fields; unknown_fields.UnknownFieldSet(msg)","message":"message.UnknownFields() was deprecated in v5.25 and removed in v6.26+. Calling it raises AttributeError.","severity":"breaking","affected_versions":">=5.26.0"},{"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.","message":"Accessing 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.","severity":"gotcha","affected_versions":"all"},{"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.","message":"The 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).","severity":"gotcha","affected_versions":"all"},{"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.","message":"Do 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.","severity":"gotcha","affected_versions":"all"}],"env_vars":null,"last_verified":"2026-05-12T12:24:28.338Z","next_check":"2026-06-25T00:00:00.000Z","problems":[{"fix":"Install 'protoc' via a package manager (e.g., 'brew install protobuf' on macOS, 'sudo apt-get install protobuf-compiler' on Linux) or by downloading the pre-compiled binary from GitHub releases and manually adding its 'bin' directory to your system's PATH.","cause":"The Protocol Buffers compiler ('protoc') is either not installed on your system or its executable location is not included in your system's PATH environment variable.","error":"protoc: command not found"},{"fix":"Install the 'protobuf' Python package using 'pip install protobuf' or 'conda install protobuf' if you are using an Anaconda environment.","cause":"The Python 'protobuf' runtime library is not installed in your active Python environment.","error":"ModuleNotFoundError: No module named 'google.protobuf'"},{"fix":"Downgrade or upgrade the 'protobuf' package to a version compatible with your dependencies (e.g., 'pip install protobuf==3.20.0' for older TensorFlow versions), and regenerate '.proto' files if they were compiled with an incompatible 'protoc' version.","cause":"This error typically indicates a version incompatibility between your installed 'protobuf' Python package and other dependent libraries (like TensorFlow) or between generated code and the runtime library.","error":"AttributeError: module 'google.protobuf.descriptor' has no attribute '_internal_create_key'"},{"fix":"Downgrade the 'protobuf' package to a compatible version (e.g., 'pip install protobuf<7') or use a virtual environment to isolate conflicting dependencies until dependent packages update their version requirements.","cause":"Other installed packages (e.g., 'grpcio-status' or 'googleapis-common-protos') have declared a dependency on an older major version of 'protobuf' (e.g., '<7.0.0'), conflicting with a newly installed 'protobuf' 7.x.","error":"ERROR: pip's dependency resolver does not currently take into account all the packages that are installed. This behaviour is the source of the following dependency conflicts. grpcio-status X requires protobuf<7.0.0,>=6.31.1, but you have protobuf 7.34.0 which is incompatible."},{"fix":"Ensure the directory containing the generated '_pb2.py' files is on your Python path, or modify the imports in the generated files to be relative (e.g., 'from . import your_message_pb2'), or use a tool like 'fix-protobuf-imports'.","cause":"When '.proto' files are organized in nested directories, 'protoc' may generate absolute Python imports instead of relative ones, causing Python to fail to locate the generated '_pb2.py' modules within the package structure.","error":"ModuleNotFoundError: No module named 'your_message_pb2'"}],"ecosystem":"pypi","meta_description":null,"install_score":100,"install_tag":"verified","quickstart_score":80,"quickstart_tag":"verified","pypi_latest":null,"install_checks":{"last_tested":"2026-05-12","tag":"verified","tag_description":"installs cleanly on critical runtimes, fast import, recently tested","results":[{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.06,"mem_mb":2.7,"disk_size":"49.8M"},{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.06,"mem_mb":2.7,"disk_size":"19.4M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.04,"mem_mb":2.8,"disk_size":"45M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.04,"mem_mb":2.8,"disk_size":"20M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.09,"mem_mb":3,"disk_size":"52.3M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.1,"mem_mb":3,"disk_size":"21.7M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.08,"mem_mb":3.1,"disk_size":"48M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.07,"mem_mb":3.1,"disk_size":"23M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.08,"mem_mb":2.9,"disk_size":"53.0M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.07,"mem_mb":2.9,"disk_size":"13.6M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.07,"mem_mb":3,"disk_size":"49M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.08,"mem_mb":3,"disk_size":"14M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.07,"mem_mb":2.7,"disk_size":"52.7M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.07,"mem_mb":2.9,"disk_size":"13.2M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.07,"mem_mb":2.7,"disk_size":"48M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.07,"mem_mb":2.7,"disk_size":"14M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.06,"mem_mb":2.7,"disk_size":"49.3M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.06,"mem_mb":2.7,"disk_size":"18.9M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.05,"mem_mb":2.7,"disk_size":"45M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.05,"mem_mb":2.7,"disk_size":"20M"}]},"quickstart_checks":{"last_tested":"2026-04-23","tag":"verified","tag_description":"quickstart runs on critical runtimes, recently tested","results":[{"runtime":"python:3.10-alpine","exit_code":0},{"runtime":"python:3.10-slim","exit_code":0},{"runtime":"python:3.11-alpine","exit_code":0},{"runtime":"python:3.11-slim","exit_code":0},{"runtime":"python:3.12-alpine","exit_code":0},{"runtime":"python:3.12-slim","exit_code":0},{"runtime":"python:3.13-alpine","exit_code":0},{"runtime":"python:3.13-slim","exit_code":0},{"runtime":"python:3.9-alpine","exit_code":0},{"runtime":"python:3.9-slim","exit_code":0}]}}