Introduction

locale.Error: unsupported locale setting during pip install usually means Python is trying to use a locale value that the operating system does not actually provide. The most common cause is an invalid LANG, LC_ALL, or related environment variable. The fix is usually to inspect the available locales, switch to a valid one such as C.UTF-8 or en_US.UTF-8, and regenerate the locale if the system does not have it installed.

Why pip Cares About Locale

pip itself is not a locale tool, but it runs inside Python, and Python consults locale settings for text handling and environment behavior. If the shell exports a locale that the OS does not support, Python can fail before pip even gets to the package installation logic.

Typical problematic variables include:

• 'LANG'
• 'LC_ALL'
• 'LC_CTYPE'

If one of those points at a nonexistent locale, pip install may crash with the unsupported-locale error.

See Which Locales Exist

On Unix-like systems, first inspect what the machine actually supports.

locale -a

That command lists valid locale names such as:

C
C.UTF-8
en_US.utf8

If your environment is set to something not present in that list, Python has a good reason to reject it.

Check Your Current Environment

echo "$LANG"
echo "$LC_ALL"
echo "$LC_CTYPE"

If one of these contains an unsupported value, replace it with a valid locale.

A quick temporary fix is often:

export LC_ALL=C.UTF-8
export LANG=C.UTF-8

Then retry:

pip install some-package

C.UTF-8 is a common safe choice on many modern Linux environments.

Use a Valid UTF-8 Locale

If C.UTF-8 is unavailable, try a locale your system actually lists, for example:

export LC_ALL=en_US.UTF-8
export LANG=en_US.UTF-8

The exact capitalization and spelling matter. On some systems the locale appears as en_US.utf8 while environment variables conventionally use en_US.UTF-8. Check what your platform expects.

Generate the Locale if It Does Not Exist

On Linux, the locale may simply not be generated yet. On Debian or Ubuntu-style systems, that often looks like:

sudo locale-gen en_US.UTF-8
sudo update-locale LANG=en_US.UTF-8

After generating it, open a fresh shell and try again.

In containers or minimal images, this is especially common because the image may ship with almost no locales installed.

Docker and CI Environments

In Dockerfiles or CI jobs, it is common to see locale problems because the environment is minimal. A pragmatic fix is to set a valid UTF-8 locale explicitly.

ENV LANG=C.UTF-8
ENV LC_ALL=C.UTF-8

This is often enough for Python tooling in lightweight images.

If the base image does not support that locale, install or generate the needed locale as part of the image build.

Avoid Invalid Manual Exports

A common root cause is a shell profile that exports a locale name copied from another machine.

Example of a potentially bad line in ~/.bashrc or ~/.zshrc:

export LC_ALL=en_US.UTF-8

If the machine does not actually provide that locale, every Python process inherits a broken environment. In that case, the real fix is not just one pip install command. It is correcting the startup file so future shells use a valid locale.

Quick Temporary Workaround

If you just need pip to run once and do not want to edit shell config immediately, use an inline environment override:

LC_ALL=C.UTF-8 LANG=C.UTF-8 pip install some-package

This is useful for testing or for one-off debugging in build scripts.

Common Pitfalls

A common mistake is setting LC_ALL to a locale name that looks valid but is not installed on the system. The environment variable alone does not create the locale.

Another issue is fixing only LANG while LC_ALL still points to an invalid value. LC_ALL overrides the more general locale variables, so it often remains the real problem.

Developers also sometimes repair the current shell manually but forget that their shell startup files still export the bad locale, so the error returns in the next session.

Finally, minimal Docker or CI images often need explicit locale setup. What works on a full desktop Linux install may not exist there.

Summary

• The error means Python received a locale value the OS does not support.
• Check available locales with locale -a.
• Set LANG and LC_ALL to a real locale such as C.UTF-8 or another installed UTF-8 locale.
• Generate the locale if the system does not already have it.
• Fix shell startup files or container config so the problem does not return in later sessions.