---
title: "WezTerm Font Configuration"
aliases: [wezterm-fonts, wezterm-font-config, wezterm-font-setup]
tags: [wezterm, fonts, terminal, lua, dotfiles, nerd-fonts]
sources: [raw/Fonts - Wez's Terminal Emulator.md]
created: 2026-04-17
updated: 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

```lua
-- 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.

```lua
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`

```sh
# 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|WezTerm Font Shaping]]

## Related

- [[wiki/dotfiles/wezterm-font-shaping|WezTerm Font Shaping]] — HarfBuzz, ligatures, per-font harfbuzz_features
- [[wiki/dotfiles/wezterm-config|WezTerm Config]] — config file structure and live reload
- [[wiki/dotfiles/wezterm-colors-appearance|WezTerm Colors & Appearance]] — color schemes, tab bar, opacity
- [[wiki/dotfiles/linux-terminal-ricing|Linux Terminal Ricing]] — full ricing stack including font choices

## Sources

- [wezterm.org/config/fonts.html](https://wezterm.org/config/fonts.html)
