---
title: "WezTerm Colors & Appearance"
aliases: [wezterm-theming, wezterm-color-scheme, wezterm-appearance]
tags: [wezterm, terminal, colors, theming, dotfiles, lua]
sources: ["raw/Colors & Appearance - Wez's Terminal Emulator.md"]
created: 2026-04-17
updated: 2026-04-17
---

## WezTerm Colors & Appearance

Full reference for theming WezTerm: color schemes, custom palettes, tab bar styling, pane dimming, background images, and opacity.

---

## Color Schemes

WezTerm ships with 700+ built-in schemes from iTerm2-Color-Schemes, base16, Gogh, and terminal.sexy.

```lua
config.color_scheme = 'Batman'
```

- Browse all schemes: `wezterm.org/colorschemes/index.html`
- Auto-switch dark/light based on OS: use `wezterm.gui.get_appearance()`
- **Multiplexing note:** when using SSH/TLS domains, the color scheme is controlled by the *server-side* config, not the client

### Precedence Rules

1. `color_scheme` (named scheme) takes priority over `colors` section
2. Since v20220903: `color_scheme` defines base colors, then `colors` overrides on top
3. To merge: use `wezterm.color.get_default_colors()` and manually merge

---

## Defining Custom Colors

```lua
config.colors = {
  foreground = 'silver',
  background = 'black',

  cursor_bg = '#52ad70',
  cursor_fg = 'black',
  cursor_border = '#52ad70',

  selection_fg = 'black',
  selection_bg = '#fffacd',

  scrollbar_thumb = '#222222',
  split = '#444444',         -- pane split line color

  ansi   = { 'black', 'maroon', 'green', 'olive', 'navy', 'purple', 'teal', 'silver' },
  brights = { 'grey', 'red', 'lime', 'yellow', 'blue', 'fuchsia', 'aqua', 'white' },

  indexed = { [136] = '#af8700' },   -- palette index 16–255

  compose_cursor = 'orange',         -- visual cue during IME/dead key input

  -- copy_mode / quick_select
  copy_mode_active_highlight_bg   = { Color = '#000000' },
  copy_mode_active_highlight_fg   = { AnsiColor = 'Black' },
  copy_mode_inactive_highlight_bg = { Color = '#52ad70' },
  copy_mode_inactive_highlight_fg = { AnsiColor = 'White' },

  quick_select_label_bg  = { Color = 'peru' },
  quick_select_label_fg  = { Color = '#ffffff' },
  quick_select_match_bg  = { AnsiColor = 'Navy' },
  quick_select_match_fg  = { Color = '#ffffff' },
}
```

### Color Formats Supported

- SVG/CSS3 named colors: `'silver'`, `'black'`
- Hex: `'#RRGGBB'`
- HSL string: `'hsl:235 100 50'`
- CSS-style: `rgb(0,255,0)`, `rgba(0,255,0,1)`, `hsl(120,100%,50%)`, `hwb(...)`, `hsv(...)`
- Alpha is **only** applied for `selection_fg` / `selection_bg` — ignored elsewhere

---

## Inline Color Schemes

Define named schemes inside `wezterm.lua` — they override all built-ins:

```lua
config.color_scheme = 'Red Scheme'

config.color_schemes = {
  ['Red Scheme'] = { background = 'red' },
  ['Blue Scheme'] = { background = 'blue' },
}
```

Use `wezterm.get_builtin_color_schemes()` for advanced use (random scheme, derive from built-in).

## External Color Scheme Files

- Format: TOML with a `[colors]` section
- Default location: `~/.config/wezterm/colors/` (POSIX) or `colors/` beside `wezterm.exe` (Windows)
- Custom path:

```lua
config.color_scheme_dirs = { '/some/path/to/my/color/schemes' }
```

Files in `color_scheme_dirs` override built-ins.

---

## Dynamic Color Changes (Escape Sequences)

WezTerm supports runtime palette changes via escape sequences. The `dynamic-colors/` directory in iTerm2-Color-Schemes contains ready-made shell scripts:

```sh
bash SomeName.sh   # switches color scheme immediately
```

