Protocol Buffers (protobuf) for Python

Common errors

Warnings

Install

Install compatibility verified last tested: 2026-05-12

Imports

• MessageToJson / ParseDict
  wrong

  import google.protobuf.json_format as jf; jf.MessageToJson(msg)

  correct

  from google.protobuf import json_format
  json_format.MessageToJson(msg)
  json_format.ParseDict(d, MyMessage())

  Always import via google.protobuf package namespace. Direct attribute access on a bare import can fail if the google namespace package is split.

• MessageToString / Parse (text format)

  from google.protobuf import text_format
  text_format.MessageToString(msg)
  text_format.Parse(text, MyMessage())

  text_format lives under google.protobuf, not at the top level of the protobuf package.

• descriptor_pool / DescriptorPool

  from google.protobuf import descriptor_pool
  pool = descriptor_pool.Default()

  Used for dynamic message creation and reflection; pool is a singleton—do not construct new ones unnecessarily.

• Generated message class (user proto)
  wrong

  import my_message; msg = my_message.MyMessage()

  correct

  # After: protoc --python_out=. my_message.proto
  from my_message_pb2 import MyMessage
  msg = MyMessage(field1='hello', field2=42)

  Generated files always have the _pb2.py suffix. The proto package declaration does NOT affect Python module names—only directory structure matters.

• Well-known types (Timestamp, Duration, Any, Struct …)
  wrong

  from protobuf.timestamp_pb2 import Timestamp

  correct

  from google.protobuf.timestamp_pb2 import Timestamp
  from google.protobuf.any_pb2 import Any

  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').

• UnknownFieldSet
  wrong

  msg.UnknownFields()

  correct

  from google.protobuf import unknown_fields
  unk = unknown_fields.UnknownFieldSet(msg)

  message.UnknownFields() was deprecated in v5.25 and removed in v6.26+. Use the unknown_fields module instead.

Quickstart verified last tested: 2026-04-23

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)