Skip to content

🧩 Generate from Protocol Buffers / gRPC

Generate Python models from Protocol Buffers schema files (.proto), including message types referenced by gRPC service definitions.

🚀 Quick Start

Install the Protocol Buffers parser extra:

pip install 'datamodel-code-generator[protobuf]'

Generate models from a .proto file:

datamodel-codegen \
    --input order.proto \
    --input-file-type protobuf \
    --output-model-type pydantic_v2.BaseModel \
    --output model.py

📝 Example

order.proto 

syntax = "proto3";

package example.shop.v1;

import "google/protobuf/timestamp.proto";

message Order {
  // Unique order identifier.
  string id = 1;
  repeated string tags = 2;
  google.protobuf.Timestamp created_at = 3;

  oneof contact {
    string email = 4;
    string phone = 5;
  }
}

message GetOrderRequest {
  string id = 1;
}

message GetOrderResponse {
  Order order = 1;
}

service OrderService {
  rpc GetOrder(GetOrderRequest) returns (GetOrderResponse);
}

✨ Generated model.py 

from __future__ import annotations

from pydantic import AwareDatetime, BaseModel, Field


class ExampleShopV1Order(BaseModel):
    id: str | None = Field('', description='Unique order identifier.')
    tags: list[str] | None = []
    created_at: AwareDatetime | None = None
    email: str | None = Field(None, description='oneof: contact')
    phone: str | None = Field(None, description='oneof: contact')


class ExampleShopV1GetOrderRequest(BaseModel):
    id: str | None = ''


class ExampleShopV1GetOrderResponse(BaseModel):
    order: ExampleShopV1Order | None = None

Supported Protocol Buffers Features

The Protocol Buffers parser supports the schema constructs needed to generate Python model definitions:

Protobuf construct Model generation behavior
Scalar fields Maps protobuf scalar types to Python scalar types
message Generates a Python model class
Nested message Generates a named Python model class with package and parent context
enum Generates an enum class
repeated Generates a list field
map<K, T> Generates a dict field for protobuf-supported string, integer, and bool key types
oneof Generates nullable fields and preserves oneof membership as field metadata
optional, required, singular Preserves proto2/proto3 presence and requiredness where model generation can represent it
Defaults Preserves explicit proto2 defaults and proto3 implicit defaults
Package names Included in generated class names to avoid cross-file collisions
Imports Resolves regular imports, public imports, weak imports, fully-qualified type references, and cross-file references
Services and RPCs Keeps request and response message types reachable for unary and streaming RPCs
Comments Preserved as field descriptions when field descriptions are enabled

Supported scalar types are double, float, int32, int64, uint32, uint64, sint32, sint64, fixed32, fixed64, sfixed32, sfixed64, bool, string, and bytes.

Well-Known Types

Common google.protobuf well-known types are mapped through the generator's normal type handling:

Protobuf type Typical generated Python type
Timestamp AwareDatetime
Duration timedelta
Struct dict[str, Any]
Value bool | float | str | dict[str, Any] | list[Any] | None
ListValue list[Any]
Any dict[str, Any]
FieldMask str
Wrapper types Optional scalar fields

Schema Version

Protocol Buffers syntax is detected from each compiled .proto descriptor:

  • syntax = "proto3"; -> proto3
  • syntax = "proto2"; or no syntax declaration -> proto2
  • edition = "2023"; -> edition 2023

Use --schema-version proto2, --schema-version proto3, or --schema-version 2023 to override auto-detection when needed.

Multiple Files

Pass a directory as input to generate from a group of related .proto files:

datamodel-codegen \
    --input ./protos \
    --input-file-type protobuf \
    --output ./models \
    --module-split-mode single

The parser resolves imports relative to the input file or directory and emits importable Python modules when an output directory is used.

Limitations

datamodel-code-generator uses Protocol Buffers schemas to generate Python model definitions. It does not implement protobuf runtime validation, oneof runtime exclusivity checks, wire serialization, or gRPC client/server code generation.

Some protobuf constructs are parsed only as needed for data model generation. Options, custom options, extensions, reserved declarations, and service streaming markers are tolerated where possible but are not emitted as runtime protobuf behavior.

📖 See Also