Font Configuration

Configure fonts, font rendering, and typography in WezTerm

Font Configuration

WezTerm provides extensive font configuration options, allowing you to customize the font family, size, weight, and rendering characteristics.

Basic Font Configuration

Setting the Font

Use wezterm.font() to specify your primary font:

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

config.font = wezterm.font('JetBrains Mono')
config.font_size = 13.0

return config

font · TextStyle · default: "wezterm.font('JetBrains Mono')"

The primary font configuration. Accepts a TextStyle object created with wezterm.font() or wezterm.font_with_fallback().

font_size · number · default: "12.0"

The font size measured in points. Default is platform-dependent.

Font with Attributes

You can specify font weight, style, and stretch:

config.font = wezterm.font('Fira Code', {
  weight = 'Medium',
  style = 'Normal',
  stretch = 'Normal',
})

weight · string|number · default: "'Regular'"

Font weight. Can be a string like ‘Bold’, ‘Light’, or a numeric value (100-1000).

Valid string values:

• Thin (100)
• ExtraLight (200)
• Light (300)
• DemiLight (350)
• Book (380)
• Regular (400)
• Medium (500)
• DemiBold (600)
• Bold (700)
• ExtraBold (800)
• Black (900)
• ExtraBlack (1000)

style · string · default: "'Normal'"

Font style. Valid values: Normal, Italic, Oblique

stretch · string · default: "'Normal'"

Font stretch. Valid values: UltraCondensed, ExtraCondensed, Condensed, SemiCondensed, Normal, SemiExpanded, Expanded, ExtraExpanded, UltraExpanded

Font Examples

Bold Font

config.font = wezterm.font('Cascadia Code', { weight = 'Bold' })

Font Fallbacks

Use wezterm.font_with_fallback() to specify a list of fonts. WezTerm will use the first font that contains the required glyphs:

config.font = wezterm.font_with_fallback({
  'JetBrains Mono',
  'Noto Color Emoji',
  'Symbols Nerd Font Mono',
})

WezTerm automatically adds ‘Noto Color Emoji’ and ‘Symbols Nerd Font Mono’ as fallbacks if they’re not explicitly included.

Fallback with Attributes

config.font = wezterm.font_with_fallback({
  { family = 'Fira Code', weight = 'Medium' },
  { family = 'Noto Color Emoji', scale = 0.9 },
  'Symbols Nerd Font Mono',
})

Font Sizing and Spacing

Line Height

line_height · number · default: "1.0"

Multiplier for line height. A value of 1.0 uses the font’s recommended line spacing.

config.line_height = 1.2 -- 20% taller lines

Cell Width

cell_width · number · default: "1.0"

Multiplier for cell width. A value of 1.0 uses the font’s natural width.

config.cell_width = 0.9 -- 10% narrower cells

Modifying cell_width can affect character alignment and may cause rendering issues with some TUI applications.

Font Rules

Font rules allow you to use different fonts based on text attributes (bold, italic, etc.):

config.font_rules = {
  -- Select a bold font when bold text is requested
  {
    intensity = 'Bold',
    italic = false,
    font = wezterm.font('Fira Code', { weight = 'Bold' }),
  },
  
  -- Select an italic font when italic text is requested
  {
    italic = true,
    intensity = 'Normal',
    font = wezterm.font('Victor Mono', { style = 'Italic' }),
  },
  
  -- Bold and italic
  {
    intensity = 'Bold',
    italic = true,
    font = wezterm.font('Victor Mono', {
      weight = 'Bold',
      style = 'Italic',
    }),
  },
}

font_rules · array · default: "[]"

An array of font rule objects that match cell attributes and specify alternative fonts.

Font rules support these matchers:

• intensity: 'Bold', 'Normal', or 'Half'
• italic: true or false
• underline: 'None', 'Single', or 'Double'
• strikethrough: true or false
• blink: 'None', 'Slow', or 'Rapid'

Font Directories

Specify additional directories to search for fonts:

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

font_dirs · array · default: "[]"

Additional directories to search for font files. Relative paths are resolved relative to the config file location.

Font Locator

font_locator · string · default: "platform-dependent"

Selects the font discovery method:

• FontConfig: Use fontconfig (Linux/Unix)
• CoreText: Use Core Text (macOS)
• Gdi: Use GDI (Windows)
• ConfigDirsOnly: Only use font_dirs

config.font_locator = 'ConfigDirsOnly'

Font Rendering

Font Rasterizer

font_rasterizer · string · default: "'FreeType'"

Selects the font rasterizer. Valid values: FreeType, Harfbuzz

config.font_rasterizer = 'FreeType'

Font Shaper

font_shaper · string · default: "'Harfbuzz'"

Selects the font shaper for text layout. Valid values: Harfbuzz, Allsorts

config.font_shaper = 'Harfbuzz'

FreeType Configuration

Anti-aliasing

font_antialias · string · default: "'Subpixel'"

Controls anti-aliasing. Valid values: None, Greyscale, Subpixel

config.font_antialias = 'Subpixel'

Hinting

font_hinting · string · default: "'Full'"

