Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Servers, nginx and Docker

Your Go program or go command says not found inside an Alpine container

Errorgo: not found when you run the go command in the container

Short 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.

  • Applies to Go 1.24, Alpine Linux 3.22, Docker Engine 28
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 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/go
  2. 2Match what you see, then jump to its fix

    1. 1ls 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. 2The file exists and is executable, yet running it prints 'not found'The binary was built with cgo against glibc and Alpine uses muslFix
    3. 3A 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

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/bin

2Fix

Set PATH in the Dockerfile, or start from the golang image, which already provides go.

ENV PATH=$PATH:/usr/local/go/bin

3Verify

go reports its version.

go version

Confirmed by go.dev

Did this fix it?

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_ENABLED

2Fix

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-app

Confirmed by pkg.go.dev

Did this fix it?

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 bash

2Fix

Install the tools in the build stage with apk add and the exact package names.

RUN apk add git gcc

3Verify

The tools are found and the build step passes.

command -v gcc git

Confirmed by hub.docker.com

Did this fix it?

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

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.