{"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,"last_verified":"2026-05-12T13:02:17.742Z","next_check":"2026-06-26T00:00:00.000Z","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,"install_tag":"verified","quickstart_score":0,"quickstart_tag":"stale","pypi_latest":null,"install_checks":{"last_tested":"2026-05-12","tag":"verified","tag_description":"installs cleanly on critical runtimes, fast import, recently tested","results":[{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.05,"mem_mb":2.3,"disk_size":"49.8M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.03,"mem_mb":2.3,"disk_size":"45M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.07,"mem_mb":2.7,"disk_size":"52.3M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.06,"mem_mb":2.7,"disk_size":"48M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.09,"mem_mb":3.3,"disk_size":"53.0M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.1,"mem_mb":3.3,"disk_size":"49M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.08,"mem_mb":3,"disk_size":"52.7M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.09,"mem_mb":3,"disk_size":"48M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.04,"mem_mb":2.2,"disk_size":"49.3M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.04,"mem_mb":2.2,"disk_size":"45M"}]},"quickstart_checks":{"last_tested":"2026-04-23","tag":"stale","tag_description":"widespread failures or data too old to trust","results":[{"runtime":"python:3.10-alpine","exit_code":139},{"runtime":"python:3.10-slim","exit_code":139},{"runtime":"python:3.11-alpine","exit_code":0},{"runtime":"python:3.11-slim","exit_code":139},{"runtime":"python:3.12-alpine","exit_code":139},{"runtime":"python:3.12-slim","exit_code":139},{"runtime":"python:3.13-alpine","exit_code":139},{"runtime":"python:3.13-slim","exit_code":139},{"runtime":"python:3.9-alpine","exit_code":139},{"runtime":"python:3.9-slim","exit_code":139}]}}