---
id: hatch-protobuf
version: "0.5.0"
license: MPL-2.0
license_treatment: copyleft
maintenance: active
---

# hatch-protobuf — A Hatch build plugin to generate Python files from Protocol Buffers .proto files

License: copyleft · Maintenance: active · Downloads: 190.5K/mo

## What it is and what it does

hatch-protobuf is a build-time plugin for the Hatch package manager that automates the generation of Python code from Protocol Buffer definitions. It wraps grpcio-tools' protoc compiler and integrates it into Hatch's build hook system, so `.proto` files are compiled to Python during package builds without manual steps.

The plugin generates Python message classes and gRPC service stubs by default, with optional `.pyi` type stub files for static analysis. It supports custom generators (e.g., for TypeScript or other languages), can import `.proto` definitions from installed packages via site-packages, and allows configuration of input/output paths and protoc options through `pyproject.toml`. It's designed for projects that use Protocol Buffers as part of their build process and want code generation to happen automatically during packaging.

Use it for:

- Generate gRPC service stubs and message classes during package build for microservices that use Protocol Buffers.
- Consume `.proto` definitions from published packages (e.g., googleapis-common-protos) without rebuilding them.
- Integrate custom protoc plugins (TypeScript, Go, etc.) into a Python project's build pipeline.
- Maintain type stubs (.pyi files) alongside generated Protocol Buffer code for IDE and mypy support.
- Automatically compile `.proto` files in src-layout or flat-layout projects with sensible defaults.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

A Hatch build plugin that generates Python files from Protocol Buffers `.proto` files using grpcio-tools, with support for gRPC, type stubs, and custom generators.

Yes, if you use Hatch and Protocol Buffers. Low friction to install, no known vulnerabilities, actively maintained, and solves a real build-automation problem. The pre-alpha status (Development Status :: 2) suggests the API may change, so pin the version in your build dependencies. Not worth installing if you don't use Hatch or don't generate code from `.proto` files.

## Install

pip install hatch-protobuf
uv add hatch-protobuf
poetry add hatch-protobuf

## Installing hatch-protobuf

Before you install: Low install friction; pure Python wheel with only two runtime dependencies (grpcio-tools and hatchling). Repository is active with recent commits and no known vulnerabilities.

License in practice: Licensed under MPL-2.0 (copyleft). You must disclose source code modifications and distribute under the same license if you modify the plugin itself, though generated code is not affected.

Quickstart:

# Add to pyproject.toml:
[tool.hatch.build.hooks.protobuf]
dependencies = ["hatch-protobuf"]

# Then run:
pip install hatch-protobuf
hatch build

Requires Hatch as your build system; grpcio-tools must be available in your environment to run protoc.

Verify before relying:

- Whether custom protoc plugins (e.g., TypeScript generators) work reliably with non-Python targets.
- Performance characteristics when processing large numbers of .proto files or deeply nested proto_paths.
- Compatibility with editable installs of packages that provide .proto files for import.

## Package facts

- License: MPL-2.0 (copyleft)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 190.5K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

protobuf code generation, hatch build plugin protobuf, grpc python file generation, proto to python compiler, hatch protobuf integration, protocol buffers build hook, grpcio code generator, protobuf, grpc, build-automation

[View on SkillFed](https://skillfed.io/packages/hatch-protobuf) · [View on PyPI](https://pypi.org/project/hatch-protobuf/)