Font Configuration

Configure fonts, fallbacks, weights, styles, and advanced font rendering options in WezTerm

Default Fonts

WezTerm bundles high-quality fonts by default:

• JetBrains Mono - Primary monospace font
• Nerd Font Symbols - Icon and symbol support
• Noto Color Emoji - Full emoji support

These fonts work out of the box with no configuration required.

Basic Font Configuration

Setting Font Family

Use wezterm.font() to specify a font:

Simple Font

local wezterm = require 'wezterm'
local config = wezterm.config_builder()

config.font = wezterm.font 'Fira Code'

return config

Font Size

Set the font size in points:

config.font_size = 12.0

-- You can use fractional sizes
config.font_size = 13.3

The default font size is 12.0 points. Fractional sizes like 13.3 allow fine-tuning.

Font Fallback

WezTerm automatically falls back to other fonts when glyphs are missing:

local wezterm = require 'wezterm'
local config = wezterm.config_builder()

config.font = wezterm.font_with_fallback {
  'Fira Code',       -- Primary font
  'DengXian',        -- For Chinese characters
  'Apple Color Emoji', -- Emoji fallback
}

return config

How Fallback Works

1. Primary Font

   WezTerm checks the first font in the list.

2. Fallback Chain

   If the glyph isn’t found, it proceeds to the next font.

3. Built-in Fallbacks

   WezTerm’s default fallbacks (Nerd Font Symbols, Noto Color Emoji) are automatically appended.

4. System Fallbacks

   If still not found, system-wide fallback fonts are checked.

5. Last Resort

   A placeholder glyph is rendered if no font contains the character.

You don’t need to include Nerd Font Symbols in your fallback list - it’s automatically included!

Font Weight and Style

Available Weights

config.font = wezterm.font('Roboto Mono', {
  weight = 'Thin',        -- 100
  -- weight = 'ExtraLight', -- 200
  -- weight = 'Light',      -- 300
  -- weight = 'DemiLight',  -- 350
  -- weight = 'Book',       -- 380
  -- weight = 'Regular',    -- 400 (default)
  -- weight = 'Medium',     -- 500
  -- weight = 'DemiBold',   -- 600
  -- weight = 'Bold',       -- 700
  -- weight = 'ExtraBold',  -- 800
  -- weight = 'Black',      -- 900
  -- weight = 'ExtraBlack', -- 950
})

-- Or use numeric values
config.font = wezterm.font('Roboto Mono', { weight = 450 })

Font Styles

Italic

config.font = wezterm.font('JetBrains Mono', {
  italic = true,
})

Oblique

config.font = wezterm.font('Monaco', {
  style = 'Oblique',
})

Normal

config.font = wezterm.font('Courier', {
  style = 'Normal', -- Default
})

Font Stretch

config.font = wezterm.font('Source Code Pro', {
  stretch = 'Condensed',
  -- stretch = 'UltraCondensed'
  -- stretch = 'ExtraCondensed'
  -- stretch = 'SemiCondensed'
  -- stretch = 'Normal' (default)
  -- stretch = 'SemiExpanded'
  -- stretch = 'Expanded'
  -- stretch = 'ExtraExpanded'
  -- stretch = 'UltraExpanded'
})

Advanced Font Rules

Customize fonts for different text styles:

local wezterm = require 'wezterm'
local config = wezterm.config_builder()

config.font = wezterm.font 'JetBrains Mono'

config.font_rules = {
  -- Select a fancy italic font for italic text
  {
    intensity = 'Normal',
    italic = true,
    font = wezterm.font('Operator Mono SSm Lig', {
      weight = 'Book',
      italic = true,
    }),
  },
  
  -- Bold text uses a heavier weight
  {
    intensity = 'Bold',
    italic = false,
    font = wezterm.font('JetBrains Mono', {
      weight = 'Bold',
    }),
  },
  
  -- Bold+Italic
  {
    intensity = 'Bold',
    italic = true,
    font = wezterm.font('Operator Mono SSm Lig', {
      weight = 'Bold',
      italic = true,
    }),
  },
  
  -- Half-intensity (dim) text
  {
    intensity = 'Half',
    italic = false,
    font = wezterm.font('JetBrains Mono', {
      weight = 'Light',
    }),
  },
}

return config

Font Metrics and Spacing

Line Height

Adjust spacing between lines:

-- Default is 1.0
config.line_height = 1.2

-- Tighter spacing
config.line_height = 0.9

Cell Width

Adjust character width:

