wezterm ls-fonts

Display and analyze font information in WezTerm

The ls-fonts command provides detailed information about fonts available to WezTerm and explains which fonts are used to render specific text.

Synopsis

wezterm ls-fonts [OPTIONS]

Description

This command is a powerful diagnostic tool for understanding font selection and rendering in WezTerm. It can list all available system fonts, explain which fonts are used for specific text, and show how glyphs are rasterized.

Options

--list-system · flag

List all fonts available to the system.

This will enumerate all fonts that WezTerm can potentially use, showing their family names, styles, and locations.

Example:

wezterm ls-fonts --list-system

--text · string

Explain which fonts are used to render the supplied text string.

WezTerm will analyze the text and show which font(s) are selected for each character or glyph, including fallback fonts for characters not available in the primary font.

Example:

wezterm ls-fonts --text "Hello World 你好"

Conflicts with: --list-system, --codepoints

--codepoints · string

Explain which fonts are used to render the specified unicode code point sequence.

Code points should be specified as comma-separated hex values.

Example:

wezterm ls-fonts --codepoints 0x48,0x65,0x6c,0x6c,0x6f

Conflicts with: --list-system

--rasterize-ascii · flag

Show rasterized glyphs for the text in --text or --codepoints using ASCII blocks.

This renders a visual representation of how each glyph looks when rasterized, which is helpful for debugging font rendering issues.

Requires: --text option

Example:

wezterm ls-fonts --text "ABC" --rasterize-ascii

Examples

List all available system fonts

wezterm ls-fonts --list-system

Output will show fonts like:

...
JetBrains Mono (TrueType)
  /usr/share/fonts/truetype/jetbrains-mono/JetBrainsMono-Regular.ttf
Fira Code (TrueType)
  /usr/share/fonts/truetype/fira-code/FiraCode-Regular.ttf
...

Check which fonts are used for English text

wezterm ls-fonts --text "Hello World!"

Check which fonts are used for mixed scripts

wezterm ls-fonts --text "Hello 世界 🌍"

This will show:

• The primary font for ASCII characters
• Fallback fonts for Chinese characters
• Fallback fonts for emoji

Inspect specific Unicode codepoints

wezterm ls-fonts --codepoints 0x1f600,0x1f601,0x1f602

This checks font coverage for emoji (😀😁😂).

Visualize glyph rendering

wezterm ls-fonts --text "ABC" --rasterize-ascii

This will show ASCII art representation of how the glyphs are rendered.

Debug missing glyphs

wezterm ls-fonts --text "→λ∀∃"

Use this to see which fonts provide mathematical and symbolic characters.

Common Use Cases

Font Configuration Debugging

If your terminal doesn’t look right, use ls-fonts to verify:

# Check if your configured font is actually being used
wezterm ls-fonts --text "test"

Emoji Support

Verify emoji rendering:

wezterm ls-fonts --text "🚀 📝 ✨"

Programming Ligatures

Check ligature support in your font:

wezterm ls-fonts --text "!= => -> =="

CJK Character Support

Verify Chinese, Japanese, or Korean character rendering:

wezterm ls-fonts --text "你好世界"
wezterm ls-fonts --text "こんにちは"
wezterm ls-fonts --text "안녕하세요"

Powerline Symbols

Check if powerline symbols are available:

wezterm ls-fonts --text "   "

Understanding Output

When using --text, the output typically shows:

1. Primary Font: The main font configured in your wezterm.lua
2. Fallback Fonts: Additional fonts used when the primary font doesn’t have a glyph
3. Coverage: Which characters are covered by which font
4. Font Attributes: Weight, style, stretch, etc.

Example output:

0 "H" U+0048 LATIN CAPITAL LETTER H
  glyph=0x48 font_idx=0 "JetBrains Mono" /usr/share/fonts/...

1 "世" U+4E16 CJK UNIFIED IDEOGRAPH-4E16
  glyph=0x1234 font_idx=3 "Noto Sans CJK SC" /usr/share/fonts/...

Troubleshooting Font Issues

1. Characters show as boxes (□): The font doesn’t have that glyph. Use --text to find which fallback font should provide it.

2. Wrong font being used: Check your wezterm.lua configuration and verify with --text.

3. Emoji not displaying: Use --text with emoji to see if an emoji font is available.

4. Ligatures not working: Not all fonts support ligatures. Use --text to verify the font being used.

Related Configuration

In your wezterm.lua, you configure fonts like:

return {
  font = wezterm.font 'JetBrains Mono',
  font_size = 12.0,
  
  -- Specify fallback fonts
  font = wezterm.font_with_fallback {
    'JetBrains Mono',
    'Noto Sans CJK SC',
    'Symbols Nerd Font',
  },
}

Related

• WezTerm Font Configuration Documentation
• wezterm show-keys - Display key bindings