Maaz Zindani

Loading the index…

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

locale-gen is missing while building a Dockerfile on the Ubuntu image

Error/bin/sh: 1: locale-gen: not found

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

  • Applies to Docker Engine 28, Ubuntu 24.04 base image
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

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

    1. 1/bin/sh: 1: locale-gen: not found, exit code 127The locales package is not installed in the imageFix
    2. 2Python 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. 3The build passes, but the locale you built is not the one the process usesThe locale was built with localedef but LANG still points elsewhereFix

What does the error look like?

  • /bin/sh: 1: locale-gen: not found
  • The 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-8

3Verify

Build the image and list the locales inside it.

docker build -t locale-test .
docker run --rm locale-test locale -a

Confirmed by manpages.ubuntu.com

Did this fix it?

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

2Fix

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

3Verify

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

Did this fix it?

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

3Verify

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

Did this fix it?

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

Next step

Want this handled for good?

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