> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/wezterm/wezterm/llms.txt
> Use this file to discover all available pages before exploring further.

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

```lua theme={null}
local wezterm = require 'wezterm'
local config = wezterm.config_builder()

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

return config
```

<ParamField path="font" type="TextStyle" default="wezterm.font('JetBrains Mono')">
  The primary font configuration. Accepts a TextStyle object created with `wezterm.font()` or `wezterm.font_with_fallback()`.
</ParamField>

<ParamField path="font_size" type="number" default="12.0">
  The font size measured in points. Default is platform-dependent.
</ParamField>

### Font with Attributes

You can specify font weight, style, and stretch:

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

<ParamField path="weight" type="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)
</ParamField>

<ParamField path="style" type="string" default="'Normal'">
  Font style. Valid values: `Normal`, `Italic`, `Oblique`
</ParamField>

<ParamField path="stretch" type="string" default="'Normal'">
  Font stretch. Valid values: `UltraCondensed`, `ExtraCondensed`, `Condensed`, `SemiCondensed`, `Normal`, `SemiExpanded`, `Expanded`, `ExtraExpanded`, `UltraExpanded`
</ParamField>

### Font Examples

<CodeGroup>
  ```lua Bold Font theme={null}
  config.font = wezterm.font('Cascadia Code', { weight = 'Bold' })
  ```

  ```lua Italic Font theme={null}
  config.font = wezterm.font('Victor Mono', { style = 'Italic' })
  ```

  ```lua Custom Weight theme={null}
  config.font = wezterm.font('Inter', { weight = 450 })
  ```
</CodeGroup>

## Font Fallbacks

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

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

<Note>
  WezTerm automatically adds 'Noto Color Emoji' and 'Symbols Nerd Font Mono' as fallbacks if they're not explicitly included.
</Note>

### Fallback with Attributes

```lua theme={null}
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

<ParamField path="line_height" type="number" default="1.0">
  Multiplier for line height. A value of 1.0 uses the font's recommended line spacing.
</ParamField>

```lua theme={null}
config.line_height = 1.2 -- 20% taller lines
```

### Cell Width

<ParamField path="cell_width" type="number" default="1.0">
  Multiplier for cell width. A value of 1.0 uses the font's natural width.
</ParamField>

```lua theme={null}
config.cell_width = 0.9 -- 10% narrower cells
```

<Warning>
  Modifying `cell_width` can affect character alignment and may cause rendering issues with some TUI applications.
</Warning>

## Font Rules

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

```lua theme={null}
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',
    }),
  },
}
```

<ParamField path="font_rules" type="array" default="[]">
  An array of font rule objects that match cell attributes and specify alternative fonts.
</ParamField>

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:

```lua theme={null}
config.font_dirs = {
  '~/.local/share/fonts',
  '/usr/share/fonts',
}
```

<ParamField path="font_dirs" type="array" default="[]">
  Additional directories to search for font files. Relative paths are resolved relative to the config file location.
</ParamField>

## Font Locator

<ParamField path="font_locator" type="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`
</ParamField>

```lua theme={null}
config.font_locator = 'ConfigDirsOnly'
```

## Font Rendering

### Font Rasterizer

<ParamField path="font_rasterizer" type="string" default="'FreeType'">
  Selects the font rasterizer. Valid values: `FreeType`, `Harfbuzz`
</ParamField>

```lua theme={null}
config.font_rasterizer = 'FreeType'
```

### Font Shaper

<ParamField path="font_shaper" type="string" default="'Harfbuzz'">
  Selects the font shaper for text layout. Valid values: `Harfbuzz`, `Allsorts`
</ParamField>

```lua theme={null}
config.font_shaper = 'Harfbuzz'
```

## FreeType Configuration

### Anti-aliasing

<ParamField path="font_antialias" type="string" default="'Subpixel'">
  Controls anti-aliasing. Valid values: `None`, `Greyscale`, `Subpixel`
</ParamField>

```lua theme={null}
config.font_antialias = 'Subpixel'
```

### Hinting

<ParamField path="font_hinting" type="string" default="'Full'">
  Controls font hinting. Valid values: `None`, `Vertical`, `VerticalSubpixel`, `Full`
