Your Go program or go command says not found inside an Alpine container
go: not found when you run the go command in the containerShort answer
On Alpine, 'not found' has two meanings: the shell cannot find the go command because /usr/local/go/bin is not on PATH, or the kernel cannot start your binary because it links to glibc, which Alpine does not have (it uses musl). Check PATH first, then how the binary was linked.
Fix it fast
1Find out which cause you have
Separate the two cases: ask whether the shell can find go, then ask whether your binary is dynamically linked.
command -v go; echo $PATH ls -l /usr/local/go/bin/go2Match what you see, then jump to its fix
- 1
ls finds /usr/local/go/bin/go but command -v go prints nothingThe Go toolchain is on disk but /usr/local/go/bin is not on PATHFix - 2
The file exists and is executable, yet running it prints 'not found'The binary was built with cgo against glibc and Alpine uses muslFix - 3
A build step on golang:alpine fails with another not found, such as gcc: not found or git: not foundThe Alpine image has no gcc, git or bash that your build step assumesFix
- 1
What does the error look like?
go: not found when you run the go command in the container./app: not found although the file exists and is executable
Cause 1 of 3
The Go toolchain is on disk but /usr/local/go/bin is not on PATH
1Check
Go's own install guide adds /usr/local/go/bin to PATH by hand. A new image or build stage starts without it, for example after COPY --from=golang ... /usr/local/go.
echo $PATH | tr ':' '\n' | grep -c /usr/local/go/bin2Fix
Set PATH in the Dockerfile, or start from the golang image, which already provides go.
ENV PATH=$PATH:/usr/local/go/bin3Verify
go reports its version.
go versionConfirmed by go.dev
Cause 2 of 3
The binary was built with cgo against glibc and Alpine uses musl
1Check
The Alpine-based Go image uses musl libc instead of glibc, which can lead to unexpected behaviour. A cgo build links to the C library of the image that built it. cgo is on by default for native builds when a C compiler is found.
go env CGO_ENABLED2Fix
Build without cgo so the program has no C library dependency, then copy it into Alpine. Or build in a golang:alpine stage so it targets musl.
FROM golang:1.24 AS build
WORKDIR /src
COPY . .
RUN CGO_ENABLED=0 go build -o /out/app .
FROM alpine:3.22
COPY --from=build /out/app /app
CMD ["/app"]3Verify
The container starts and runs the program.
docker run --rm my-go-appConfirmed by pkg.go.dev
Cause 3 of 3
The Alpine image has no gcc, git or bash that your build step assumes
1Check
To keep the image small, Alpine-based images leave out tools such as git, gcc and bash, and you add what you need in your own Dockerfile.
command -v gcc git bash2Fix
Install the tools in the build stage with apk add and the exact package names.
RUN apk add git gcc3Verify
The tools are found and the build step passes.
command -v gcc gitConfirmed by hub.docker.com
How do I stop it coming back?
- Decide on CGO_ENABLED per project and write it in the Dockerfile, so builds are the same on every machine.
- Use a multi-stage build: compile in the golang image, run in a small image.
- Run the final image once in CI to catch start-up errors early.
Sources
How was this page made?
I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.
Which stack is behind this page?
Projects of mine built on the same technologies:
Related fixes
Servers
Docker build fails with apk: not found in a Python or Ubuntu image
/bin/sh: 1: apk: not found
apk is the package manager of Alpine Linux only.
2 causes, each with a fixServers
Apache logs SIGWINCH and exits on its own
the httpd container stops although nothing crashed
SIGWINCH is Apache's graceful-stop signal.
2 causes, each with a fixServers
sam local fails: Running AWS SAM projects locally requires Docker
Cannot connect to the Docker daemon. Is the docker daemon running on this host?
sam local start-api and sam local invoke run your function inside a Docker container, so SAM stops if it cannot talk to Docker.
3 causes, each with a fixServers
dnf fails to download repo metadata in a CentOS 8 Docker build
The same Dockerfile built fine before 2022
CentOS Linux 8 reached end of life on 31 December 2021 and its content left the mirrors.
2 causes, each with a fixServers
pip install confluent-kafka fails because librdkafka/rdkafka.h is missing
pip stops while building confluent-kafka from source
The error means pip is compiling confluent-kafka from source, and the compiler cannot find the librdkafka C headers.
3 causes, each with a fixServers
Cypress says the npm package is installed but the binary is missing
Cypress binary is missing after npm install in CI or in a Docker build
The npm package is only a launcher.
3 causes, each with a fix