locale-gen is missing while building a Dockerfile on the Ubuntu image
/bin/sh: 1: locale-gen: not foundShort answer
The Ubuntu base image is minimal and ships without the locales package, which is what provides locale-gen. Install locales after apt-get update, generate the locale you need, and set LANG. If you only need UTF-8, skip all of it and set LANG=C.UTF-8, which the image already includes.
Fix it fast
1Find out which cause you have
Build a throwaway container from your base image and ask the shell whether the command exists. No output means the package is not installed.
docker run --rm ubuntu:24.04 sh -c 'command -v locale-gen; locale -a'2Match what you see, then jump to its fix
- 1
/bin/sh: 1: locale-gen: not found, exit code 127The locales package is not installed in the imageFix - 2
Python or a CLI tool complains about the encoding and you added locale-gen only to fix thatYou only need UTF-8, so no new locale is neededFix - 3
The build passes, but the locale you built is not the one the process usesThe locale was built with localedef but LANG still points elsewhereFix
- 1
What does the error look like?
/bin/sh: 1: locale-gen: not foundThe command '/bin/sh -c locale-gen en_US.UTF-8' returned a non-zero code: 127
Cause 1 of 3
The locales package is not installed in the image
1Check
The locale-gen command comes from the locales package. A minimal base image does not include it, and its package index is empty until apt-get update has run.
docker run --rm ubuntu:24.04 sh -c 'dpkg -s locales'2Fix
Update the package index and install locales in the same RUN step, then generate the locale and export it.
RUN apt-get update && apt-get install -y locales \
&& rm -rf /var/lib/apt/lists/* \
&& locale-gen en_US.UTF-8
ENV LANG=en_US.UTF-83Verify
Build the image and list the locales inside it.
docker build -t locale-test .
docker run --rm locale-test locale -aConfirmed by manpages.ubuntu.com
Cause 2 of 3
You only need UTF-8, so no new locale is needed
1Check
The Ubuntu image already contains the locales C, C.UTF-8 and POSIX. For most UTF-8 needs C.UTF-8 is enough, so no package or generation step is required.
docker run --rm ubuntu:24.04 locale -a2Fix
Remove the locale-gen line and set LANG to C.UTF-8, either in the Dockerfile or when you run the container.
ENV LANG=C.UTF-8
# or, per container
docker run -e LANG=C.UTF-8 my-image3Verify
The variable is set inside a running container.
docker run --rm -e LANG=C.UTF-8 ubuntu:24.04 sh -c 'echo $LANG'Confirmed by hub.docker.com
Cause 3 of 3
The locale was built with localedef but LANG still points elsewhere
1Check
Docker's own Ubuntu page builds extra locales with localedef after installing locales, and then sets LANG to match. A built locale does nothing until LANG names it.
docker run --rm my-image sh -c 'echo $LANG; locale -a'2Fix
Use the documented pattern: install locales, run localedef for the locale, then set LANG to its name.
RUN apt-get update && apt-get install -y locales && rm -rf /var/lib/apt/lists/* \
&& localedef -i en_US -c -f UTF-8 -A /usr/share/locale/locale.alias en_US.UTF-8
ENV LANG=en_US.utf83Verify
LANG prints the new name and locale -a lists it.
docker run --rm my-image sh -c 'echo $LANG; locale -a | grep en_US'Confirmed by hub.docker.com
How do I stop it coming back?
- Decide first whether you need a real locale or only UTF-8; most containers only need LANG=C.UTF-8.
- Always put apt-get update and apt-get install in the same RUN line so the index is never stale or empty.
- Set LANG in the Dockerfile so every container from the image behaves the same.
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
bash warns that it cannot change the locale after you log in to a server
bash: warning: setlocale: LC_ALL: cannot change locale (en_US.UTF-8)
The shell was told to use a locale that is not built on the server.
3 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