Skip to content

Protobuf Go Tool Differences: Detailed Explanation of protoc / protoc-gen-go / protoc-gen-go-grpc | Pitfalls in Go gRPC Code Generation ​

Schematic diagram for clearly distinguishing the Protobuf Go trio

Companion screenshot version:

One-sentence overview ​

Many people confuse these three; the root cause is that protoc is the compiler itself, while the other two are independent plugins with different responsibilities and generate code separately.

  • protoc: protobuf compiler, responsible for parsing .proto File, scheduling plugin

  • protoc-gen-go: Generate message structure, corresponding xxx.pb.go

  • protoc-gen-go-grpc: Generate gRPC service, client stub, corresponding to xxx_grpc.pb.go

Looking at the screenshot confirms: acl.pb.go File header annotation Code generated by protoc-gen-goacl_grpc.pb.go File header annotation Code generated by protoc-gen-go-grpc

Project Address & Detailed Explanation of Purpose ​

1. protoc (Protocol Buffers compiler) ​

Warehouse address:https://github.com/protocolbuffers/protobuf

  • Official repository, C++ implementation, is the core program

  • Effect

  • Parse .proto Protocol file, validate syntax

  • It does not directly generate Go code by itself

  • Through the plugin mechanism, external plugins are invoked to generate code in the corresponding language.

  • Command characteristics:protoc --go_out=. --go-grpc_out=. acl.proto

  • Screenshot version:protoc v3.15.8

You can simply understand it as: protoc is a scheduler; it does not directly generate business code, but is responsible for calling plugins to complete code generation.

2. protoc-gen-go (Go protobuf message plugin) ​

Repository address:https://github.com/golang/protobuf Module path:google.golang.org/protobuf/cmd/protoc-gen-go

  • Effect

  • Generate xxx.pb.go File containing Go structs for message and enum, and serialization and deserialization methods

  • Only process data structures, do not generate any gRPC service code.

  • In the corresponding screenshot acl.pb.go, annotation labeling protoc-gen-go v1.23.0

  • Installation command

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

3. protoc-gen-go-grpc (Go gRPC service plugin) ​

Warehouse address:https://github.com/grpc/grpc-go Module path:google.golang.org/grpc/cmd/protoc-gen-go-grpc

  • Effect

  • Generate xxx_grpc.pb.go File containing service interfaces, service registration methods, and client invocation stubs

  • Only recognize in proto files service Definition, does not process ordinary messages

  • In the corresponding screenshot acl_grpc.pb.go, annotation labeling protoc-gen-go-grpc v1.1.0

  • Installation command

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

💡 Note

Certain versions of protoc-gen-go-grp need to be compiled manually!

Version comparison + Generated file comparison table ​

ToolProduct file nameCore contentWarehouse
protoc-Parse proto, scheduling pluginprotocolbuffers/protobuf
protoc-gen-goxxx.pb.goMessage, Enum, serialization logicgolang/protobuf
protoc-gen-go-grpcxxx_grpc.pb.goService, Server interface, Client stubgrpc/grpc-go

Legacy pitfall reminder

In earlier versions, protoc-gen-go generated both pb and grpc code simultaneously, with a single plugin handling the generation of both types of files. Later versions split it, so the two plugins must be installed separately and their output parameters specified separately; if either plugin is missing, the corresponding code will be missing. Standard notation:--go_out Hand it over to the message plugin,--go-grpc_out Hand it over to the grpc plugin.

Minimal proto example acl.proto ​

protobuf
syntax = "proto3";

package acl;
option go_package = "./acl;acl";

message CheckRequest {
  string user_id = 1;
  string resource = 2;
}

message CheckResponse {
  bool allow = 1;
  string reason = 2;
}

service AclService {
  rpc Check(CheckRequest) returns (CheckResponse);
}

Description:

  • syntax = "proto3" Using proto3 syntax is currently mainstream.

  • go_package Control the package path of the generated code, format 输出路径;包名

  • message will be compiled into by protoc-gen-go acl.pb.go

  • service will be compiled into by protoc-gen-go-grpc acl_grpc.pb.go

Standard generation command ​

bash
protoc --go_out=. --go_opt=paths=source_relative \
       --go-grpc_out=. --go-grpc_opt=paths=source_relative \
       acl.proto
  • --go_out: Specify the output of protoc-gen-go

  • --go-grpc_out: Specify the output of protoc-gen-go-grpc

  • paths=source_relative Using the directory containing the proto file as the relative path is most commonly used in daily development.

Makefile script ​

New Makefile, placed in the same directory as the proto file

makefile
# Generate proto code
.PHONY: proto
proto:
	protoc --go_out=. --go_opt=paths=source_relative \
	--go-grpc_out=. --go-grpc_opt=paths=source_relative \
	acl.proto

# Clean up the generated code
.PHONY: clean
clean:
	rm -f acl.pb.go acl_grpc.pb.go

# View tool version
.PHONY: version
version:
	protoc --version
	protoc-gen-go --version
	protoc-gen-go-grpc --version

Usage:

bash
# Generate code
make proto
# Clean generated files
make clean
# Check the versions of the three local tools
make version

Check the versions of the three tools on this machine ​

bash
# Check the protoc compiler version
protoc --version

# Check the protoc-gen-go version
protoc-gen-go --version

# Check the protoc-gen-go-grpc version
protoc-gen-go-grpc --version

The header comment of the generated pb.go file records the tool version used during generation, for aligning environments and troubleshooting version compatibility issues.

Summary of Common Misconceptions ​

  • Misconception 1: protoc can directly generate Go code

  • Correction: protoc is just a dispatcher and relies on plugins to generate Go code

  • Misconception 2: protoc-gen-go can generate gRPC service code

  • Correction: after the split, it is only responsible for message structures, and the gRPC code is handled separately by protoc-gen-go-grpc.

  • Misconception 3: The two plugin versions must be exactly the same.

  • Correction: version numbers do not need to match; they only need to be compatible across versions. For production, it is recommended to pin versions to avoid inconsistent code produced locally and in CI.

Compare one by one against the screenshot ​

go
// acl.pb.go
// Code generated by protoc-gen-go. DO NOT EDIT.
// versions:
//  protoc-gen-go v1.23.0
//  protoc        v3.15.8
// source: acl.proto
go
// acl_grpc.pb.go
// Code generated by protoc-gen-go-grpc. DO NOT EDIT.
// versions:
// - protoc-gen-go-grpc v1.1.0
// - protoc             v3.15.8
// source: acl.proto

Both files record the protoc version, but each records the version of its own plugin, which is why the plugin versions in the headers of the two files are different.

Directory structure reference ​

.
├── acl.proto
├── acl.pb.go
├── acl_grpc.pb.go
└── Makefile
Last updated on11/18/2026, 12:10 PM
@fishfinal | @fishfinals | [email protected]