Skip to main content

​
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

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

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
  • 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