This guide explains how to configure terminal emulators to properly display Nerd Fonts glyphs. Terminal emulators require specific configuration to correctly render the programming-related icons and glyphs that Nerd Fonts add to regular fonts. This page covers terminal-specific configuration, font variant selection, and troubleshooting common display issues.
For general installation instructions across different operating systems, see Operating System Specific. For details about using patched fonts in other contexts such as text editors or IDEs, see CSS Integration.
Each patched font family ships in three variants, controlled by flags passed to font-patcher. The variant determines how glyph widths are handled, which directly affects terminal alignment.
Patcher flag → output variant mapping:
| Variant Name | Patcher Flag(s) | Glyph Width | Terminal Suitability |
|---|---|---|---|
Nerd Font (default) | (none) | Double-width icons | Good appearance; may misalign with some terminals |
Nerd Font Mono | --mono / -s | Single-width (all glyphs) | Best alignment; icons may appear compressed |
Nerd Font Propo | --variable-width-glyphs | Variable / proportional | Not recommended for terminal use |
Diagram: font-patcher flags to installed font variant
Note:
font-patcheroption--single-width-glyphs(implied by--mono) forces icon glyphs to single-cell width. The--variable-width-glyphsoption disables advance-width adjustment entirely.
Non-monospaced fonts in fonts.json (where isMonospaced is false) have their patched-font README automatically annotated with a terminal usage warning by standardize-and-complete-readmes.sh bin/scripts/standardize-and-complete-readmes.sh29-34
Sources:
Nerd Fonts provides shell variable definitions for icon codepoints, allowing scripts and prompt frameworks to reference glyphs by name instead of raw Unicode escapes.
File layout:
Source the i_all.sh aggregator or a specific i_*.sh file to expose icon variables in your shell session. The files are located under bin/scripts/lib/ in the repository.
See page 3.1 for full documentation of these files and the codepoint-to-variable mapping format.
Sources:
General steps for any terminal emulator:
JetBrainsMono Nerd Font).The font name to enter is the patched name from fonts.json plus the suffix Nerd Font, Nerd Font Mono, or Nerd Font Propo depending on the variant installed. For example, JetBrains Mono is patched to JetBrainsMono, so the full terminal font name is JetBrainsMono Nerd Font.
| Terminal | Configuration Path |
|---|---|
| iTerm2 | Preferences → Profiles → Text → Font |
| Terminal.app | Preferences → Profiles → Text → Change… |
| Terminal | Configuration |
|---|---|
| Windows Terminal | Settings → Profiles → Appearance → Font face |
| PowerShell Console | Properties → Font |
| Terminal | Configuration Path |
|---|---|
| GNOME Terminal | Preferences → Profile → Custom font |
| Konsole | Settings → Edit Current Profile → Appearance |
| Terminator | Right-click → Preferences → Profiles → Font |
| Terminal / Editor | Configuration Key |
|---|---|
| VS Code | terminal.integrated.fontFamily in settings.json |
| Alacritty | font.normal.family in alacritty.toml / alacritty.yml |
| Kitty | font_family in kitty.conf |
| WezTerm | font = wezterm.font("...") in wezterm.lua |
Sources:
Instead of using a fully patched font, you can keep your preferred font and rely on the OS font-fallback mechanism to render Nerd Font glyphs from a SymbolsOnly variant.
Diagram: OS font fallback mechanism with SymbolsOnly Nerd Font
| Detail | |
|---|---|
| Pro | One SymbolsOnly font works alongside any primary font |
| Con | Scaling and placement of fallback glyphs can be inconsistent |
On fontconfig-based systems, the 10-nerd-font-symbols.conf file improves fallback behavior by explicitly prioritizing Symbols Nerd Font for the monospace generic family.
Diagram: fontconfig file → font resolution
Steps:
Symbols Nerd Font (the SymbolsOnly release package).10-nerd-font-symbols.conf into ~/.config/fontconfig/conf.d/.fc-cache -f -v to rebuild the font cache.The 10-nerd-font-symbols.conf file is distributed as part of the Nerd Fonts release and must be manually installed. Its content declares a fontconfig <alias> that appends Symbols Nerd Font to the fallback chain for the monospace generic family.
Sources:
To verify that the terminal is correctly configured:
Expected output: Powerline arrow, house/home, branch, and GitHub icons. If you see boxes (□) or replacement characters (�), the font is not selected correctly or not installed.
After sourcing an i_*.sh file from bin/scripts/lib/:
| Issue | Possible Cause | Solution |
|---|---|---|
| Icons show as boxes (□) | Font not installed or wrong font selected | Verify installation; check font name in terminal settings |
| Icons are misaligned | Wrong width variant selected | Switch between Nerd Font and Nerd Font Mono variants |
| Specific icons missing | Glyph set not included in patched font | Use --complete patcher flag; check glyph coverage on the cheat sheet |
| Characters overlap | Terminal cell-width mismatch | Use the Nerd Font Mono variant; disable ligatures if needed |
| Fallback icons sized incorrectly | fontconfig fallback scaling | Use direct font config instead of the SymbolsOnly fallback |
| OS | Method |
|---|---|
| macOS | Font Book app — confirm the font family appears |
| Windows | Settings → Personalization → Fonts, or Control Panel → Fonts |
| Linux | fc-list | grep "Nerd" |
The installed font name is <patchedName> Nerd Font (or Nerd Font Mono / Nerd Font Propo). The patchedName field in bin/scripts/lib/fonts.json is the authoritative source. Examples:
patchedName in fonts.json | Terminal font name (default variant) |
|---|---|
JetBrainsMono | JetBrainsMono Nerd Font |
FiraCode | FiraCode Nerd Font |
Hack | Hack Nerd Font |
MesloLG | MesloLGM Nerd Font |
For detailed troubleshooting of font-rendering edge cases (Panose flags, checksum errors, monospaced detection), see page 7.
Sources:
Many popular terminal configurations and frameworks work well with Nerd Fonts:
| Framework/Tool | Configuration |
|---|---|
| Starship | Automatically uses Nerd Fonts if available |
| Oh-My-Zsh | Many themes depend on Nerd Fonts for icons |
| Powerlevel10k | Set POWERLEVEL9K_MODE=nerdfont-complete |
| Oh-My-Posh | Select a theme that uses Nerd Fonts |
Sources:
Refresh this wiki
This wiki was recently refreshed. Please wait 3 days to refresh again.