protoc "protoc: command not found" in CI

By Daniel Zoghalchali·Latchkey

The shell could not find a protoc executable on PATH. GitHub-hosted runners do not ship the Protocol Buffers compiler, so any step that calls protoc fails until you install it in an earlier step.

What this error means

A codegen step calling protoc ... fails with "protoc: command not found" and the job exits 127, even though your Makefile runs it fine locally.

/home/runner/work/_temp/script.sh: line 1: protoc: command not found
Error: Process completed with exit code 127.

Common causes

protoc is not installed on the runner

GitHub-hosted images do not include the Protocol Buffers compiler by default, so protoc is absent unless a step installs it.

protoc was extracted but its bin/ is not on PATH

You downloaded the release zip but never added the extracted bin directory to GITHUB_PATH, so the shell cannot find the binary.

How to fix it

Install protoc with a setup action

1. Add a setup step that installs a pinned protoc version.
2. Run it before any codegen step.
3. Confirm with protoc --version in the same job.

- uses: arduino/setup-protoc@v3
  with:
    version: '27.2'
- run: protoc --version

Install via the OS package manager

On Ubuntu runners you can install the distribution package, though the version lags the upstream release.

sudo apt-get update && sudo apt-get install -y protobuf-compiler
protoc --version

How to prevent it

• Pin an exact protoc version so codegen output is reproducible.
• Install protoc in a dedicated setup step before generation.
• Verify with protoc --version early so a missing binary fails fast.

Frequently asked questions

Related guides

References

• GitHub Actions documentation