> ## 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, fallbacks, weights, styles, and advanced font rendering options in WezTerm

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

<CodeGroup>
  ```lua Simple Font theme={null}
  local wezterm = require 'wezterm'
  local config = wezterm.config_builder()

  config.font = wezterm.font 'Fira Code'

  return config
  ```

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

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

  return config
  ```

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

  config.font = wezterm.font('Cascadia Code', {
    weight = 'Medium',
    stretch = 'Normal',
    italic = false,
  })

  return config
  ```
</CodeGroup>

### Font Size

Set the font size in points:

```lua theme={null}
config.font_size = 12.0

-- You can use fractional sizes
config.font_size = 13.3
```

<Note>
  The default font size is 12.0 points. Fractional sizes like 13.3 allow fine-tuning.
</Note>

## Font Fallback

WezTerm automatically falls back to other fonts when glyphs are missing:

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

<Steps>
  <Step title="Primary Font">
    WezTerm checks the first font in the list.
  </Step>

  <Step title="Fallback Chain">
    If the glyph isn't found, it proceeds to the next font.
  </Step>

  <Step title="Built-in Fallbacks">
    WezTerm's default fallbacks (Nerd Font Symbols, Noto Color Emoji) are automatically appended.
  </Step>

  <Step title="System Fallbacks">
    If still not found, system-wide fallback fonts are checked.
  </Step>

  <Step title="Last Resort">
    A placeholder glyph is rendered if no font contains the character.
  </Step>
</Steps>

<Tip>
  You don't need to include Nerd Font Symbols in your fallback list - it's automatically included!
</Tip>

## Font Weight and Style

### Available Weights

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

<Tabs>
  <Tab title="Italic">
    ```lua theme={null}
    config.font = wezterm.font('JetBrains Mono', {
      italic = true,
    })
    ```
  </Tab>

  <Tab title="Oblique">
    ```lua theme={null}
    config.font = wezterm.font('Monaco', {
      style = 'Oblique',
    })
    ```
  </Tab>

  <Tab title="Normal">
    ```lua theme={null}
    config.font = wezterm.font('Courier', {
      style = 'Normal', -- Default
    })
    ```
  </Tab>
</Tabs>

### Font Stretch

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

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

```lua theme={null}
-- Default is 1.0
config.line_height = 1.2

-- Tighter spacing
config.line_height = 0.9
```

### Cell Width

Adjust character width:

```lua theme={null}
-- Default is 1.0
config.cell_width = 1.1

-- Narrower spacing
config.cell_width = 0.9
```

### Underline Customization

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

### Cursor Thickness

```lua theme={null}
config.cursor_thickness = '2px'
```

<Note>
  These options accept pixel values (e.g., `'2px'`) or percentage values (e.g., `'200%'`).
</Note>

## Font Loading and Discovery

### Custom Font Directories

Add additional directories to search for fonts:

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

### Font Locator

Choose how WezTerm finds fonts:

<Tabs>
  <Tab title="ConfigDirsOnly">
    ```lua theme={null}
    -- Only search in font_dirs
    config.font_locator = 'ConfigDirsOnly'
    ```
  </Tab>

  <Tab title="FontConfig (Linux)">
    ```lua theme={null}
    -- Use FontConfig system
    config.font_locator = 'FontConfig'
    ```
  </Tab>

  <Tab title="CoreText (macOS)">
    ```lua theme={null}
    -- Use macOS CoreText
    config.font_locator = 'CoreText'
    ```
  </Tab>
</Tabs>

## Font Rendering

### Font Shaper

Control text shaping and ligatures:

```lua theme={null}
-- Harfbuzz (default) - full ligature support
config.font_shaper = 'Harfbuzz'

-- AllSorts - alternative shaper
config.font_shaper = 'AllSorts'
```

### FreeType Options (Linux/Windows)

<CodeGroup>
  ```lua Load Flags theme={null}
  config.freetype_load_flags = 'NO_HINTING'
  -- Options:
  -- 'DEFAULT'
  -- 'NO_HINTING'
  -- 'NO_AUTOHINT'
  -- 'FORCE_AUTOHINT'
  -- 'MONOCHROME'
  -- 'NO_AUTOHINT|FORCE_AUTOHINT'
  ```

  ```lua Load Target theme={null}
  config.freetype_load_target = 'Normal'
  -- Options:
  -- 'Normal' (default)
  -- 'Light'
  -- 'Mono'
  -- 'HorizontalLcd'
  ```

  ```lua Render Target theme={null}
  config.freetype_render_target = 'Normal'
  -- Options:
  -- 'Normal' (default)
  -- 'Light'
  -- 'Mono'
  -- 'HorizontalLcd'
  ```
</CodeGroup>

### DPI Override

```lua theme={null}
-- Force specific DPI (useful for high-density displays)
config.dpi = 144.0
```

## Special Font Features

### Bold and Bright Colors

```lua theme={null}
-- Make bold text use bright ANSI colors
config.bold_brightens_ansi_colors = true
```

### Square Glyph Overflow

```lua theme={null}
-- Allow box-drawing characters to extend slightly
config.allow_square_glyphs_to_overflow_width = 'WhenFollowedBySpace'
-- Options:
-- 'Never'
-- 'Always'
-- 'WhenFollowedBySpace'
```

### Cap Height Scaling

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

```bash theme={null}
# 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:

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

<Warning>
  **Font not found**: Ensure the font is installed system-wide or added to `font_dirs`.
</Warning>

<Warning>
  **Ligatures not working**: Check that `font_shaper = 'Harfbuzz'` is set and your font supports ligatures.
</Warning>

<Warning>
  **Blurry fonts on Linux**: Try adjusting `freetype_load_target` and `freetype_render_target`.
</Warning>

## Complete Example

Here's a comprehensive font configuration:

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