{"id":9032,"library":"hatch-protobuf","title":"Hatch Protobuf Plugin","description":"Hatch-protobuf is a Hatch build plugin designed to automatically generate Python files from Protocol Buffers (.proto) definitions. It leverages `grpcio-tools` internally to invoke the `protoc` compiler, streamlining the integration of Protobuf schema compilation into the standard Python build process. As of version 0.5.0, it is actively maintained, though its release cadence is tied to the broader Hatch and Hatchling ecosystem.","status":"active","version":"0.5.0","language":"en","source_language":"en","source_url":"https://github.com/nanoporetech/hatch-protobuf","tags":["hatch","protobuf","build-plugin","code-generation","grpc","compiler"],"install":[{"cmd":"pip install hatch-protobuf","lang":"bash","label":"Install only the plugin"},{"cmd":"pip install hatch-protobuf grpcio-tools protobuf","lang":"bash","label":"Install plugin and common Protobuf dependencies"}],"dependencies":[{"reason":"Required as the build backend for Hatch plugins.","package":"hatchling","optional":false},{"reason":"Provides the `protoc` compiler and Python gRPC stubs, used internally by the plugin for code generation.","package":"grpcio-tools","optional":false},{"reason":"The core Protocol Buffers runtime library, necessary for working with generated Python Protobuf messages.","package":"protobuf","optional":false}],"imports":[{"note":"Hatch-protobuf is a build hook; end-users import the Python modules generated from .proto files, typically suffixed with '_pb2.py' and located according to your project's `output-path` configuration.","symbol":"GeneratedProtobufModule","correct":"from my_package.protos import my_message_pb2"}],"quickstart":{"code":"# pyproject.toml\n[build-system]\nrequires = [\"hatchling>=1.12.0\", \"hatch-protobuf~=0.5.0\"]\nbuild-backend = \"hatchling.build\"\n\n[tool.hatch.build.hooks.protobuf]\nproto-paths = [\"src/my_package/protos\"] # Directory containing your .proto files\noutput-path = \"src/my_package/protos\" # Where to place generated Python files\ndependencies = [\n    \"grpcio-tools~=1.48\", # Specific versions often needed for compatibility\n    \"protobuf>=3.19\"\n]\n\n# src/my_package/protos/example.proto\nsyntax = \"proto3\";\n\npackage my_package.protos;\n\nmessage MyMessage {\n  string name = 1;\n  int32 id = 2;\n}\n\n# src/my_package/main.py (after running hatch build or in dev environment)\nfrom my_package.protos import example_pb2\n\nmessage = example_pb2.MyMessage(name=\"Alice\", id=123)\nprint(f\"Created Protobuf message: {message.name}, {message.id}\")","lang":"python","description":"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."},"warnings":[{"fix":"Ensure `hatch-protobuf` itself is listed in `build-system.requires` in your `pyproject.toml`, as shown in the quickstart example.","message":"Hatch 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`.","severity":"breaking","affected_versions":"Hatch >= 1.16.0"},{"fix":"For `.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`.","message":"The 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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Only 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.","message":"Care 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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Review and shorten excessively long symbol names in your `.proto` files if you encounter errors related to name length limits.","message":"Newer 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.","severity":"gotcha","affected_versions":"Protobuf compiler v22.x and later"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Ensure `grpcio-tools` and `protobuf` are correctly specified in your build hook dependencies with compatible versions. Double-check `proto-paths` and `output-path` in `pyproject.toml` for correctness. Manually run `protoc` on your `.proto` files with similar arguments to debug syntax issues.","cause":"The `protoc` command invoked by `grpc_tools.protoc.main` failed. This often indicates issues with file paths, syntax errors in `.proto` files, or `grpcio-tools`/`protobuf` not being correctly installed or accessible.","error":"RuntimeError: ERROR: ['grpc_tools.protoc', '--proto_path=...', '--python_out=...', '...']"},{"fix":"Verify that `output-path` in `pyproject.toml` points to a valid location within your Python package structure (e.g., `src/my_package/protos`). For development, ensure your project is installed in editable mode (e.g., `hatch env run pip install -e .` from your project root) so the generated files are symlinked or copied into the editable package location.","cause":"The Python files generated by `hatch-protobuf` are not being placed in a location discoverable by Python, or the Python package structure is incorrect, or the project is not installed in development mode.","error":"ModuleNotFoundError: No module named 'my_package.protos.my_message_pb2'"},{"fix":"Update `hatch-protobuf` to its latest compatible version, as changes in Hatch (e.g., Hatch 1.16.5 fixed a breaking change in virtualenv, and older Hatch versions might drop Python 3.9 support). Ensure `hatch-protobuf`'s version constraint allows for the latest patch releases.","cause":"This error or similar `TypeError` can occur when using an older version of `hatch-protobuf` with a newer version of `Hatch` due to changes in Hatch's environment plugin interface.","error":"TypeError: environment_type_plugin_class() got an unexpected keyword argument 'keep_env'"}]}