---
title: "WezTerm Font Shaping & HarfBuzz Features"
aliases: [wezterm-harfbuzz, wezterm-ligatures, font-shaping]
tags: [wezterm, fonts, ligatures, harfbuzz, dotfiles]
sources: [raw/Font Shaping - Wez's Terminal Emulator.md]
created: 2026-04-17
updated: 2026-04-17
---

## Font Shaping in WezTerm

Font shaping expands ligatures and applies OpenType features (positioning, glyph substitution) encoded in the font. WezTerm uses the **HarfBuzz** library for this.

---

## harfbuzz_features Option

Set globally in `wezterm.lua`:

```lua
config.harfbuzz_features = { 'calt=0', 'clig=0', 'liga=0' }
```

Or per-font (requires ≥ v20220101-133340-7edc5b5a):

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

---

## Common Feature Tags

| Tag | Purpose |
|-----|---------|
| `calt` | Contextual alternates |
| `clig` | Contextual ligatures |
| `liga` | Standard ligatures |
| `zero` | Slashed zero (Fira Code) |

To **disable all ligatures**: `{ 'calt=0', 'clig=0', 'liga=0' }`

---

## Per-Font in Fallback Stack

Apply features to one font without affecting fallbacks:

```lua
config.font = wezterm.font_with_fallback {
  {
    family = 'JetBrains Mono',
    weight = 'Medium',
    harfbuzz_features = { 'calt=0', 'clig=0', 'liga=0' },
  },
  { family = 'Terminus', weight = 'Bold' },
  'Noto Color Emoji',
}
```

---

## Stylistic Sets

Some fonts expose extended options via stylistic sets. Example for Fira Code:

```lua
config.harfbuzz_features = { 'zero' }  -- slashed zero instead of dotted
```

Fira Code stylistic sets: `ss01`–`ss06` (cursive italics, alternate `r`, etc.)

---

## Key Takeaways

- HarfBuzz handles all font shaping in WezTerm
- `harfbuzz_features` accepts CSS `font-feature-settings`-style tags
- Disable ligatures globally: `{ 'calt=0', 'clig=0', 'liga=0' }`
- Per-font features (since v20220101) let you mix fonts with different ligature settings in a fallback stack
- Stylistic sets (`ss01`–`ssXX`) and named features like `zero` unlock font-specific variants

---

## Related

- [[wiki/dotfiles/wezterm-config|WezTerm Config Structure]]
- [[wiki/dotfiles/wezterm-colors-appearance|WezTerm Colors & Appearance]]
- [[wiki/dotfiles/terminal-cheatsheet|Terminal Cheatsheet]]

---

## Sources

- [WezTerm Font Shaping docs](https://wezterm.org/config/font-shaping.html)
