Nerd Fonts

Nerd Fonts

Nerd Fonts patches developer fonts with 10,995 icons from Devicons, Font Awesome, Font Awesome Extension, Material Design Icons, Weather, Octicons, Codicons, Font Logos, Pomicons, Powerline and Powerline Extra, IEC Power Symbols, and Seti-UI + Custom. It ships 72 patched font families, a Symbols Only font, and a patcher for any other font. Upstream: ryanoasis/nerd-fonts (MIT for the patcher and the aggregation; every font keeps its own license). This skill snapshots release v3.5.1 (2026-08-21) as data/glyphs.tsv.

How to use

• /nerd-fonts: apply the icon policy below to every icon and font decision in this conversation.
• /nerd-fonts <file>: review a script, TUI source, prompt config, editor config, terminal config, HTML or CSS file against the policy. For each finding output:
  • violation (quote the exact line)
  • why it matters (one sentence)
  • fix (the exact glyph with its nf-<set>-<name> and U+XXXX, or the exact config line)

Review checklist for /nerd-fonts <file> (perl ships with macOS and Linux):

• Emoji or dingbats used as icons: perl -CSD -ne 'print "$.: $_" if /[\x{2600}-\x{27BF}\x{1F000}-\x{1FAFF}]/' FILE. Fix: the glyph from data/glyphs.tsv.
• Legacy Material classes: grep -n 'nf-mdi-' FILE. Fix: the nf-md- name found by bare-name search.
• Glyphs without their name and codepoint: perl -CSD -ne 'print "$.: $_" if /[\x{E000}-\x{F8FF}\x{F0000}-\x{FFFFD}]/ && !/nf-[a-z]+-[a-z0-9_]+/' FILE. Fix: add nf-<set>-<name> U+XXXX next to the glyph and confirm the codepoint.
• Unpatched family in a font setting: grep -n -i -E 'cascadia code|source code pro|ibm plex mono|hasklig|hermit|anonymous pro|monaspace|terminus|liberation mono|share tech mono|intel one mono|atkinson|d2coding|ia writer|bitstream vera' FILE. Fix: the patched family from references/fonts.md.
• Web page with glyphs and no font: after a glyph hit in HTML or CSS, grep -L -E 'webfont\.css|@font-face' FILE prints the file when it loads no icon font. Fix: load webfont.css or self-host Symbols Only.
• Text markers standing in for icons (E:, W:, [x], -> in status lines): no regex catches them reliably; read the file. Fix: the matching glyph, one set per surface.

Icon policy

Choosing icons

• MUST use a Nerd Fonts glyph for every icon in CLI output, TUIs, prompts, statuslines, editor and terminal configs, docs, and web UI
• NEVER use emoji, ASCII art, or Unicode dingbats as an icon when a Nerd Fonts glyph exists
• MUST take the name from the cheat sheet, data/glyphs.tsv, or upstream glyphnames.json
• NEVER state a codepoint or class name from memory
• MUST write the glyph next to its name and codepoint in a comment or adjacent note, for example icon = "" # nf-oct-mark_github U+F408
• SHOULD keep one icon set per surface; NEVER mix two sets for the same concept in one UI
• SHOULD pick the set by purpose: nf-md- for breadth, nf-cod- for editor UI, nf-oct- for git and GitHub, nf-dev- and nf-seti- for languages and file types, nf-pl- and nf-ple- for prompt separators, nf-linux- for OS logos, nf-weather- for weather

Font requirement

• MUST say that a Nerd Font must be active on the rendering surface and link https://www.nerdfonts.com/font-downloads
• MUST use the patched family name exactly as installed; Reserved Font Name renames apply: Cascadia Code is CaskaydiaCove Nerd Font, Source Code Pro is SauceCodePro Nerd Font, IBM Plex Mono is BlexMono Nerd Font (full list in references/fonts.md)
• SHOULD offer Symbols Nerd Font (Symbols Only) when the user keeps a different text font

Terminal and CLI

• MUST use the Mono variant, or account for 1.5-cell icons, wherever columns must align
• SHOULD add a plain-text fallback switch (--no-icons or NO_ICONS=1) to CLIs that may run without a Nerd Font
• MUST print the chosen glyphs with printf and check alignment before claiming they render
• SHOULD use a patched font, not the Symbols Only fallback, where icons must sit exactly on the text line: upstream documents fallback placement as hit or miss; kitty corrects it with modify_font baseline, WezTerm with a fallback scale

Web

• MUST load the Nerd Fonts webfont (<link rel="stylesheet" href="https://www.nerdfonts.com/assets/css/webfont.css"> then <i class="nf nf-fa-heart"></i>) or self-host SymbolsNerdFont-Regular.ttf from NerdFontsSymbolsOnly.zip with an @font-face and a .nf class
• SHOULD self-host in production instead of hot-linking nerdfonts.com
• MUST add aria-hidden="true" on decorative icon elements and an accessible name on icon-only controls
• NEVER ship a Private Use Area character on a page without a font that covers it
• MUST keep line-height: 1 on icon elements (the upstream .nf class sets it) and align them to the text with vertical-align (start at -0.125em and tune per text font) or display: inline-flex; align-items: center in components
• MUST check a line that mixes text and icons in the browser before shipping; an icon font sits on a different baseline than the text font

Verification

• MUST verify every glyph name in data/glyphs.tsv or on the cheat sheet before use
• NEVER claim an icon renders without evidence: printf output, a screenshot, or the user confirming

