Nerd Font icons show as boxes in Windows Terminal

If you see empty boxes where icons should be, the terminal’s font has no glyph for those characters.

What it means

Every character is a picture in a font. Nerd Fonts add thousands of extra icons (folders, git branches, logos) in a private range of characters. If the font you use does not have them, the terminal has nothing to draw and shows a box.

Why it happens

Windows Terminal’s default font is Cascadia Mono. It does not contain the Nerd Font icons, and no program can ask a terminal which fonts it has. That is why Devpit does not show Nerd Font icons unless you turn them on.

How Devpit fixes or avoids it

Devpit has three icon styles: nerd (opt-in), unicode (the default in a normal terminal) and ascii (plain). If you see boxes, you are most likely on the nerd style without the font.

Fix it in one step. Run:

devpit font install

Or open Devpit and use Settings, Icon font. Devpit then:

Installs Symbols Nerd Font Mono for your user only. No administrator rights are needed. It downloads a pinned release and checks its SHA-256 checksum first.
Adds it to Windows Terminal as a fallback in the font list, so your own font is kept.
Saves a backup of your settings.json first (a copy ending in .devpit-bak) and writes the change safely.
Asks whether the icons render before it turns them on.

Then close all Windows Terminal windows and open one again. Windows Terminal reads its font list once per process.

Other commands:

devpit font status says whether the font is installed.
devpit font remove removes the font and undoes the Windows Terminal change.
devpit --ascii forces the plain style for one run.
The installer can skip the font. Use -NoFont (see Getting started).

The manual fix

Install a Nerd Font, or the small Symbols Only font from the Nerd Fonts project. The project’s own guide says that for font fallback you can use one of the SymbolsOnly fonts, and warns that scaling and placement of fallback symbols can be hit or miss.
Open settings.json in Windows Terminal. Select Settings in the dropdown menu while holding Shift. The stable release keeps it at %LOCALAPPDATA%\Packages\Microsoft.WindowsTerminal_8wekyb3d8bbwe\LocalState\settings.json.
Put your font first and the symbols font second in font.face. The face property is inside the font object, and defaults applies to all profiles:

{
    "profiles": {
        "defaults": {
            "font": {
                "face": "Cascadia Mono, Symbols Nerd Font Mono"
            }
        }
    }
}

Save the file, close all Windows Terminal windows, and open it again.

Comma-separated names in face were added in Windows Terminal 1.21. On an older version, use a full Nerd Font as the only face instead, for example the one you installed in step 1.

Sources

Common questions

Why does Windows Terminal show boxes instead of icons?

The current font has no picture for that character, so the terminal draws a box. Windows Terminal's default font is Cascadia Mono, and it does not contain the Nerd Font icon characters.

Do I need to replace my font?

No. Windows Terminal accepts a comma-separated list of font names in font.face (since version 1.21). Put your normal font first and a Nerd Font symbols font second, and the terminal uses the second one only for the icons.

How do I undo what Devpit changed?

Run devpit font remove. It removes the font and undoes the Windows Terminal change. Before its first change Devpit also saves a backup of settings.json next to it with the ending .devpit-bak.