wezterm.font() and font_with_fallback()

Configure fonts with attributes and fallback support for WezTerm

wezterm.font()

Constructs a font configuration for a single named font with optional style attributes.

Signature

function wezterm.font(
  family: string,
  attributes?: FontAttributes
) -> TextStyle

function wezterm.font(
  font_spec: FontSpec
) -> TextStyle

Parameters

family · string · required

The font family name. Can be one of:

• Family name (recommended): "JetBrains Mono" - doesn’t include style info
• Full name: "JetBrains Mono Regular" - includes sub-family
• PostScript name: Unique identifier encoded by font designer

attributes · FontAttributes

Optional table specifying font style attributes:

weight · string · default: "Regular"

Font weight. Options:

• "Thin"
• "ExtraLight"
• "Light"
• "DemiLight"
• "Book"
• "Regular" (default)
• "Medium"
• "DemiBold"
• "Bold"
• "ExtraBold"
• "Black"
• "ExtraBlack"

stretch · string · default: "Normal"

Font stretch. Options:

• "UltraCondensed"
• "ExtraCondensed"
• "Condensed"
• "SemiCondensed"
• "Normal" (default)
• "SemiExpanded"
• "Expanded"
• "ExtraExpanded"
• "UltraExpanded"

style · string · default: "Normal"

Font style. Options:

• "Normal" (default)
• "Italic" - distinctive design at an angle
• "Oblique" - similar to Normal but skewed

harfbuzz_features · string[]

HarfBuzz font shaping features to enable/disable. Example: { 'calt=0', 'clig=0', 'liga=0' } to disable ligatures

freetype_load_target · string

FreeType load target hint setting

freetype_render_target · string

FreeType render target setting

freetype_load_flags · string

FreeType load flags

assume_emoji_presentation · boolean

Control whether font is considered to have emoji presentation glyphs

Return Value

TextStyle · object

A text style object containing font configuration that can be assigned to config.font

Basic Examples

Simple Usage

local wezterm = require 'wezterm'

return {
  font = wezterm.font('JetBrains Mono'),
}

Advanced Features

Disable Ligatures

You can disable ligatures for specific fonts:

local wezterm = require 'wezterm'

return {
  font = wezterm.font {
    family = 'JetBrains Mono',
    harfbuzz_features = { 'calt=0', 'clig=0', 'liga=0' },
  },
}

Emoji Presentation

Control whether a font is considered to have emoji glyphs:

local wezterm = require 'wezterm'

return {
  font = wezterm.font {
    family = 'MyFont',
    assume_emoji_presentation = true,
  },
}

wezterm.font_with_fallback()

Constructs a font configuration with fallback fonts. Glyphs are looked up in the first font, but if missing, the next font is checked, and so on.

Signature

function wezterm.font_with_fallback(
  families: (string | FontSpec)[],
  attributes?: FontAttributes
) -> TextStyle

Parameters

families · array · required

Array of font families in preferred order. Each element can be:

• A string font family name
• A table with family and per-font attributes

attributes · FontAttributes

Optional attributes applied to all fonts (unless overridden per-font)

Return Value

TextStyle · object

A text style object with multiple fonts configured in fallback order

Examples

Basic Fallback

local wezterm = require 'wezterm'

return {
  font = wezterm.font_with_fallback {
    'JetBrains Mono',
    'Noto Color Emoji',
  },
}

Fallback Font Scaling

When mixing different font families, glyphs may appear to have different heights. WezTerm provides two ways to handle this:

Automatic Scaling

Use the use_cap_height_to_scale_fallback_fonts config option:

local wezterm = require 'wezterm'

return {
  use_cap_height_to_scale_fallback_fonts = true,
  font = wezterm.font_with_fallback {
    'JetBrains Mono',
    'Noto Sans CJK',
  },
}

This uses the font’s cap-height metric (or computes it) to automatically scale fallback fonts.

Manual Scaling

For CJK fonts or when automatic scaling doesn’t work well, manually specify the scale factor:

local wezterm = require 'wezterm'

return {
  line_height = 1.2,
  font = wezterm.font_with_fallback {
    'JetBrains Mono',
    { family = 'Microsoft YaHei', scale = 1.5 },
  },
}

Manual scaling cannot influence font metrics, so you may also need to adjust line_height for better appearance.

Font Resolution

WezTerm follows CSS Fonts Level 3 compatible font matching when resolving fonts:

1. Exact match: Tries to find a font that exactly matches the specified attributes
2. Close match: If no exact match, finds a close match within the font family
3. Fallback: If a glyph is missing, tries the next font in the fallback list

WezTerm can only use fonts installed on your system. If you request a condensed variant, you must have the condensed font file installed. WezTerm can synthesize basic bold and oblique for non-bitmap fonts, but this is not recommended.

Important Notes

• Use family names: The family name (without style info) is the most compatible
• Install all variants: If you want condensed, bold, or italic fonts, install those font files
• Implicit fallbacks: WezTerm adds its own default fallback fonts to your list
• Font files required: All fonts must be installed on your system

Related Configuration

• font_size - Set the font point size
• font_dirs - Additional directories to search for fonts
• line_height - Adjust line height multiplier
• use_cap_height_to_scale_fallback_fonts - Automatic fallback scaling

Source Reference

Implementation: config/src/lua.rs:552-641