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
muslpy 3.10–3.910 runs
installs and imports cleanly · install 0.0s · import 0.264s · 50.4MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 3.5s · import 0.234s · 46MB
49MB installed
● package 49MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
grpc
✓ import grpc
Core gRPC module for Python
grpc_tools
✓ import grpc_tools
Module for gRPC tools, including the protocol buffer compiler
Basic setup for a gRPC server in Python
import grpc
from concurrent import futures
# Define the server
server = grpc.server(futures.ThreadPoolExecutor(max_workers=10))
# Add your service implementations here
# Start the server
server.add_insecure_port('[::]:50051')
server.start()
server.wait_for_termination()
Debug
Known issues
breakingPython 2.7 support was removed on January 1, 2020.fixUpgrade to Python 3.9 or higher.
affects: grpcio versions after 1.30.0
gotchaGenerated Python code from .proto files may have absolute imports, causing import errors in certain project structures.fixEnsure .proto files are organized to match the desired Python package structure, or adjust import statements accordingly.
affects: All versions
gotchaInstallation issues may arise due to setuptools version conflicts.fixDowngrade setuptools to version 49.6.0 if installation fails.
affects: grpcio versions around 1.30.0
gotchaTest execution timed out.fixInvestigate test logs for hanging processes, deadlocks, or infinite loops that prevent tests from completing within the allotted time.
affects: All versions
gotchaTest execution timed out. This could be due to long-running tests, resource constraints, or an infinite loop in the code.fixReview test duration, optimize test cases, check for infinite loops, and ensure sufficient resources are allocated for test execution.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'grpc'
This error occurs when the `grpcio` package (or its associated tools like `grpcio-tools`) is not installed or not accessible in the Python environment where the code is being run.
fixInstall the necessary gRPC packages using pip: `pip install grpcio grpcio-tools`
Connection refused
This typically indicates that the gRPC client cannot establish a TCP connection to the gRPC server. Common reasons include the server not running, an incorrect server address/port, firewall issues, or network connectivity problems. The client might also report `grpc._channel._InactiveRpcError: <_InactiveRpcError of RPC that terminated with: status = StatusCode.UNAVAILABLE` in this scenario.
fixVerify that the gRPC server is running and listening on the expected address and port. Check firewall rules (e.g., `ufw`, `iptables`) to ensure the port is open. Ensure the client is connecting to the correct IP address and port, possibly binding the server to `0.0.0.0` or `[::]` instead of `localhost` for external access.
AttributeError: module 'grpc' has no attribute 'aio'
This error arises when trying to use the asynchronous gRPC API (`grpc.aio`) with an older version of `grpcio` that does not support it, or if there's an issue with the installation of the `grpcio` package's C extensions.
fixUpgrade `grpcio` to a version that supports `asyncio` (e.g., `grpcio>=1.32.0`) by running `pip install --upgrade grpcio grpcio-tools`. If issues persist, try reinstalling with `--no-cache-dir` to ensure a fresh build.
SSL: CERTIFICATE_VERIFY_FAILED
This error occurs during a secure (TLS/SSL) gRPC connection when the client cannot verify the server's SSL certificate. This can be due to an invalid certificate, a self-signed certificate not trusted by the client, or an outdated `certifi` package.
fixEnsure the server is presenting a valid, trusted SSL certificate. If using self-signed certificates for development, configure the client to trust them explicitly. Update `certifi` (if applicable) using `pip install --upgrade certifi`. For environments where proxy issues might interfere with certificate validation, setting `grpc.enable_http_proxy=0` in channel options might help.
error: Microsoft Visual C++ 14.0 or greater is required.
Installing grpcio from source on Windows requires the Microsoft Visual C++ build tools to compile its C extensions.
fixInstall the 'Build Tools for Visual Studio' from Microsoft's website, ensuring the 'Desktop development with C++' workload is selected.
Upgrade
Version history
1.83.0latest on PyPI · released Jul 23, 2026
Audit
Dependencies
grpcio-toolsoptionalRequired for generating Python code from .proto files