Skip to content
Tutorials Center
My learning

Topics

Lesson 4 of 39 ยท Getting Started

Installing protoc and the gRPC Plugins

Install the protobuf compiler and language plugins for Go, Python and Java, compile your first .proto file, and see how code generation works with a runnable Go stand-in.

To use gRPC you need a compiler that reads .proto files and writes code. The classic tool is protoc, the Protocol Buffers compiler. It does not know any language by itself: it parses your contract and hands a description to a plugin, which writes the code for Go, Python, Java and so on. A newer, friendlier tool called buf wraps this workflow.

On this site none of these tools can run, so the commands below are read-only. They are accurate for typical Linux, macOS and Windows setups, but check each project's release page for current versions. After the commands, a runnable Go stand-in shows what a code generator actually does.

Step 1: install protoc

System Command
macOS (Homebrew) brew install protobuf
Debian/Ubuntu sudo apt install -y protobuf-compiler
Windows (winget) winget install protobuf
Any Download a release zip and put bin/protoc on your PATH

Check it works:

Terminal
protoc --version

It prints a line such as libprotoc 29.x; the exact number depends on what you installed.

Step 2: install the language plugins

Each language has its own plugins. For Go, install the message plugin and the gRPC plugin:

Terminal
go install google.golang.org/protobuf/cmd/protoc-gen-go@latest
go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@latest

Make sure $(go env GOPATH)/bin is on your PATH, or protoc will not find protoc-gen-go. The naming rule is important: protoc --go_out=... runs the program named protoc-gen-go.

For Python, the gRPC tools package bundles a compiler:

Terminal
pip install grpcio grpcio-tools
python -m grpc_tools.protoc --version

For Java, you normally use a build plugin (the Maven or Gradle protobuf plugin) rather than installing protoc by hand; the plugin downloads a matching compiler.

Step 3: compile a contract

Create proto/greeter/v1/greeter.proto:

PROTO
syntax = "proto3";

package greeter.v1;
option go_package = "example.com/hello/gen/greeter/v1;greeterv1";

service Greeter {
  rpc SayHello(HelloRequest) returns (HelloReply);
}

message HelloRequest { string name = 1; }
message HelloReply   { string message = 1; }

Then generate Go code:

Terminal
protoc \
  --proto_path=proto \
  --go_out=gen --go_opt=paths=source_relative \
  --go-grpc_out=gen --go-grpc_opt=paths=source_relative \
  proto/greeter/v1/greeter.proto

You get two files: greeter.pb.go (message types) and greeter_grpc.pb.go (client and server code). Never edit them by hand; they are regenerated each time, and you should either commit them or generate them in CI consistently.

For Python the equivalent is:

Terminal
python -m grpc_tools.protoc -Iproto --python_out=gen --grpc_python_out=gen proto/greeter/v1/greeter.proto

The modern workflow: buf

Long protoc command lines are easy to get wrong. buf replaces them with two small config files.

YAML
# buf.yaml
version: v2
modules:
  - path: proto
lint:
  use: [STANDARD]
breaking:
  use: [FILE]
YAML
# buf.gen.yaml
version: v2
plugins:
  - remote: buf.build/protocolbuffers/go
    out: gen
    opt: paths=source_relative
  - remote: buf.build/grpc/go
    out: gen
    opt: paths=source_relative
Terminal
buf lint        # style checks on your .proto files
buf generate    # run all plugins
buf breaking --against '.git#branch=main'   # detect incompatible changes

buf breaking is especially valuable: it compares your branch to main and fails if you removed a field or changed a type. See the later chapter on versioning on the track page.

What the compiler really does

flowchart LR
  A[".proto files"] --> B["protoc parses and checks"]
  B --> C["FileDescriptorSet (a description of your contract)"]
  C --> D["protoc-gen-go"]
  C --> E["protoc-gen-go-grpc"]
  C --> F["other plugins"]
  D --> G["greeter.pb.go"]
  E --> H["greeter_grpc.pb.go"]

A plugin is an ordinary program that reads a description on standard input and writes files on standard output.

That description step is the key idea. protoc parses, validates and resolves names. Plugins only turn the finished description into code.

Stand-in 1: a tiny .proto parser

This runnable program is a stand-in, not protoc. It reads a very small subset of the language (messages with scalar fields) and prints a structured description, like the parsing half of a compiler.

Go Stand-in: parse a small .proto

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with bufio.Scanner or fmt.Scan), it gets the next line from this box.

Stand-in 2: a tiny code generator

The second half of a compiler turns the description into source code. This stand-in produces Go structs from the parsed messages, much like protoc-gen-go does (the real one also writes serialization code).

Go Stand-in: generate Go structs

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with bufio.Scanner or fmt.Scan), it gets the next line from this box.

Notice is_ok became IsOk. Real generators follow the same kind of naming rules per language: snake_case in the contract, idiomatic names in the generated code.

Common installation problems

  • protoc-gen-go: program not found. The plugin binary is not on your PATH. Add Go's bin folder.
  • Mismatched versions. Generated code expects a runtime library of a compatible version. Upgrade protobuf and grpc libraries together with the plugins.
  • Import errors. --proto_path (or -I) must contain the root from which imports are written. See packages, imports and options.
  • Wrong go_package. Without an option go_package the Go plugin refuses to generate.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does protoc do by itself?

    protoc is language neutral. Plugins such as protoc-gen-go write the actual code.
  2. 2. Which executable does --go_out make protoc run?

    protoc looks for a program named protoc-gen-NAME on your PATH for --NAME_out.
  3. 3. What does buf breaking check?

    It compares your contract with a reference such as main and reports removed fields or changed types.
  4. 4. Which two files does the Go gRPC workflow normally produce?

    One file holds message types, the other holds client and server code.

Summary

  • protoc parses .proto files; language plugins generate code from its description.
  • Install protoc, then protoc-gen-go and protoc-gen-go-grpc for Go, or grpcio-tools for Python.
  • buf simplifies generation and adds linting and breaking-change checks.
  • Generated files must not be edited by hand.
  • Our Go stand-ins parse a small .proto subset and generate structs to show the idea.

Next: Hello World Service