How to fix perl: warning: Setting locale failed in APT

APTBEGINNERLOWUpdated Sep 22, 2026· 246 views

This warning occurs when Perl cannot find the locale configuration specified in your environment variables. It typically appears when using apt or Perl scripts on systems where locale packages are not fully installed or configured.

Quick fix

Fixes perl: warning: Setting locale failed

locale -a
  1. List available locales on your system
  2. Generate the required locale using locale-gen
  3. Set your system locale using update-locale
  4. Verify locale configuration
apt — error
locale -a
perl: warning: Setting locale failed

What this error means

The "perl: warning: Setting locale failed" warning indicates that Perl tried to set a locale (language and regional settings) based on your environment variables, but that locale is not available on your system. Perl checks the LC_ALL, LANG, and other locale environment variables to determine which locale to use for character encoding, sorting, and number formatting. When the specified locale (such as en_US.UTF-8) is not installed or generated on your system, Perl issues this warning and falls back to the basic "C" locale. This warning is often triggered by apt, apt-get, and other Perl-based package management tools in Debian and Ubuntu systems. It's typically harmless but indicates that your system's locale configuration needs attention.

Typical symptoms

  • Warning appears when running apt, apt-get, or other package management commands
  • Warning shows during Perl script execution
  • Message mentions "Please check that your locale settings"
  • LANG or LC_ALL environment variables are referenced in the warning
  • System falls back to the "C" (basic ASCII) locale
  • Perl commands execute successfully despite the warning

Common causes

  1. The specified locale (e.g., en_US.UTF-8) is not generated on the system
  2. Locale packages are not fully installed
  3. Environment variables (LANG, LC_ALL) point to a non-existent locale
  4. Fresh system installation without locale configuration
  5. SSH connections propagating client locale settings to a server that does not have them installed
  6. Locale generation process was interrupted or incomplete
  7. Using a minimal or containerized OS image without full locale support

How to fix "perl: warning: Setting locale failed"

1List available locales on your system

First, check which locales are currently available on your system:

bash
locale -a

This shows all installed and generated locales. If en_US.UTF-8 is missing, you need to generate it.

2Generate the required locale using locale-gen

On Debian and Ubuntu systems, use the locale-gen command to generate the locale you need:

bash
sudo locale-gen en_US.UTF-8

This creates the en_US.UTF-8 locale. You can replace en_US.UTF-8 with your desired locale (e.g., de_DE.UTF-8, fr_FR.UTF-8).

3Set your system locale using update-locale

After generating the locale, update your system-wide locale settings:

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

This modifies /etc/default/locale and sets en_US.UTF-8 as the default locale for all users.

4Verify locale configuration

Check that your locale settings are now correct by running:

bash
locale

This displays all locale environment variables. Confirm that LANG is set to your desired locale:

bash
LANG=en_US.UTF-8
LANGUAGE=
LC_CTYPE="en_US.UTF-8"
LC_NUMERIC="en_US.UTF-8"
LC_TIME="en_US.UTF-8"
...
5Use dpkg-reconfigure locales for interactive configuration

Alternatively, you can use the interactive dpkg-reconfigure command, which is often easier:

bash
sudo dpkg-reconfigure locales

This opens a menu where you can:
1. Select which locales to generate (use arrow keys and spacebar)
2. Choose which locale becomes the default
3. Confirm your selection

Select at least one locale (e.g., en_US.UTF-8) and choose it as the default in the next step.

6Temporary workaround: Set locale in your shell

If you cannot use sudo, you can temporarily suppress the warning by setting LC_ALL in your current session:

bash
export LC_ALL=C.UTF-8

Or set it to your available locale:

bash
export LC_ALL=C

This prevents Perl from attempting to use unavailable locales. To make this permanent, add the export line to your ~/.bashrc or ~/.zshrc file.

Advanced notes

SSH Remote Connection Issues: When connecting to a remote server via SSH, your client machine's locale settings (LANG, LC_*) may be propagated to the server. If the server doesn't have those locales installed, you'll see this warning. To prevent this, modify the SSH server configuration by editing /etc/ssh/sshd_config and commenting out the line:

bash
# AcceptEnv LANG LC_*

Then reload SSH: sudo systemctl reload ssh

Containerized Environments: Docker and minimal cloud images often don't include locale packages. Install them with:

bash
apt-get update && apt-get install -y locales
locale-gen en_US.UTF-8

Environment Variable Precedence: LC_ALL overrides all other locale variables (LC_CTYPE, LC_TIME, etc.). According to Debian best practices, avoid setting LC_ALL permanently in startup files as it's too broad. Instead, set individual LC_* variables as needed.

Perl BADLANG: You can silence Perl locale warnings without fixing locales by setting PERL_BADLANG to 0, but this masks the underlying problem. This is a temporary workaround only:

bash
export PERL_BADLANG=0

UTF-8 Encoding: Note that "UTF-8" alone is not a valid locale—it must be paired with a region code like "en_US.UTF-8" or "C.UTF-8". The "C.UTF-8" locale is a minimalist UTF-8 locale available in most modern systems and is useful when you don't need language-specific settings.

Frequently asked questions

What does "perl: warning: Setting locale failed" mean?
The "perl: warning: Setting locale failed" warning indicates that Perl tried to set a locale (language and regional settings) based on your environment variables, but that locale is not available on your system. Perl checks the LC_ALL, LANG, and other locale environment variables to determine which locale to use for character encoding, sorting, and number formatting. UTF-8) is not installed or generated on your system, Perl issues this warning and falls back to the basic "C" locale.
How do I fix "perl: warning: Setting locale failed"?
This warning occurs when Perl cannot find the locale configuration specified in your environment variables. It typically appears when using apt or Perl scripts on systems where locale packages are not fully installed or configured.
What causes "perl: warning: Setting locale failed"?
The specified locale (e.g., en_US.UTF-8) is not generated on the system Locale packages are not fully installed Environment variables (LANG, LC_ALL) point to a non-existent locale
Is the "perl: warning: Setting locale failed" error serious?
It is a low-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading