The ErrorYou probably hit this wall while running go build or go run on a project that pulls in C-based dependencies. The error message is blunt:
cgo: C compiler "gcc" not found: exec: "gcc": executable file not found in %PATH%
Why This HappensGo usually compiles into a single static binary without needing external tools. However, many popular libraries—like the SQLite driver (go-sqlite3) or Kafka clients—rely on CGO. This bridge lets Go talk to existing C code.
Without a C compiler like GCC, Go can't process these low-level files. If gcc isn't in your system's PATH, the build toolchain simply gives up. You need a working compiler to bridge the gap between Go and C.
How to Fix It on WindowsWindows doesn't ship with a C compiler, which is why this error hits Windows users hardest. You have three reliable ways to get GCC up and running.
Option 1: Chocolatey (The Quickest Way)If you already use Chocolatey, you can skip the manual downloads. Open an Admin PowerShell and run this command:
choco install mingw
This installs the MinGW-w64 distribution. Once it finishes (usually taking 2–3 minutes), restart your terminal to refresh your environment variables.
Option 2: MSYS2 (Best for Long-term Stability)MSYS2 is a robust environment that provides modern GCC builds. It is the preferred choice for many Go contributors.
- Download the installer from msys2.org.- Launch the MSYS2 UCRT64 terminal.- Run this command to grab the full toolchain:``` pacman -S --needed base-devel mingw-w64-ucrt-x86_64-toolchain
Finally, add `C:\msys64\ucrt64\bin` to your Windows System PATH. This ensures Go can find `gcc.exe` whenever you build a project.
### Option 3: Manual Installation- Download the MinGW-w64 files from GitHub or SourceForge.- Extract them to a clean directory like `C:\mingw64`.- Open the Start menu and search for "Edit the system environment variables."- Under **System Variables**, find **Path** and click **Edit**.- Add `C:\mingw64\bin` to the list and save your changes.## How to Fix It on LinuxLinux distributions make this easy. You just need to install the standard development packages, which usually take up about 100MB of disk space.
### Ubuntu / Debian / Mint```
sudo apt update && sudo apt install build-essential
CentOS / RHEL / Fedora```
sudo dnf groupinstall "Development Tools"
### Arch Linux```
sudo pacman -S base-devel
How to Fix It on macOSApple provides a streamlined package called Command Line Tools. You don't need the massive 12GB Xcode IDE; a small 500MB download will suffice.
xcode-select --install
Click "Install" on the software update popup. Once finished, gcc (which is actually a shortcut to the Clang compiler on Mac) will be ready for use.
The "I Don't Need CGO" WorkaroundSometimes you don't actually need a C compiler. If your project doesn't strictly require C features, you can tell Go to skip CGO entirely. This creates a more portable binary and bypasses the GCC requirement.
Try building with the CGO_ENABLED flag set to zero:
# Windows (PowerShell)
$env:CGO_ENABLED="0"; go build
# Linux / macOS
CGO_ENABLED=0 go build
A word of caution: If you are using github.com/mattn/go-sqlite3, this will fail. That specific library requires CGO. If you must go C-free, switch to a pure Go alternative like modernc.org/sqlite.
Verification: Is It Fixed?Open a fresh terminal window. Run this command to check your compiler version:
gcc --version
You should see something like gcc (MinGW-W64) 13.2.0. Now, verify that Go recognizes the change:
go env CGO_ENABLED
go build ./...
If go env returns 1 and your build finishes without errors, you've successfully configured your environment.