Termhint Get Termhint

Docs

Nerd Font icons showing as boxes in your Mac terminal? Here is the fix

Updated 19 November 2026

In short: your shell only sends the icon's code point; the terminal picks the font that draws it. If that font has no Nerd Font icons, you get a box. No shell-side trick shows an icon in every terminal, so the fix is a font setting per terminal. termhint icons setup makes that change in every terminal it can, and Termhint's prompt shows a standard symbol wherever icons still can't show.

Why Nerd Font icons show as boxes

Measured on macOS 26 with FiraCode Nerd Font installed, 13 November 2026.

Fix it with one command

termhint icons            # each terminal: icons or standard symbols, and why
termhint icons setup      # turn icons on in every terminal Termhint can (installs fonts as needed)
termhint icons test       # run inside the terminal in question

In the app, the same is Set Up Icons in Settings → Terminal → Apps, with an Icons switch per terminal. termhint icons on <terminal> and termhint icons off <terminal> work on one terminal. Turning icons off restores the setting Termhint changed: the previous value, or no setting. If you changed the value yourself since, it is left alone.

The font Termhint installs

Any family of the newest Nerd Fonts release. The default is Symbols Only: icons alone, 2.3 MB, so each terminal keeps its own text font. Nerd Fonts you already installed (for example FiraCode Nerd Font Mono or MesloLGS NF) count too.

The download is checked against the release's SHA-256.txt before the files go to ~/Library/Fonts. A file of that name that Termhint did not install is left alone, and termhint icons remove deletes only files Termhint installed.

Font settings per terminal

TerminalIcons show whenWhat turning icons on changes
TerminalIts default profile's font is a Nerd Font, or a Nerd Font is installed and the prompt's icons are all Material ones (U+F0000 and up)Installs the icons font; the prompt's older icons switch to their Material twins. Terminal's font is never changed for icons. An icon without a twin (Powerline edges) leaves it on standard symbols.
Ghostty, kitty, WezTerm, Rio, Kaku, cmuxAlways (built in)Nothing
Cursor, VS Code, VS Code Insiders, VSCodium, Windsurf, Kiro, Trae, PositronThe terminal font list names an installed Nerd Font (terminal.integrated.fontFamily, else editor.fontFamily, else the default)Adds the Nerd Font before the generic family in terminal.integrated.fontFamily, keeping your comments
iTerm2The default profile's normal font, or its non-ASCII font when used, is a Nerd FontSets Non-ASCII Font to the icons font at the normal font's size and turns Use Non-ASCII Font on. Only while iTerm2 is not running.
Alacrittyfont.normal.family is a Nerd Font (default Menlo)Sets that key to the Nerd Font build of your font (Menlo becomes Meslo), keeping comments
HyperfontFamily in .hyper.js names a Nerd FontAdds the icons font to that list
Tabbyterminal.font or terminal.fallbackFont in config.yaml is a Nerd FontSets fallbackFont to the icons font. Only while Tabby is not running.
WarpNot supported: it draws its own prompt and command line.

To fix an editor terminal by hand, one setting is enough:

"terminal.integrated.fontFamily": "Menlo, 'Symbols Nerd Font Mono'"

Prompt icons only where they show

A theme set with --glyphs auto (the default for a new theme) is built twice: once with icons, once with standard symbols. Each shell loads the icon version only in a terminal that is ready, so no terminal shows a box. termhint theme set <name> --glyphs unicode or ascii never uses Nerd Font icons. A prompt made in Settings keeps a standard stand-in for each icon, such as ❯ or a language's emoji. More on themes: prompt themes.

Tab titles are drawn with the system font. It finds Material icons (U+F0000 and up) in an installed Nerd Font, but not the older ones.

Use a Nerd Font for the terminal's text

Installing a Nerd Font with letters (FiraCode, Meslo and so on) changes nothing until a terminal's own font setting names it. Choose one terminal font in Settings → Terminal → Font, or with termhint icons font <family>, among your installed fixed-pitch Nerd Fonts. Then switch it on per terminal with termhint icons font on|off <terminal>. The terminal keeps its font size.

TerminalSetting changedQuit the terminal first
TerminalThe default profile's FontYes
iTerm2The default profile's Normal FontYes
Cursor, VS Code, VS Code Insiders, VSCodium, Windsurf, Kiro, Trae, PositronThe family first in terminal.integrated.fontFamily, the rest of the list after itNo
Alacrittyfont.normal.familyNo
HyperThe family first in fontFamilyNo
Tabbyterminal.fontYes
GhosttyA termhint font block at the end of its config with font-familyNo (Reload Configuration for open windows)
kittyA termhint font block in kitty.conf with font_family; a running kitty reloads itNo
WezTermA termhint font block before the config's last return line; a config without that line is set by handNo
Rio, Kaku, cmuxNot set: Termhint does not write their configs—

The font switch and the icons switch undo separately, by the same rules. Choosing no font turns every font switch off. termhint uninstall --all puts back every icon and font setting Termhint changed (docs).

Limits

Still seeing boxes? See troubleshooting.

Download for Mac All docs