How to Use buf Instead of protoc for Managing Proto Files

Web
2026-04-17T16:32:01+00:00
Use `buf` as a drop-in replacement for `protoc` to gain better dependency management, linting, and breaking change detection, while keeping the same output format.

Use buf as a drop-in replacement for protoc to gain better dependency management, linting, and breaking change detection, while keeping the same output format. You configure your project with a buf.yaml file and run buf build or buf generate instead of manually invoking protoc with complex flags.

First, initialize your project and define your configuration. The buf.yaml file tells buf which directories to scan and which plugins to use. Unlike protoc, which requires you to manually resolve imports and specify include paths, buf automatically resolves dependencies from your module or a remote registry.

# buf.yaml
version: v1
name: buf.build/your-org/your-service
deps:
  - buf.build/googleapis/googleapis
  - buf.build/envoyproxy/envoy

lint:
  use:
    - STANDARD
    - FILE_LOWER_SNAKE_CASE
breaking:
  use:
    - FILE

To generate code, replace your protoc command with buf generate. You can specify the output directory and plugins directly in the command or via a buf.gen.yaml file for complex setups. This approach ensures that every developer and CI pipeline uses the exact same plugin versions and generation rules.

# Install buf
go install github.com/bufbuild/buf/cmd/buf@latest

# Generate Go code (equivalent to protoc --go_out=...)
buf generate --template buf.gen.yaml

# Or run a quick one-liner without a template file
buf generate --template 'buf.gen.yaml' --output ./pb

For CI/CD pipelines, buf excels at catching breaking changes before they merge. While protoc only checks for syntax errors, buf breaking compares your current proto files against a previous version (like main branch) to ensure API compatibility.

# Check for breaking changes against the main branch
buf breaking --against github.com/your-org/your-service#branch:main

# Run linting to enforce style guides
buf lint

The key advantage is consistency. With protoc, teams often drift into different generation scripts or miss dependency updates. buf centralizes this logic, making it impossible to accidentally generate code with mismatched dependencies or violate style rules. If you need to generate code for multiple languages, buf handles the orchestration of multiple plugins in a single command, whereas protoc requires chaining multiple invocations or complex shell scripts.