Install & Compatibility
Where this runs
tested against v1.3.3 · 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.920 runs
installs and imports cleanly · install 0.0s · import 0.000s · 22.1MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 3.1s · import 0.000s · 23MB
20MB installed
● package 20MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
ValidationError
✓ from protoc_gen_validate import ValidationError
✗ from protoc_gen_validate import ValidationError
This quickstart demonstrates how to use the generated validation functions and catch `ValidationError` exceptions for Protobuf messages in Python. It assumes that you have already defined your `.proto` messages with validation rules and used the `protoc` compiler with the `protoc-gen-validate` plugin to generate the Python `_pb2.py` and `_pb2_validate.py` files.
# This quickstart assumes you have already defined a .proto file with validation rules
# (e.g., example.proto) and generated the Python protobuf and validation stubs:
#
# example.proto content:
# syntax = "proto3";
# package example;
# import validate/validate.proto;
#
# message Person {
# int32 id = 1 [(validate.rules).int32.gt = 0];
# string email = 2 [(validate.rules).string.email = true];
# string name = 3 [(validate.rules).string.min_len = 1];
# }
#
# Generation command (requires 'protoc' and 'protoc-gen-validate' binaries):
# protoc --plugin=protoc-gen-validate --validate_out=. --python_out=. example.proto
from example_pb2 import Person
from example_pb2_validate import validate as validate_person
from protoc_gen_validate.validator import ValidationError
# --- Example 1: Valid Person ---
print("\n--- Valid Person Example ---")
try:
p_valid = Person(id=1, email="alice@example.com", name="Alice Smith")
validate_person(p_valid)
print(f"Validation successful for: {p_valid.name}")
except ValidationError as e:
print(f"Validation unexpectedly failed for valid person: {e}")
# --- Example 2: Invalid Person (id <= 0) ---
print("\n--- Invalid Person (ID) Example ---")
try:
p_invalid_id = Person(id=0, email="bob@example.com", name="Bob Johnson")
validate_person(p_invalid_id)
print(f"Validation unexpectedly passed for invalid ID: {p_invalid_id.name}")
except ValidationError as e:
print(f"Validation failed for invalid ID (as expected): {e}")
# --- Example 3: Invalid Person (empty name) ---
print("\n--- Invalid Person (Name) Example ---")
try:
p_invalid_name = Person(id=2, email="charlie@example.com", name="")
validate_person(p_invalid_name)
print(f"Validation unexpectedly passed for empty name: {p_invalid_name.email}")
except ValidationError as e:
print(f"Validation failed for empty name (as expected): {e}")
protoc-gen-validate --version
Debug
Known issues
gotchaThe PyPI package `protoc-gen-validate` provides only the Python runtime library for generated validation code. You must separately install the `protoc-gen-validate` binary (the `protoc` plugin) to generate the Python validation files (`_pb2_validate.py`).fixDownload the `protoc-gen-validate` binary from GitHub releases (https://github.com/bufbuild/protoc-gen-validate/releases) or install it via `go install github.com/bufbuild/protoc-gen-validate/cmd/protoc-gen-validate@latest`, then ensure it's in your system's PATH.
affects: All
gotchaValidation is not automatic. After generation, you must explicitly import the `validate` function from your generated `_pb2_validate.py` module and call it with your message instance. Simply importing the `_pb2.py` message definition is insufficient.fixEnsure you have a line like `from my_message_pb2_validate import validate as validate_my_message` and call `validate_my_message(my_instance)`.
affects: All
breakingPython 3.9 support was unstable in earlier `v1.x` versions, with explicit fixes in `v1.2.1`. From `v1.3.3` onwards, the official `requires_python` is `>=3.10`. Using older versions of the library with Python 3.9+ may lead to build or runtime issues.fixUpgrade to `protoc-gen-validate==1.3.3` or newer, and ensure your Python environment is `3.10` or later. If you must use Python 3.9, try `v1.2.1` but be aware of potential issues.
affects: <1.3.3 with Python >=3.9
gotchaThe `ValidationError` exception must be imported from `protoc_gen_validate.validator`. Attempting to import it from the top-level package or using a generic `Exception` will prevent proper handling of specific validation failures.fixAlways use `from protoc_gen_validate.validator import ValidationError` when catching validation errors.
affects: All
Upgrade
Version history
1.3.3latest on PyPI · released Feb 18, 2026
Audit
Dependencies
protobufrequiredRequired runtime dependency for all Protocol Buffers messages and generated code.