Skip to main content

​
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: 
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

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

​
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: 
-- Only search in font_dirs
config.font_locator = 'ConfigDirsOnly'

​
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)

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