Go / Gin

How to Fix Go cgo Compilation Error: C Compiler Not Found in PATH on Windows/macOS

4 min read by DebuggedIt

Quick answer

Building a Go project that uses cgo (directly, or indirectly through a dependency that wraps a C library) fails because Go can't find a C compiler on your...

Building a Go project that uses cgo (directly, or indirectly through a dependency that wraps a C library) fails because Go can't find a C compiler on your system. Unlike pure Go code, cgo-enabled packages need an actual C toolchain installed and reachable, which isn't part of a standard Go installation on Windows or macOS.

The Problem

A build that should work fails with a clear but easy-to-overlook message:

$ go build .
# runtime/cgo
cgo: C compiler "gcc" not found: exec: "gcc": executable file not found in %PATH%

On macOS, it's often phrased slightly differently but points at the same root issue:

$ go build .
xcrun: error: invalid active developer path
(/Library/Developer/CommandLineTools), missing xcrun at:
/Library/Developer/CommandLineTools/usr/bin/xcrun

Why It Happens

cgo allows Go code to call into C code directly, and any package using it — including many popular packages that wrap native libraries for SQLite, image processing, or certain cryptographic operations — needs an actual C compiler present at build time to compile that C portion. The Go toolchain itself doesn't bundle one, so this is entirely dependent on your system having a separate C toolchain installed and discoverable. This error shows up because:

  • No C compiler is installed at all — common on a fresh Windows machine, where MinGW/GCC isn't installed by default, or on a Mac where Xcode Command Line Tools were never set up.
  • A C compiler is installed but not on PATH, so Go's cgo tooling can't find it even though it technically exists somewhere on disk.
  • Xcode Command Line Tools were installed previously but became invalid after a macOS update, which can happen after major OS upgrades.
  • CGO_ENABLED is set to 1 (the default on most platforms) for a build that doesn't actually need cgo, and a stray dependency pulls in a cgo-requiring package unintentionally.

The Fix

On macOS, install Xcode Command Line Tools, which include a full C compiler (clang) and are the standard, lightweight way to get a working C toolchain without installing the entire Xcode IDE:

xcode-select --install

If it reports tools are already installed but the build still fails, the installation may have become invalid after a system update — reset and reinstall:

sudo xcode-select --reset
xcode-select --install

Verify the compiler is now reachable:

gcc --version
Apple clang version 15.0.0

On Windows, install MinGW-w64 (or an equivalent GCC distribution like TDM-GCC), since Windows has no built-in C compiler at all:

# Using the MSYS2 project's package manager, a common modern approach
# Download and run the MSYS2 installer from msys2.org, then:
pacman -S mingw-w64-ucrt-x86_64-gcc

Add the compiler's bin directory to your system PATH so Go's cgo tooling can find it:

# Add to PATH, e.g. via System Properties -> Environment Variables
C:\msys64\ucrt64\bin

Open a new terminal (environment variable changes don't apply to already-open shells) and verify:

gcc --version

If you don't actually need cgo for your specific build and just want the build to succeed without installing a C toolchain at all, disable it explicitly — this only works if none of your actual dependencies genuinely require cgo:

set CGO_ENABLED=0
go build .
# macOS/Linux equivalent
CGO_ENABLED=0 go build .

Disabling cgo also has the side benefit of producing a fully statically linked binary with no external C library dependencies at runtime, which is often desirable for deployment simplicity — but only do this if you've confirmed your actual dependency tree doesn't require it, or those specific packages will simply fail to build instead.

Still Not Working?

If a C compiler is confirmed installed and on PATH, but the build still fails, check whether Go itself is picking up the correct compiler by inspecting its own environment configuration directly:

go env CC

If this returns a path to a compiler that doesn't actually exist or isn't the one you just installed, override it explicitly:

go env -w CC=gcc

Or, for a specific full path if multiple compilers are installed and you need to be precise about which one Go uses:

go env -w CC=C:\msys64\ucrt64\bin\gcc.exe

You might also like