Registry / http-networking / grpcio-tools

grpcio-tools

library1.83.0pypypi✓ verified 24d ago

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.

http-networking serialization

pip install grpcio-tools

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · GRPCIO-TOOLS

grpcio-tools

http-networkingpythonv1.83.0

Install

4.3s avg

Import

65ms

Disk

49MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v1.83.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

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.066s · 50.4MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 4.3s · import 0.064s · 46MB

49MB installed

● package 49MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

protoc

✓ from grpc_tools import protoc

Ensure correct import path to access the protoc compiler.

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.

grpc_tools.protoc --version

Debug

Known issues

breakingEnsure compatibility between grpcio-tools and grpcio versions to avoid potential issues.

fix

Use matching versions of grpcio and grpcio-tools.

affects: All

gotchaRunning protoc without specifying the .proto file will result in an error.

fix

Always specify the .proto file when running protoc.

affects: All

gotchaRunning 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.

affects: All

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'grpc_tools'

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`

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

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: Failed building wheel for grpcio-tools

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`.

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

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.

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

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`.

Upgrade

Version history

1.83.0latest on PyPI · released Jul 23, 2026

Audit

Dependencies

grpciorequiredRequired for gRPC functionality

Agent activity

27 hits · last 30 days

node