| title |
aliases |
tags |
sources |
created |
updated |
| WezTerm Font Configuration |
| wezterm-fonts |
| wezterm-font-config |
| wezterm-font-setup |
|
| wezterm |
| fonts |
| terminal |
| lua |
| dotfiles |
| nerd-fonts |
|
| raw/Fonts - Wez's Terminal Emulator.md |
|
2026-04-17 |
2026-04-17 |
Overview
WezTerm uses Lua to configure fonts. It ships with JetBrains Mono, Nerd Font Symbols, and Noto Color Emoji as bundled defaults — no patched fonts needed for powerline/Nerd Font glyphs out of the box.
Setting a Font
-- Simple family name
config.font = wezterm.font 'Fira Code'
-- With weight/style parameters
config.font = wezterm.font('JetBrains Mono', { weight = 'Bold', italic = true })
Font Fallback
WezTerm resolves glyphs by walking an ordered fallback list. First match wins.
config.font = wezterm.font_with_fallback {
'Fira Code',
'DengXian', -- CJK fallback
}
- WezTerm appends its own default fallback after your list automatically — no need to re-specify Nerd Fonts or emoji.
- If no font in the full chain has a glyph, WezTerm tries the system font fallback, then renders a "Last Resort" placeholder.
Key Config Options
| Option |
Purpose |
config.font_size |
Font size in points |
config.line_height |
Scale line height (e.g. 1.1) |
config.cell_width |
Scale cell width |
config.font_dirs |
Extra directories to search for fonts |
config.font_rules |
Per-style overrides (bold, italic, etc.) |
config.font_shaper |
Kerning/ligature engine ("Harfbuzz" default) |
config.dpi |
Override DPI — useful on X11 with HiDPI displays |
config.freetype_load_target |
Hinting + anti-aliasing mode |
config.freetype_render_target |
Anti-aliasing render target |
config.bold_brightens_ansi_colors |
Whether bold text uses bright ANSI palette |
Troubleshooting with wezterm ls-fonts
# Show which font files are active for each text style
wezterm ls-fonts
# List all discovered fonts in copy-pasteable Lua form
wezterm ls-fonts --list-system
# Show per-glyph font resolution for a specific string
wezterm ls-fonts --text 'a🞄b'
The --text flag is especially useful for debugging why a particular glyph renders from an unexpected font — it prints each character's Unicode codepoint, advance width, glyph index, and the resolved font file.
Key Takeaways
- WezTerm bundles JetBrains Mono + Nerd Symbols + Noto Emoji — no patched fonts needed
- Use
wezterm.font_with_fallback {} for multi-script or icon-heavy setups
- WezTerm always appends its default fallback to your list; you never lose Nerd Fonts coverage
wezterm ls-fonts and wezterm ls-fonts --text <string> are the go-to debug tools- Font rendering fine-tuning lives in
freetype_load_target, freetype_render_target, and font_shaper
- For ligature/kerning control see wiki/dotfiles/wezterm-font-shaping
Related
Sources
