{"id":318,"library":"grpcio-tools","title":"gRPC Python Tools","description":"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.","status":"active","version":"1.78.0","language":"python","source_language":"en","source_url":"https://github.com/grpc/grpc","tags":["gRPC","Python","Protocol Buffers","Code Generation"],"install":[{"cmd":"pip install grpcio-tools","lang":"bash","label":"Install grpcio-tools"}],"dependencies":[{"reason":"Required for gRPC functionality","package":"grpcio","optional":false}],"imports":[{"note":"Ensure correct import path to access the protoc compiler.","symbol":"protoc","correct":"from grpc_tools import protoc"}],"quickstart":{"code":"import grpc\nfrom grpc_tools import protoc\n\n# Generate Python code from .proto file\nprotoc.main(())\n\n# Implement server and client using generated code\n# Refer to gRPC Python Quick Start guide for detailed implementation steps.","lang":"python","description":"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."},"warnings":[{"fix":"Use matching versions of grpcio and grpcio-tools.","message":"Ensure compatibility between grpcio-tools and grpcio versions to avoid potential issues.","severity":"breaking","affected_versions":"All"},{"fix":"Always specify the .proto file when running protoc.","message":"Running protoc without specifying the .proto file will result in an error.","severity":"gotcha","affected_versions":"All"},{"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.","message":"Running pip as the 'root' user can lead to broken permissions and conflicts with the system package manager, potentially rendering the system unusable.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"search_vec":"'1.78.0':28 'align':33 'buffer':10,40 'cadenc':30 'client':20 'code':21,41 'compil':11 'current':26 'definit':25 'generat':17,42 'grpc':1,4,35,37 'plugin':15 'proto':23 'protoc':12 'protocol':9,39 'provid':7 'python':2,5,38 'regular':31 'releas':29,36 'server':18 'servic':24 'tool':3,6 'updat':32 'version':27","created_at":"2026-03-28T08:31:07.052529+00:00","updated_at":"2026-04-16T15:30:02.063076+00:00","problems":[{"fix":"Ensure `grpcio-tools` is installed in your active Python environment: `pip install grpcio-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.","error":"ModuleNotFoundError: No module named 'grpc_tools'"},{"fix":"Instead of calling `protoc` directly, use the Python module runner: `python -m grpc_tools.protoc [OPTIONS] [PROTO_FILES]`","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.","error":"protoc-gen-grpc_python: program not found or is not executable"},{"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`.","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.","error":"ERROR: Failed building wheel for grpcio-tools"},{"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.","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.","error":"ImportError: No module named 'my_service_pb2' (within generated _grpc.py file)"},{"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`.","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.","error":"Import \"google/protobuf/timestamp.proto\" was not found or had errors"}],"ecosystem":"pypi","meta_description":null,"install_score":100,"quickstart_score":0,"quickstart_tag":"stale","pypi_latest":"1.83.0","cli_name":"grpc_tools.protoc","cli_version":"sh: 1: grpc_tools.protoc: not found","type":"library","homepage":"https://grpc.io","github":"https://github.com/grpc/grpc","docs":null,"changelog":null,"pypi":"https://pypi.org/project/grpcio-tools/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["http-networking","serialization"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-08-27","next_check":"2026-07-28","install_tag":"verified"}}