Install & Compatibility
Where this runs
tested against v0.3.3.1 · 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.940 runs
installs and imports cleanly · install 0.0s · import 0.841s · 32.4MB
glibcpy 3.10–3.940 runs
installs and imports cleanly · install 3.8s · import 0.571s · 32MB
31MB installed
● package 31MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
msg_to_pydantic_model
✓ from protobuf_to_pydantic import msg_to_pydantic_model
Template
✓ from protobuf_to_pydantic.template import Template
✗ from protobuf_to_pydantic.desc_template import DescTemplate
The import path for custom templates changed in `v0.3.0`. `DescTemplate` was removed. [cite: GitHub v0.3.0 release]
This quickstart demonstrates how to convert a Protobuf Message object into a Pydantic `BaseModel` at runtime using `msg_to_pydantic_model`. It includes a minimal simulated Protobuf message for immediate execution. For actual use, `UserMessage` would be imported from your generated `_pb2.py` files.
import sys
from typing import Type
from pydantic import BaseModel, Field
from google.protobuf.message import Message
from google.protobuf import descriptor_pool, descriptor_pb2
from protobuf_to_pydantic import msg_to_pydantic_model
# Simulate a generated protobuf message `demo_pb2.UserMessage`
# In a real scenario, this would come from `import demo_pb2`
pool = descriptor_pool.Default()
descriptor = descriptor_pb2.DescriptorProto()
descriptor.name = 'UserMessage'
descriptor.field.add(name='uid', number=1, type=descriptor_pb2.FieldDescriptorProto.TYPE_STRING)
descriptor.field.add(name='age', number=2, type=descriptor_pb2.FieldDescriptorProto.TYPE_INT32)
descriptor.field.add(name='user_name', number=3, type=descriptor_pb2.FieldDescriptorProto.TYPE_STRING)
pool.Add(descriptor)
# Create a mock Message class based on the descriptor
class UserMessage(Message):
def __init__(self, uid='', age=0, user_name='', **kwargs):
super().__init__(**kwargs)
self.uid = uid
self.age = age
self.user_name = user_name
DESCRIPTOR = pool.FindMessageTypeByName('UserMessage')
# Convert the Protobuf Message object to a Pydantic BaseModel
UserModel: Type[BaseModel] = msg_to_pydantic_model(UserMessage)
# Example usage of the generated Pydantic model
user_data = UserModel(uid='123', age=30, user_name='John Doe')
print(user_data.model_dump_json(indent=2))
# Access field info
# print({k: v.field_info for k, v in UserModel.__fields__.items()}) # For Pydantic v1
print({k: v.json_schema_extra for k, v in UserModel.model_fields.items()}) # For Pydantic v2+
protobuf-to-pydantic --version
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'protobuf_to_pydantic.desc_template'
Attempting to import `DescTemplate` after the `v0.3.0` release, where its import path was changed to `Template`.
fixChange the import statement to `from protobuf_to_pydantic.template import Template`.
FileNotFoundError: [Errno 2] No such file or directory: 'protoc'
The `protoc` command-line tool, required for compiling `.proto` files in plugin mode, is not installed or not found in the system's PATH.
fixInstall the Protocol Buffer Compiler (`protoc`) for your operating system and ensure its executable is discoverable in your system's PATH environment variable.
TypeError: 'Struct' object cannot be interpreted as a dict (or similar error when passing google.protobuf.struct_pb2.Struct)
Older versions of the library might have had issues correctly processing `google.protobuf.Struct` types into Pydantic models. [cite: GitHub v0.2.5 fix]
fixUpgrade to `protobuf-to-pydantic` version `0.2.5` or newer, which includes a fix for handling `google.protobuf.Struct` types correctly.
Upgrade
Version history
0.3.3.1latest on PyPI · released Jun 7, 2025
Audit
Dependencies
pydanticrequiredCore functionality relies on Pydantic for model generation and validation.
protobufrequiredRequired for parsing Protobuf message definitions and handling generated `_pb2.py` files.
grpcio-toolsoptionalRequired for compiling .proto files and using the `protoc` plugin mode.
mypy-protobufoptionalOptional dependency for enhanced type checking and full functionality via `mypy-protobuf` integration.