---

## Tab Bar Appearance

### Key Options

| Option | Effect |
|--------|--------|
| `use_fancy_tab_bar` | `true` = native/fancy (default), `false` = retro |
| `enable_tab_bar` | toggle tab bar on/off |
| `hide_tab_bar_if_only_one_tab` | auto-hide when single tab |
| `tab_bar_at_bottom` | move bar to bottom |
| `tab_max_width` | max cell width per tab (retro mode) |

### Fancy Tab Bar

```lua
config.window_frame = {
  font      = wezterm.font { family = 'Roboto', weight = 'Bold' },
  font_size = 12.0,
  active_titlebar_bg   = '#333333',
  inactive_titlebar_bg = '#333333',
}
config.colors = {
  tab_bar = { inactive_tab_edge = '#575757' },
}
```

### Retro Tab Bar

```lua
config.colors = {
  tab_bar = {
    background = '#0b0022',
    active_tab   = { bg_color = '#2b2042', fg_color = '#c0c0c0', intensity = 'Normal' },
    inactive_tab = { bg_color = '#1b1032', fg_color = '#808080' },
    inactive_tab_hover = { bg_color = '#3b3052', fg_color = '#909090', italic = true },
    new_tab       = { bg_color = '#1b1032', fg_color = '#808080' },
    new_tab_hover = { bg_color = '#3b3052', fg_color = '#909090', italic = true },
  },
}
```

---

## Inactive Pane Styling

Inactive panes are dimmed/de-saturated by default. Override with HSB multipliers:

```lua
config.inactive_pane_hsb = {
  saturation = 0.9,   -- < 1.0 = more washed out
  brightness  = 0.8,  -- < 1.0 = dimmer
}
```

- Values are **multipliers** on existing HSV components (1.0 = no change, 0.5 = half)
- Range: 0.0 and up

---

## Window Background Image

```lua
config.window_background_image = '/path/to/wallpaper.jpg'

config.window_background_image_hsb = {
  brightness = 0.3,   -- darken to 1/3
  hue        = 1.0,
  saturation = 1.0,
}
```

- Supported formats: PNG, JPEG, GIF, BMP, ICO, TIFF, PNM, DDS, TGA, farbfeld
- Animated GIF/PNG animate while window is focused
- Large images increase VRAM usage — resize before use
- For tiling/scrolling/repeating control use the `background` config option instead

---

## Window Background Gradient

Available since v20210814. See `window_background_gradient` config option for full syntax.

---

## Background & Text Opacity

```lua
config.window_background_opacity = 0.9   -- 0.0 = fully transparent, 1.0 = opaque
config.text_background_opacity    = 0.3  -- applies to non-default background cells only
```

- Compositing required: macOS, Windows, Wayland — supported out of the box; X11 needs a compositing WM
- Non-1.0 opacity impacts render performance

---

## Key Takeaways

- **700+ built-in schemes** — set with one line: `config.color_scheme = 'Name'`
- **`color_scheme` overrides `colors`** — to override specific colors, either drop `color_scheme` or use `get_default_colors()` to merge
- **Color formats** — hex, named, HSL string, and full CSS color syntax all work
- **Two tab bar modes** — fancy (native OS look) vs retro; each has distinct color keys
- **Inactive panes** — dimmed via `inactive_pane_hsb` HSB multipliers, not absolute values
- **Background image HSB** — same multiplier approach as inactive panes
- **Opacity** — both window background and text cell background are independently controllable
- **Dynamic colors** — escape-sequence driven; use iTerm2-Color-Schemes `dynamic-colors/` scripts for live switching

---

## Related

- [[wiki/dotfiles/wezterm-cli-reference|WezTerm CLI Reference]]
- [[wiki/dotfiles/terminal-cheatsheet|Terminal Cheatsheet]]
- [[wiki/dotfiles/linux-terminal-ricing|Linux Terminal Ricing]]

---

## Sources

- `raw/Colors & Appearance - Wez's Terminal Emulator.md`
- Original: https://wezterm.org/config/appearance.html
