gRPC Code Generation — Generate Client and Server Stubs from Proto

In this tutorial, you will learn about grpc Code Generation. We cover key concepts, practical examples, and best practices to help you master this topic.

gRPC code generation uses the protoc compiler to automatically produce client stubs and server skeletons from .proto files, eliminating boilerplate and ensuring type safety.

What You'll Learn

You will learn how to install protoc, generate code for multiple languages, organize generated code, and integrate code generation into your build Process.

Installing protoc

# Linux
apt install -y protobuf-compiler

# macOS
brew install protobuf

# Verify
protoc --version
# libprotoc 25.1

# Install language-specific plugins
pip install grpcio-tools           # Python
go install google.golang.org/protobuf/cmd/protoc-gen-go@latest   # Go
npm install -g grpc-tools          # Node.js

Generating Code

# Python
python -m grpc_tools.protoc \
  -I./protos \
  --python_out=./generated \
  --grpc_python_out=./generated \
  ./protos/threat.proto

# Go
protoc \
  -I./protos \
  --go_out=./generated \
  --go-grpc_out=./generated \
  ./protos/threat.proto

# Node.js
npx grpc-tools \
  --proto_path=./protos \
  --js_out=import_style=commonjs,binary:./generated \
  --grpc_out=grpc_js:./generated \
  ./protos/threat.proto

Using Generated Code

# Server — extend the generated servicer
import threat_pb2_grpc
import threat_pb2

class ThreatServicer(threat_pb2_grpc.ThreatServiceServicer):
    def GetThreat(self, request, context):
        return threat_pb2.Threat(id=request.id, name="Emotet", severity="CRITICAL")

def serve():
    server = grpc.server(futures.ThreadPoolExecutor(max_workers=10))
    threat_pb2_grpc.add_ThreatServiceServicer_to_server(ThreatServicer(), server)
    server.add_insecure_port("[::]:50051")
    server.start()
    server.wait_for_termination()

# Client — use the generated stub
channel = grpc.insecure_channel("localhost:50051")
stub = threat_pb2_grpc.ThreatServiceStub(channel)
response = stub.GetThreat(threat_pb2.GetThreatRequest(id="thr-001"))
print(f"Threat: {response.name}, Severity: {response.severity}")

Common Mistakes

1. Forgetting --grpc_out

Without --grpc_out, protoc generates only message types, not service stubs. Always specify both outputs.

2. Not Regenerating After Proto Changes

Edited .proto files without regenerating leads to runtime errors. Add codegen to your build pipeline.

3. Committing Generated Files to Git

Generated files in git cause merge conflicts. Generate during build or pre-commit hook.

4. Wrong Import Paths

Generated imports use the proto package path. Set --proto_path correctly and use consistent package names.

5. Version Mismatches

protoc, language plugins, and runtime libraries must be compatible versions. Use a requirements.txt or go.mod.

Practice Questions

1. What does protoc generate?
2. What is the difference between --python_out and --grpc_python_out?
3. How do you organize generated code?
4. Should generated code be committed to version control?
5. How do you add codegen to CI/CD?

Answers:

1. protoc generates message classes (Serialization/deserialization) and service stubs (client/server base classes).
2. --python_out generates message classes. --grpc_python_out generates service stubs and client classes.
3. Put generated files in a generated/ directory matching the proto package structure. Import them like normal code.
4. Debate: Committing ensures builds work without protoc. Not committing keeps repo clean. CI generates them.
5. Add a make generate step that runs protoc. Run it in CI before tests. Fail the build if codegen changes files.

Mini Project

Set up code generation for DodaTech's proto files. Create proto definitions for Device, Threat, and User services. Write a build script that generates Python code. Create a simple server and client using the generated stubs.

What's Next