---
id: setuptools-protobuf
version: "0.1.16"
license: Apachev2
license_treatment: permissive
maintenance: active
---

# setuptools-protobuf — Setuptools protobuf extension plugin

License: permissive · Maintenance: active · Downloads: 90.0K/mo

## What it is and what it does

setuptools-protobuf is a build-time plugin for setuptools that integrates protobuf compilation into the Python package build process. It wraps the protoc compiler and runs it during setup to convert .proto files into Python modules, placing generated files in the source tree for inclusion in the package. The plugin supports configuration via setup.py, setup.cfg, or pyproject.toml, and can optionally generate type hints when the mypy extra is enabled.

The plugin requires the protoc executable to be available in the build environment—either pre-installed on the system or automatically downloaded by specifying a protoc_version. It is designed for projects that define protocol buffer schemas and need to generate Python code from them as part of their build workflow, eliminating manual compilation steps.

Use it for:

- Include protobuf-generated Python modules in a package distribution without manual pre-compilation
- Automate proto file compilation in CI/CD pipelines using GitHub Actions or similar
- Generate type hints alongside protobuf code by enabling the mypy extra
- Manage multiple .proto files with custom search paths using the proto_path configuration
- Pin a specific protoc version for reproducible builds across different environments

## Worth the install?

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

A setuptools plugin that automates compilation of protobuf files during the Python package build process, generating Python code from .proto definitions.

Yes, if your project uses protobuf schemas and you want to automate code generation during the build process. The low install friction, active maintenance, permissive license, and zero known vulnerabilities make it a straightforward choice. The main prerequisite is having protoc available; if that's already part of your build environment or CI setup, this plugin integrates cleanly.

## Install

pip install setuptools-protobuf
uv add setuptools-protobuf
poetry add setuptools-protobuf

## Installing setuptools-protobuf

Before you install: Low friction installation with only setuptools and tomli as runtime dependencies. Active maintenance with recent commits; last release 289 days ago.

License in practice: Licensed under Apache v2 (permissive), allowing commercial and private use with minimal restrictions.

Quickstart:

# In pyproject.toml
[build-system]
requires = ["setuptools", "setuptools-protobuf"]

[tool.setuptools-protobuf]
protobufs = ["example/foo.proto"]

# Or in setup.py
from setuptools_protobuf import Protobuf
setup(setup_requires=['setuptools-protobuf'], protobufs=[Protobuf('example/foo.proto')])

The external protoc executable must be present in the environment (from protobuf-compiler package on Debian, or downloaded if protoc_version is specified)

Verify before relying:

- Whether typing hint generation (mypy extra) requires mypy as a build-time dependency
- Performance characteristics when compiling large numbers of proto files
- Compatibility with protoc versions outside the tested range

## Package facts

- License: Apachev2 (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 90.0K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

protobuf compilation setuptools, proto file build plugin, protoc integration python, setuptools protobuf extension, automatic proto compilation, protobuf code generation build, build-automation, protobuf

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