Python "locale.Error: unsupported locale setting" in CI

locale.Error: unsupported locale setting is raised by locale.setlocale when the requested locale is not installed/generated on the system. Minimal CI images often ship only the C/POSIX locale, so a call expecting en_US.UTF-8 fails.

What this error means

A step fails with "locale.Error: unsupported locale setting" on a setlocale call, or a library that sets a locale at import fails on a minimal runner.

python

locale.Error: unsupported locale setting

Common causes

The requested locale is not generated on the runner

A minimal image only has C/POSIX, so setting en_US.UTF-8 (or similar) fails.

Hard-coded locale name that differs from the OS

Code set a specific locale string the runner OS does not provide.

How to fix it

Generate the locale or use a portable setting

Generate the needed locale on the runner, or set LANG/LC_ALL to one that exists (e.g. C.UTF-8).
Avoid hard-coding a locale; fall back gracefully if setlocale fails.
Set LC_ALL/LANG in the CI job environment so all steps agree.

Python

import locale
try:
    locale.setlocale(locale.LC_ALL, "C.UTF-8")
except locale.Error:
    locale.setlocale(locale.LC_ALL, "")

How to prevent it

Prefer C.UTF-8 in minimal CI images, or generate the locale you need.
Set LANG/LC_ALL consistently in the job env.
Make setlocale calls tolerant of missing locales.