Controls font hinting. Valid values: None, Vertical, VerticalSubpixel, Full

config.font_hinting = 'Full'

FreeType Load Target

freetype_load_target · string · default: "'Normal'"

FreeType rendering target. Valid values: Normal, Light, Mono, HorizontalLcd, VerticalLcd

config.freetype_load_target = 'Normal'

FreeType Load Flags

freetype_load_flags · string · default: "nil"

FreeType load flags. Can be combined with |. Valid values:

• DEFAULT
• NO_HINTING
• NO_BITMAP
• FORCE_AUTOHINT
• MONOCHROME
• NO_AUTOHINT
• NO_SVG
• SVG_ONLY

config.freetype_load_flags = 'NO_HINTING'

FreeType Interpreter Version

freetype_interpreter_version · number · default: "nil"

Specifies the FreeType interpreter version (35, 38, or 40). Affects subpixel hinting.

config.freetype_interpreter_version = 40

Display Configuration

Pixel Geometry

display_pixel_geometry · string · default: "'RGB'"

Specifies the subpixel order. Valid values: RGB, BGR

config.display_pixel_geometry = 'RGB'

DPI

dpi · number · default: "nil"

Override the DPI for font rendering. If not set, WezTerm uses the system DPI.

config.dpi = 144.0

Per-Screen DPI

config.dpi_by_screen = {
  ['Built-in Retina Display'] = 144.0,
  ['External Display'] = 96.0,
}

dpi_by_screen · table · default: "{}"

A table mapping screen names to DPI values.

Advanced Font Features

HarfBuzz Features

You can enable or disable OpenType font features:

config.harfbuzz_features = {
  'calt=1',  -- Enable contextual alternates
  'clig=1',  -- Enable contextual ligatures
  'liga=1',  -- Enable standard ligatures
  'ss01',    -- Enable stylistic set 1
}

harfbuzz_features · array · default: "nil"

Array of OpenType feature strings to apply globally.

You can also specify features per-font:

config.font = wezterm.font('Fira Code', {
  harfbuzz_features = { 'calt=0', 'clig=0', 'liga=0' }, -- Disable ligatures
})

Font Scaling

Scale individual fallback fonts:

config.font = wezterm.font_with_fallback({
  'JetBrains Mono',
  { family = 'Noto Color Emoji', scale = 0.8 }, -- Make emoji smaller
})

Use Cap Height Scaling

use_cap_height_to_scale_fallback_fonts · boolean · default: "false"

When true, fallback fonts are scaled to match the cap height of the primary font.

config.use_cap_height_to_scale_fallback_fonts = true

Cursor Thickness

cursor_thickness · string · default: "'1px'"

The thickness of the cursor. Can be specified in pixels or as a fraction of the cell width.

config.cursor_thickness = '2px'
-- or
config.cursor_thickness = '0.1cell'

Underline Configuration

underline_thickness · string · default: "nil"

The thickness of underlines. Can be specified in pixels or as a fraction of the cell height.

underline_position · string · default: "nil"

The position of underlines from the baseline.

config.underline_thickness = '2px'
config.underline_position = '-4px'

Strikethrough Configuration

strikethrough_position · string · default: "nil"

The vertical position of strikethrough lines.

config.strikethrough_position = '0.5cell'

Character Width Behavior

Allow Square Glyph Overflow

allow_square_glyphs_to_overflow_width · string · default: "'WhenFollowedBySpace'"

Controls whether square glyphs (box drawing characters) can overflow their cell width.

Valid values:

• Never: Never allow overflow
• Always: Always allow overflow
• WhenFollowedBySpace: Only overflow when followed by a space

config.allow_square_glyphs_to_overflow_width = 'WhenFollowedBySpace'

Custom Block Glyphs

custom_block_glyphs · boolean · default: "true"

When true, WezTerm uses its own block glyph renderer instead of font glyphs.

config.custom_block_glyphs = true

Warn About Missing Glyphs

warn_about_missing_glyphs · boolean · default: "true"

When true, WezTerm logs warnings when glyphs are missing from fonts.

config.warn_about_missing_glyphs = false

Complete Font Configuration Example

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

-- Primary font
config.font = wezterm.font_with_fallback({
  { family = 'JetBrains Mono', weight = 'Medium' },
  { family = 'Noto Color Emoji', scale = 0.85 },
  'Symbols Nerd Font Mono',
})

-- Font size and spacing
config.font_size = 13.0
config.line_height = 1.1
config.cell_width = 1.0

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

-- Font rules for italic text
config.font_rules = {
  {
    intensity = 'Normal',
    italic = true,
    font = wezterm.font({
      family = 'Victor Mono',
      style = 'Italic',
    }),
  },
  {
    intensity = 'Bold',
    italic = true,
    font = wezterm.font({
      family = 'Victor Mono',
      weight = 'Bold',
      style = 'Italic',
    }),
  },
}

-- HarfBuzz features
config.harfbuzz_features = { 'calt=1', 'clig=1', 'liga=1' }

return config

See Also

• wezterm.font() - Font creation function
• wezterm.font_with_fallback() - Fallback font configuration (same page as font())
• Color Schemes - Color configuration