</ParamField>

```lua theme={null}
config.font_hinting = 'Full'
```

### FreeType Load Target

<ParamField path="freetype_load_target" type="string" default="'Normal'">
  FreeType rendering target. Valid values: `Normal`, `Light`, `Mono`, `HorizontalLcd`, `VerticalLcd`
</ParamField>

```lua theme={null}
config.freetype_load_target = 'Normal'
```

### FreeType Load Flags

<ParamField path="freetype_load_flags" type="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`
</ParamField>

```lua theme={null}
config.freetype_load_flags = 'NO_HINTING'
```

### FreeType Interpreter Version

<ParamField path="freetype_interpreter_version" type="number" default="nil">
  Specifies the FreeType interpreter version (35, 38, or 40). Affects subpixel hinting.
</ParamField>

```lua theme={null}
config.freetype_interpreter_version = 40
```

## Display Configuration

### Pixel Geometry

<ParamField path="display_pixel_geometry" type="string" default="'RGB'">
  Specifies the subpixel order. Valid values: `RGB`, `BGR`
</ParamField>

```lua theme={null}
config.display_pixel_geometry = 'RGB'
```

### DPI

<ParamField path="dpi" type="number" default="nil">
  Override the DPI for font rendering. If not set, WezTerm uses the system DPI.
</ParamField>

```lua theme={null}
config.dpi = 144.0
```

### Per-Screen DPI

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

<ParamField path="dpi_by_screen" type="table" default="{}">
  A table mapping screen names to DPI values.
</ParamField>

## Advanced Font Features

### HarfBuzz Features

You can enable or disable OpenType font features:

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

<ParamField path="harfbuzz_features" type="array" default="nil">
  Array of OpenType feature strings to apply globally.
</ParamField>

You can also specify features per-font:

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

### Font Scaling

Scale individual fallback fonts:

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

### Use Cap Height Scaling

<ParamField path="use_cap_height_to_scale_fallback_fonts" type="boolean" default="false">
  When true, fallback fonts are scaled to match the cap height of the primary font.
</ParamField>

```lua theme={null}
config.use_cap_height_to_scale_fallback_fonts = true
```

## Cursor Thickness

<ParamField path="cursor_thickness" type="string" default="'1px'">
  The thickness of the cursor. Can be specified in pixels or as a fraction of the cell width.
</ParamField>

```lua theme={null}
config.cursor_thickness = '2px'
-- or
config.cursor_thickness = '0.1cell'
```

## Underline Configuration

<ParamField path="underline_thickness" type="string" default="nil">
  The thickness of underlines. Can be specified in pixels or as a fraction of the cell height.
</ParamField>

<ParamField path="underline_position" type="string" default="nil">
  The position of underlines from the baseline.
</ParamField>

```lua theme={null}
config.underline_thickness = '2px'
config.underline_position = '-4px'
```

## Strikethrough Configuration

<ParamField path="strikethrough_position" type="string" default="nil">
  The vertical position of strikethrough lines.
</ParamField>

```lua theme={null}
config.strikethrough_position = '0.5cell'
```

## Character Width Behavior

### Allow Square Glyph Overflow

<ParamField path="allow_square_glyphs_to_overflow_width" type="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
</ParamField>

```lua theme={null}
config.allow_square_glyphs_to_overflow_width = 'WhenFollowedBySpace'
```

### Custom Block Glyphs

<ParamField path="custom_block_glyphs" type="boolean" default="true">
  When true, WezTerm uses its own block glyph renderer instead of font glyphs.
</ParamField>

```lua theme={null}
config.custom_block_glyphs = true
```

### Warn About Missing Glyphs

<ParamField path="warn_about_missing_glyphs" type="boolean" default="true">
  When true, WezTerm logs warnings when glyphs are missing from fonts.
</ParamField>

```lua theme={null}
config.warn_about_missing_glyphs = false
```

## Complete Font Configuration Example

```lua theme={null}
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()](/lua/wezterm/font) - Font creation function
* [wezterm.font\_with\_fallback()](/lua/wezterm/font) - Fallback font configuration (same page as font())
* [Color Schemes](./color-schemes) - Color configuration