← All posts
  • #nerd fonts
  • #claude code
  • #terminal fonts
  • #install nerd fonts
  • #powerline glyphs

How to Install Nerd Fonts for Claude Code

· · 6 min read

Step-by-step guide to install Nerd Fonts for Claude Code on Mac, Windows, and Linux, plus the patched-glyph mistake that breaks every icon.

To install Nerd Fonts for Claude Code, download a patched font (like JetBrainsMono Nerd Font) from nerdfonts.com or Homebrew, install it to your OS, then set that exact font as your terminal's font family. The single most common mistake is pointing your terminal at the plain font instead of the "Nerd Font" patched variant, which is why your icons show up as empty boxes. This guide walks through the install on macOS, Windows, and Linux, and shows you how to confirm the glyphs actually render.

If you want the which font answer first, read our ranking of the best Nerd Fonts for AI terminals in 2026. This post is the how to actually install it companion.

Why Claude Code needs a Nerd Font

Claude Code, like most modern CLI tools, renders status lines, git branch markers, spinners, and file-type icons using glyphs that live in the Private Use Area of the Unicode table. Standard fonts (Menlo, Consolas, Cascadia Mono) do not have those glyphs. A Nerd Font is just a normal monospace font that has been "patched" with roughly 9,000 extra icons (Powerline, Font Awesome, Devicons, Material, Octicons, Weather). No patched font, no icons. You get tofu boxes (□) or question-mark diamonds instead.

This matters more for Claude Code than a vanilla shell because the Claude Code terminal experience leans on a rich status line and tool-call indicators. Broken glyphs make the whole thing look half-finished.

Step 1: Download a Nerd Font

You have three reliable sources. Pick one.

Method Best for Command / Action
Homebrew (macOS) Mac users who want it fast brew install --cask font-jetbrains-mono-nerd-font
Official release zip Windows, Linux, manual control Download from github.com/ryanoasis/nerd-fonts/releases
nerdfonts.com browser Previewing before you commit Click "Download" on any font card

As of 2026 the current Nerd Fonts release line is v3.x, which uses the cleaner naming scheme (for example JetBrainsMonoNerdFont-Regular.ttf). Popular picks: JetBrainsMono, FiraCode, Hack, Meslo, and CaskaydiaCove (the Nerd-patched Cascadia Code).

Step 2: Install the font on your OS
macOS
  1. If you used Homebrew, you are done. The cask installs it system-wide.
  2. Manual route: unzip the download, select all the .ttf files, double-click, and click Install Font in Font Book. Or drop them into ~/Library/Fonts.
Windows
  1. Unzip the download.
  2. Select all .ttf files, right-click, and choose Install for all users (this avoids per-app font visibility issues).
  3. Fully restart your terminal app afterward. Windows font caching is stubborn.
Linux
  1. Make the user font directory: mkdir -p ~/.local/share/fonts
  2. Copy the files in: cp *.ttf ~/.local/share/fonts/
  3. Rebuild the cache: fc-cache -fv
  4. Confirm it registered: fc-list | grep "Nerd Font"
Step 3: Point your terminal at the patched font (the gotcha)

This is where almost everyone trips. After install you will often see two names available: the plain family ("JetBrains Mono") and the patched family ("JetBrainsMono Nerd Font"). They look nearly identical in a font picker. If you select the plain one, your icons stay broken even though you installed everything correctly.

Set the Nerd Font variant explicitly. Examples by terminal:

  • iTerm2 / Terminal.app: Preferences > Profiles > Text > Font, choose "JetBrainsMono Nerd Font".
  • VS Code integrated terminal: set "terminal.integrated.fontFamily": "JetBrainsMono Nerd Font" in settings.json.
  • Windows Terminal: Settings > Profiles > Appearance > Font face > "JetBrainsMono Nerd Font".
  • Alacritty / WezTwen / Kitty: set the font family string in your config file to the exact patched name.

A small wrinkle: some terminals only expose the "Mono" sub-variant (JetBrainsMono Nerd Font Mono), which forces every glyph into a single cell width. If your icons look squished or clipped, switch to the non-Mono "Propo" or standard variant, which lets wide glyphs breathe.

The MOLTamp shortcut

If you run Claude Code inside MOLTamp, the patched font is part of the deal. MOLTamp ships with Nerd Font support baked into its skin system, so you pick a font from a dropdown and the glyphs just render. No Font Book, no fc-cache, no guessing which variant has the icons. You can pair it with the built-in skins, widgets, and visualizers without touching a config file.

Step 4: Verify the glyphs render

Run a quick visual check. In your terminal, echo a few known Nerd Font codepoints:

echo -e "   "

You should see a Powerline arrow, a GitHub mark, a git branch icon, and an open folder. If you get boxes, you are still on the plain font. Reselect the Nerd Font variant and restart the terminal completely (not just a new tab).

Ranked: fastest path to working icons
  1. macOS + Homebrew, one command, system-wide, near-zero failure rate.
  2. MOLTamp, font bundled, dropdown selection, nothing to install.
  3. Windows Terminal + official zip, reliable, just remember "install for all users."
  4. Linux + fc-cache, predictable once you know the three commands.
  5. Manual drag-and-drop into a font picker, works, but most likely to leave you on the wrong variant.
Verdict: which path is for you

Pick Homebrew if: you are on a Mac and live in the terminal. It is the cleanest, most repeatable install.

Pick the official release zip if: you are on Windows or Linux, or you want a specific font that is not in your package manager.

Pick MOLTamp if: you would rather not manage fonts at all and want Claude Code to look polished out of the box. For more on terminal options, see our AI terminal comparison.

Bottom line: the install is easy on every OS. The only thing that reliably breaks Nerd Fonts is selecting the un-patched font name. Choose the "Nerd Font" variant, restart fully, and verify with an echo test.

FAQ

Do I need to install a Nerd Font, or can Claude Code patch one for me? Claude Code does not patch fonts. You install a pre-patched Nerd Font yourself and set it as your terminal font. MOLTamp bundles patched fonts so you can skip the manual step.

Why are my icons still boxes after installing? You almost certainly selected the plain font family instead of the "Nerd Font" variant, or your terminal cached the old font. Reselect the patched name and fully restart the terminal.

What is the best Nerd Font for Claude Code? JetBrainsMono Nerd Font is the most common pick for clarity at small sizes, with FiraCode and CaskaydiaCove close behind. See our full 2026 Nerd Font ranking.

Should I use the "Mono" or regular variant? Use the regular (non-Mono) variant when your terminal allows it, so wide icons are not clipped. Switch to "Mono" only if your terminal misaligns columns.

MOLTamp is free to use, every feature works, and Nerd Font support is built in so your Claude Code icons render on the first try. A one-time $20 license only removes a small reminder popup. If you would rather not wrestle with Font Book and fc-cache, download MOLTamp and pick a font from the dropdown.