Two pages to use

The cheat sheet reads upstream glyphnames.json; data/glyphs.tsv is the same data bundled here. Each cheat sheet result has copy buttons for Icon, Class, and Code.

Which set for what

Counts and codepoint ranges: references/glyph-sets.md. The same concept in every set, to keep one set per surface: references/icon-concepts.md.

Common icons

Verified against data/glyphs.tsv (v3.5.1). 766 more in references/common-icons.md.

Look up an icon

Cheat sheet: search the bare name. For a removed nf-mdi-altimeter type altimeter, then copy Icon, Class, or Code.

Bundled snapshot (paths relative to this skill directory):

grep -i 'folder' data/glyphs.tsv
awk -F'\t' '$1=="md-folder"' data/glyphs.tsv

Latest upstream data:

curl -fsSL https://raw.githubusercontent.com/ryanoasis/nerd-fonts/master/glyphnames.json -o /tmp/glyphnames.json
jq -r --arg q folder 'to_entries[]|select(.key!="METADATA" and (.key|test($q)))|"\(.key) \(.value.code) \(.value.char)"' /tmp/glyphnames.json

Class names follow nf-<set>-<name>. Material Design Icons moved in v3 from nf-mdi- (U+F001 to U+F847) to nf-md- (U+F0001 to U+F1AF0); some icons were dropped, so search by bare name for the replacement.

Writing a glyph:

More languages: references/glyph-sets.md.

Pick the variant

The variant changes only the added icons, never the base letters.

Install

macOS (casks are font-<kebab-patched-name>-nerd-font; brew search --cask nerd-font lists them all):

brew install --cask font-jetbrains-mono-nerd-font
brew install --cask font-symbols-only-nerd-font

Windows (Scoop packages are <ReleaseAsset>-NF; Chocolatey packages are community-maintained, check choco search nerd-fonts):

scoop bucket add nerd-fonts
scoop install JetBrainsMono-NF
choco install nerd-fonts-hack

Linux (Arch packages are ttf-<name>-nerd, pacman -Ss nerd; any distro via the release asset):

sudo pacman -S ttf-jetbrains-mono-nerd
mkdir -p ~/.local/share/fonts && cd ~/.local/share/fonts
curl -fLO https://github.com/ryanoasis/nerd-fonts/releases/latest/download/JetBrainsMono.tar.xz
tar -xf JetBrainsMono.tar.xz && fc-cache -fv

Any OS, pinned release: https://github.com/ryanoasis/nerd-fonts/releases/download/v3.5.1/JetBrainsMono.zip. Asset names are the "Release asset" column in references/fonts.md; SHA-256.txt ships with every release.

Keep your current text font: install NerdFontsSymbolsOnly (families Symbols Nerd Font and Symbols Nerd Font Mono; the zip holds SymbolsNerdFont-Regular.ttf, SymbolsNerdFontMono-Regular.ttf, 10-nerd-font-symbols.conf, LICENSE, README.md) and let the app fall back to it: fontconfig users copy 10-nerd-font-symbols.conf to ~/.config/fontconfig/conf.d/, kitty uses symbol_map, WezTerm font_with_fallback, iTerm2 "Use a different font for non-ASCII text", Ghostty and WezTerm bundle the symbols already. Snippets: references/terminals.md.

install.sh and install.ps1 from a shallow clone install all or one font, but only fonts still tracked in the repository.

Verify

printf '  󰉋\n'
fc-list : family | grep -i 'nerd font' | sort -u
fc-list ':charset=f408' family

The first line prints nf-custom-vim U+E62B, nf-oct-mark_github U+F408, nf-md-folder U+F024B; boxes or blanks mean the active font lacks the glyph. fc-list needs fontconfig, which macOS does not ship (brew install fontconfig); on macOS use kitty +list-fonts | grep -i nerd inside kitty, system_profiler SPFontsDataType | grep -i 'nerd font' anywhere, or the printf line alone. Checklist: the terminal profile still points at another font; Regular vs Mono overlap; restart the app and run fc-cache -fv; tmux and ssh sessions use the local terminal font, nothing to install remotely; terminals without double-width support need the Mono variant.

Configure terminals and editors

More apps, prompt tools (starship, powerlevel10k, oh-my-posh) and web snippets: references/terminals.md.

Patch your own font

Download FontPatcher.zip from the latest release; needs FontForge and Python 3.

fontforge -script font-patcher MyFont.ttf --complete --outputdir out/
docker run --rm -v "$PWD/in:/in:Z" -v "$PWD/out:/out:Z" nerdfonts/patcher --complete

--mono makes single-width icons, --variable-width-glyphs makes the Propo variant. All options: references/font-patcher.md.

Common mistakes

References

• data/glyphs.tsv: all 10,995 named glyphs, columns name, code, char
• references/common-icons.md: 766 everyday icons by purpose
• references/icon-concepts.md: the same 22 concepts across the md, fa, oct, cod and seti sets
• references/glyph-sets.md: sets, prefixes, codepoint ranges, lookup recipes
• references/fonts.md: 72 families, release assets, package names, RFN renames
• references/terminals.md: terminal, editor, prompt, and web configuration
• references/font-patcher.md: patcher options and examples
• Upstream: releases, README, wiki Glyph Sets and Code Points, wiki FAQ and Troubleshooting, webfont.css