gRPC Python Tools

1.78.0 verified Tue May 12 auth: no python install: verified quickstart: stale

gRPC Python Tools provides the protocol buffer compiler `protoc` and a plugin for generating server and client code from `.proto` service definitions. Current version: 1.78.0. Release cadence: Regular updates aligned with gRPC releases.

pip install grpcio-tools

Common errors

error ModuleNotFoundError: No module named 'grpc_tools' ↓

cause The `grpcio-tools` package, which contains the `grpc_tools` module used for `protoc` invocation and generated code, is not installed or not accessible in the current Python environment.

fix

Ensure grpcio-tools is installed in your active Python environment: pip install grpcio-tools

error protoc-gen-grpc_python: program not found or is not executable ↓

cause The `protoc` executable's gRPC Python plugin (`protoc-gen-grpc_python`) is not located in the system's PATH, or the `grpcio-tools` package is not being invoked correctly to find its internal `protoc` binary.

fix

Instead of calling protoc directly, use the Python module runner: python -m grpc_tools.protoc [OPTIONS] [PROTO_FILES]

error ERROR: Failed building wheel for grpcio-tools ↓

cause This error, often accompanied by C/C++ compilation failures (e.g., `fatal error: Python.h: No such file or directory` or `command 'g++' failed`), indicates that the system lacks the necessary build tools and Python development headers required to compile `grpcio-tools` from source, which happens if a pre-built wheel is unavailable.

fix

Install the required build tools and Python development headers for your operating system. For Debian/Ubuntu: sudo apt-get install build-essential python3-dev. For Fedora: sudo dnf install @development-tools python3-devel. For macOS: Install Xcode Command Line Tools: xcode-select --install.

error ImportError: No module named 'my_service_pb2' (within generated _grpc.py file) ↓

cause When `grpcio-tools` generates Python stub files, the `_grpc.py` file might attempt to import its corresponding `_pb2.py` file using an absolute import (e.g., `import my_service_pb2`). This fails if the generated files are in a directory that isn't a proper Python package or if Python's import mechanism cannot resolve the path.

fix

Ensure the directory containing your generated .py files is treated as a Python package (e.g., by adding an __init__.py file). When invoking protoc, use relative paths for imports and output, and consider structuring your project such that generated files reside in an importable package. A common manual fix is to change import my_service_pb2 as my_service__pb2 to from . import my_service_pb2 as my_service__pb2 in the _grpc.py file. Alternatively, adjust the protoc command with appropriate -I and output directories.

error Import "google/protobuf/timestamp.proto" was not found or had errors ↓

cause This error occurs because the `protoc` command cannot find the well-known protobuf types (like `timestamp.proto`) that are included with the `grpcio-tools` package but require an explicit include path.

fix

Add the include path to Google's well-known types when running protoc. This path is usually found within your grpcio-tools installation. You can typically find it by appending -I$(python -c 'import grpc_tools; print(grpc_tools.__path__[0])')/_proto to your protoc command, or explicitly specify the path like -I/path/to/venv/lib/pythonX.Y/site-packages/grpc_tools/_proto.

Warnings

breaking Ensure compatibility between grpcio-tools and grpcio versions to avoid potential issues. ↓

fix Use matching versions of grpcio and grpcio-tools.

gotcha Running protoc without specifying the .proto file will result in an error. ↓

fix Always specify the .proto file when running protoc.

gotcha Running pip as the 'root' user can lead to broken permissions and conflicts with the system package manager, potentially rendering the system unusable. ↓

fix Avoid running pip as the 'root' user. It is recommended to use a virtual environment or explicitly acknowledge the action with `--root-user-action=ignore` if the implications are understood.

Install compatibility verified last tested: 2026-05-12

python os / libc status wheel install import disk

3.10 alpine (musl) - - 0.05s 49.8M

3.10 slim (glibc) - - 0.03s 45M

3.11 alpine (musl) - - 0.07s 52.3M

3.11 slim (glibc) - - 0.06s 48M

3.12 alpine (musl) - - 0.09s 53.0M

3.12 slim (glibc) - - 0.10s 49M

3.13 alpine (musl) - - 0.08s 52.7M

3.13 slim (glibc) - - 0.09s 48M

3.9 alpine (musl) - - 0.04s 49.3M

3.9 slim (glibc) - - 0.04s 45M

Imports

protoc
```
from grpc_tools import protoc
```
Ensure correct import path to access the protoc compiler.

Quickstart stale last tested: 2026-04-23

Generate Python code from .proto files and implement server and client using the generated code. Detailed steps are available in the gRPC Python Quick Start guide.

import grpc
from grpc_tools import protoc

# Generate Python code from .proto file
protoc.main(())

# Implement server and client using generated code
# Refer to gRPC Python Quick Start guide for detailed implementation steps.