Proto Plus for Python

1.27.2 verified Tue May 12 auth: no python install: verified quickstart: verified

A Python library that provides a beautiful, Pythonic interface for working with protocol buffers. Current version: 1.27.2. Maintained with regular updates.

pip install proto-plus

Common errors

error ModuleNotFoundError: No module named 'your_app_name.proto.your_service_pb2' ↓

cause This error occurs because the Python protobuf code has not been generated from your '.proto' file, or the generated files are not in a directory included in your Python import path (PYTHONPATH).

fix

Generate the Python code from your '.proto' files using the protoc compiler and ensure the output directory is in your PYTHONPATH or added to sys.path: protoc --python_out=. --proto_path=. your_service.proto

error AttributeError: 'MyProtoMessage' object has no attribute 'to_dict' ↓

cause The `to_dict()` and `from_dict()` methods are enhancements provided by `proto-plus`, and this error indicates that `proto-plus` is either not installed, not correctly applied to your protobuf classes, or an older version is in use.

fix

Ensure proto-plus is installed (pip install proto-plus) and that your environment allows it to patch the protobuf classes. These methods should become available automatically when proto-plus is active.

error TypeError: cannot interpret bytestring as UTF-8 ↓

cause This error arises when you attempt to assign a `bytes` object that is not a valid UTF-8 sequence to a protobuf field defined as a `string` type, which expects a Python `str` (unicode).

fix

Decode the bytes data into a str (unicode string) before assigning it to a protobuf string field, typically using .decode('utf-8').

error TypeError: Can't set repeated field to non-iterable ↓

cause This error occurs when you try to assign a single scalar value (e.g., a string or integer) directly to a protobuf repeated field, which expects an iterable (like a list or tuple) of values.

fix

Always assign an iterable (even a list with a single item) to a repeated field.

Warnings

breaking Proto Plus 1.27.0 introduced changes to the 'Field' class constructor, requiring explicit 'type' and 'number' arguments. ↓

fix Update your 'Field' class instantiations to include 'type' and 'number' arguments.

gotcha When defining nested messages, ensure that the nested class is defined before the parent class to avoid 'NameError'. ↓

fix Define nested message classes before the parent class to prevent 'NameError' during instantiation.

gotcha Running pip as the 'root' user can result in broken permissions and conflicting behaviour with the system package manager. It is recommended to use a virtual environment. ↓

fix It is recommended to use a virtual environment instead: https://pip.pypa.io/warnings/venv

Install compatibility verified last tested: 2026-05-12

python os / libc status wheel install import disk

3.10 alpine (musl) - - 0.22s 19.8M

3.10 slim (glibc) - - 0.07s 21M

3.11 alpine (musl) - - 0.59s 22.1M

3.11 slim (glibc) - - 0.15s 23M

3.12 alpine (musl) - - 0.49s 14.0M

3.12 slim (glibc) - - 0.15s 15M

3.13 alpine (musl) - - 0.46s 13.6M

3.13 slim (glibc) - - 0.16s 14M

3.9 alpine (musl) - - 0.14s 19.3M

3.9 slim (glibc) - - 0.09s 20M

Imports

proto
```
import proto
```
Ensure 'proto' is imported to access the library's functionalities.
proto.Message
```
from proto import Message
```
Import 'Message' from 'proto' to define protocol buffer messages.

Quickstart verified last tested: 2026-04-23

A simple example demonstrating how to define and use protocol buffer messages with Proto Plus.

import proto

class Composer(proto.Message):
    given_name = proto.Field(proto.STRING, number=1)
    family_name = proto.Field(proto.STRING, number=2)

class Song(proto.Message):
    composer = proto.Field(Composer, number=1)
    title = proto.Field(proto.STRING, number=2)
    lyrics = proto.Field(proto.STRING, number=3)
    year = proto.Field(proto.INT32, number=4)

song = Song(
    composer={'given_name': 'Johann', 'family_name': 'Pachelbel'},
    title='Canon in D',
    year=1680,
)
print(song.composer.family_name)  # Output: Pachelbel
print(song.title)  # Output: Canon in D