Troubleshooting UTF-8 Character Display Issue in gnome-terminal (zsh)

UTF-8 display issues in gnome-terminal with zsh are typically caused by locale misconfiguration, missing font support, or terminal emulator encoding settings. Verifying that the system locale is set to UTF-8 and that the terminal profile uses the correct character set resolves most rendering errors without requiring complex shell modifications.

Verify System Locale Configuration

The most common cause of garbled characters or question marks replacing glyphs is an incorrect system locale. The operating system must be configured to generate UTF-8 output, and the terminal emulator must respect this setting. You can check your current locale settings by running the locale command in your terminal. Look for variables such as LANG, LC_CTYPE, and LC_ALL. If these values do not end in .UTF-8, your system is likely generating non-UTF-8 byte sequences, which causes the terminal to fail when attempting to render multi-byte characters like emojis, CJK ideographs, or accented Latin letters. To fix this on Debian-based systems like Ubuntu, you should use the localectl tool or edit the configuration file located at /etc/default/locale. Ensure that the LANG variable is set to a valid UTF-8 locale, such as en_US.UTF-8 or C.UTF-8. After making changes, you must log out and log back in for the new locale settings to apply to all user sessions. If you are using a different distribution, consult your package manager's documentation for locale generation commands, but the principle remains the same: the environment variable must explicitly declare UTF-8 encoding.

Check Terminal Profile Encoding Settings

Even if your system locale is correct, gnome-terminal may be configured to use a different character encoding for its input and output streams. Open gnome-terminal and navigate to the menu bar. Click on Edit, then select Preferences. In the preferences window, go to the Profiles tab and select your active profile. Look for the General or Appearance section depending on your version of GNOME. There should be an option labeled "Character encoding" or "Encoding". Ensure this dropdown is set to Unicode (UTF-8). If it is set to Western (ISO-8859-1) or another legacy encoding, special characters will appear as mojibake or replacement characters. Some users might have accidentally changed this setting while troubleshooting other issues. Resetting it to automatic or explicitly selecting UTF-8 often resolves immediate display problems. Additionally, check the "Display" tab within the profile settings to ensure that the font selected supports the glyphs you are trying to display. A font lacking specific Unicode blocks will show boxes or tofu instead of the intended characters, regardless of encoding settings.

Inspect Zsh Configuration Files

While less common than system-level issues, zsh configuration files can sometimes interfere with character rendering if they contain explicit encoding overrides or problematic prompt themes. Check your .zshrc file for any lines that modify the LOCALE or ENCODING variables. Remove any manual exports that force non-UTF-8 locales. Furthermore, if you are using a powerline-enhanced prompt or a theme that relies on special symbols, ensure that the font you are using includes the necessary ligatures and glyphs. Powerline fonts require specific patches to include extra symbols. If your terminal displays squares where icons should be, the issue is likely a font mismatch rather than an encoding error. Install a patched font such as Font Awesome combined with a base font, or use a dedicated Nerd Font variant. In gnome-terminal, you can change the font under the Appearance tab in the profile preferences. Selecting a Nerd Font ensures that both standard text and special prompt symbols render correctly.

Test with a Fresh Environment

If the above steps do not resolve the issue, isolate the problem by launching zsh with a minimal configuration. Run the command zsh -f to start zsh without reading any startup files. Type a few special characters directly into this instance. If they display correctly, the problem lies within your .zshrc or .zprofile files. Comment out sections of your configuration file incrementally until the issue disappears, identifying the offending line. This methodical approach helps distinguish between shell configuration errors and terminal emulator limitations. For more information on resolving shell compatibility issues, you might find Bash Command Doesn't Work in ZSH: Troubleshooting helpful, as shell interoperability problems can sometimes manifest as unexpected behavior in mixed environments.

Frequently Asked Questions

Why do some characters still look wrong after setting UTF-8?

If the encoding is correct but characters remain broken, your selected font likely lacks the necessary Unicode glyphs. Switch to a comprehensive font like DejaVu Sans Mono or a Nerd Font variant that includes extended symbol sets.

Does restarting the terminal service fix locale issues?

No, changing locale settings requires a full session restart. You must log out of your graphical desktop environment and log back in to ensure all processes inherit the new LANG variables.

Can I force UTF-8 only in zsh without changing system locale?

You can export LANG=UTF-8 in your .zshrc, but this is not recommended as it may break other applications expecting the system default. It is better to configure the system locale globally via localectl.

How do I know if my font supports emojis?

Open a text editor and paste an emoji. If it renders as a box or a generic icon, your current font does not support it. Use a font manager or install a font pack that includes emoji support, such as Noto Color Emoji.

What should I do if gnome-terminal ignores my font choice?

Clear the cache by deleting the .cache/fontconfig directory and restarting the terminal. This forces gnome-terminal to rebuild its font cache and pick up newly installed or modified font configurations.