-- Default is 1.0
config.cell_width = 1.1

-- Narrower spacing
config.cell_width = 0.9

Underline Customization

config.underline_thickness = '2px'
config.underline_position = '-4px' -- Negative moves up

Cursor Thickness

config.cursor_thickness = '2px'

These options accept pixel values (e.g., '2px') or percentage values (e.g., '200%').

Font Loading and Discovery

Custom Font Directories

Add additional directories to search for fonts:

config.font_dirs = {
  '/Users/username/fonts',
  '/usr/share/local/fonts',
}

Font Locator

Choose how WezTerm finds fonts:

ConfigDirsOnly

-- Only search in font_dirs
config.font_locator = 'ConfigDirsOnly'

FontConfig (Linux)

-- Use FontConfig system
config.font_locator = 'FontConfig'

CoreText (macOS)

-- Use macOS CoreText
config.font_locator = 'CoreText'

Font Rendering

Font Shaper

Control text shaping and ligatures:

-- Harfbuzz (default) - full ligature support
config.font_shaper = 'Harfbuzz'

-- AllSorts - alternative shaper
config.font_shaper = 'AllSorts'

FreeType Options (Linux/Windows)

Load Flags

config.freetype_load_flags = 'NO_HINTING'
-- Options:
-- 'DEFAULT'
-- 'NO_HINTING'
-- 'NO_AUTOHINT'
-- 'FORCE_AUTOHINT'
-- 'MONOCHROME'
-- 'NO_AUTOHINT|FORCE_AUTOHINT'

DPI Override

-- Force specific DPI (useful for high-density displays)
config.dpi = 144.0

Special Font Features

Bold and Bright Colors

-- Make bold text use bright ANSI colors
config.bold_brightens_ansi_colors = true

Square Glyph Overflow

-- Allow box-drawing characters to extend slightly
config.allow_square_glyphs_to_overflow_width = 'WhenFollowedBySpace'
-- Options:
-- 'Never'
-- 'Always'
-- 'WhenFollowedBySpace'

Cap Height Scaling

-- Use cap height instead of ascent for fallback fonts
config.use_cap_height_to_scale_fallback_fonts = true

Troubleshooting Fonts

List Available Fonts

See what fonts WezTerm can find:

# Show current font configuration
wezterm ls-fonts

# List all available fonts
wezterm ls-fonts --list-system

Example output:

Primary font:
wezterm.font_with_fallback({
  -- /home/user/.fonts/OperatorMono.otf, FontDirs
  {family="Operator Mono", weight="Regular"},
  
  -- /usr/share/fonts/jetbrains-mono/JetBrainsMono-Regular.ttf
  "JetBrains Mono",
  
  -- /usr/share/fonts/noto-emoji/NotoColorEmoji.ttf
  "Noto Color Emoji",
})

Check Text Shaping

See how specific text is rendered:

wezterm ls-fonts --text "a→b"

Output shows which font provides each glyph:

a  \u{61}     x_adv=8  glyph=29   wezterm.font("Fira Code", ...)
b  \u{62}     x_adv=8  glyph=30   wezterm.font("Fira Code", ...)
→  \u{2192}   x_adv=10 glyph=1245 wezterm.font("Symbols Nerd Font", ...)

Common Issues

Font not found: Ensure the font is installed system-wide or added to font_dirs.

Ligatures not working: Check that font_shaper = 'Harfbuzz' is set and your font supports ligatures.

Blurry fonts on Linux: Try adjusting freetype_load_target and freetype_render_target.

Complete Example

Here’s a comprehensive font configuration:

local wezterm = require 'wezterm'
local config = wezterm.config_builder()

-- Primary font with fallbacks
config.font = wezterm.font_with_fallback {
  'Fira Code',
  'Noto Sans CJK JP', -- Japanese support
  'Symbola',          -- Unicode symbols
}

config.font_size = 12.0
config.line_height = 1.1
config.cell_width = 1.0

-- Custom font rules for italic
config.font_rules = {
  {
    intensity = 'Normal',
    italic = true,
    font = wezterm.font('Operator Mono Lig', {
      weight = 'Book',
      style = 'Italic',
    }),
  },
}

-- Font rendering
config.font_shaper = 'Harfbuzz'
config.freetype_load_target = 'Light'
config.freetype_render_target = 'HorizontalLcd'

-- Additional options
config.bold_brightens_ansi_colors = true
config.allow_square_glyphs_to_overflow_width = 'WhenFollowedBySpace'

return config