Install & Compatibility
Where this runs
tested against v0.5.0 · 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 · 52.8MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 4.6s · import 0.000s · 48MB
52MB installed
● package 52MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
hatch_protobuf
✓ import hatch_protobuf
✗ from my_package.protos import my_message_pb2
To quickly use `hatch-protobuf`, first configure your `pyproject.toml` file to include the plugin and define the paths for your `.proto` files and where the generated Python modules should be placed. Ensure `grpcio-tools` and `protobuf` are listed as dependencies for the build hook. Then, place your `.proto` definitions in the specified `proto-paths`. After running `hatch build` or setting up your development environment (e.g., `hatch env run pip install -e .`), the generated Python modules can be imported and used like any other Protobuf-generated code.
# pyproject.toml
[build-system]
requires = ["hatchling>=1.12.0", "hatch-protobuf~=0.5.0"]
build-backend = "hatchling.build"
[tool.hatch.build.hooks.protobuf]
proto-paths = ["src/my_package/protos"] # Directory containing your .proto files
output-path = "src/my_package/protos" # Where to place generated Python files
dependencies = [
"grpcio-tools~=1.48", # Specific versions often needed for compatibility
"protobuf>=3.19"
]
# src/my_package/protos/example.proto
syntax = "proto3";
package my_package.protos;
message MyMessage {
string name = 1;
int32 id = 2;
}
# src/my_package/main.py (after running hatch build or in dev environment)
from my_package.protos import example_pb2
message = example_pb2.MyMessage(name="Alice", id=123)
print(f"Created Protobuf message: {message.name}, {message.id}")
Debug
Known issues
breakingHatch 1.16.0 introduced changes in how build hook dependencies are handled, which may cause `hatch build` to fail if `hatch-protobuf` is listed only within `[tool.hatch.build.hooks.protobuf].dependencies`.fixEnsure `hatch-protobuf` itself is listed in `build-system.requires` in your `pyproject.toml`, as shown in the quickstart example.
affects: Hatch >= 1.16.0
gotchaThe plugin is designed to import `.proto` definitions from non-editable (regular `pip install`) dependencies. Importing from editable dependencies (e.g., `pip install -e` or `uv workspaces`) might not work due to different directory layouts that `protoc` cannot correctly resolve.fixFor `.proto` files provided by other Python packages, ensure those packages are installed normally (not in editable mode). For local `.proto` files, manage them within your project's `proto-paths`.
affects: All versions
gotchaCare must be taken when configuring `proto-paths` and `import_site_packages`. Setting `import_site_packages = true` causes `protoc` to add your site-packages to its `--proto_path`, potentially leading to re-generation of Python files for existing system-wide Protobuf definitions (like `googleapis-common-protos`), which can conflict with pre-built versions and stomp over your `site-packages` directory.fixOnly use `import_site_packages = true` if you explicitly intend to generate code that might conflict with or override existing `site-packages` protos. For most cases, explicitly define `proto-paths` for your project's `.proto` files.
affects: All versions
gotchaNewer versions of the `protoc` compiler (used internally) enforce stricter limits on the length of symbol names (e.g., field names). Very long names in your `.proto` definitions can lead to compilation errors.fixReview and shorten excessively long symbol names in your `.proto` files if you encounter errors related to name length limits.
affects: Protobuf compiler v22.x and later
Upgrade
Version history
0.5.0latest on PyPI · released Jul 16, 2025
Audit
Dependencies
hatchlingrequiredRequired as the build backend for Hatch plugins.
grpcio-toolsrequiredProvides the `protoc` compiler and Python gRPC stubs, used internally by the plugin for code generation.
protobufrequiredThe core Protocol Buffers runtime library, necessary for working with generated Python Protobuf messages.