Color Scheme Configuration

Configure color schemes and palettes in WezTerm using Lua

Color Scheme Configuration

WezTerm provides extensive color customization options, including built-in color schemes, custom palettes, and dynamic color configuration.

Using Built-in Color Schemes

WezTerm includes hundreds of pre-configured color schemes. You can select one using the color_scheme option:

local wezterm = require 'wezterm'
local config = wezterm.config_builder()

config.color_scheme = 'Dracula'

return config

color_scheme · string · default: "nil"

The name of a built-in color scheme. When set, this overrides the colors configuration.

Popular Color Schemes

Dark Themes

config.color_scheme = 'Dracula'
-- or
config.color_scheme = 'Catppuccin Mocha'
-- or
config.color_scheme = 'Tokyo Night'
-- or
config.color_scheme = 'Nord'

Listing Available Color Schemes

You can list all available color schemes using:

wezterm ls-color-schemes

Or programmatically in Lua:

local wezterm = require 'wezterm'

for name, scheme in pairs(wezterm.color.get_builtin_schemes()) do
  wezterm.log_info('Color scheme: ' .. name)
end

Custom Color Palettes

You can define your own color palette using the colors configuration option:

config.colors = {
  -- The default text color
  foreground = '#d4d4d4',
  -- The default background color
  background = '#1e1e1e',

  -- Overrides the cell background color when the current cell is occupied by the cursor
  cursor_bg = '#52ad70',
  -- Overrides the text color when the current cell is occupied by the cursor
  cursor_fg = '#1e1e1e',
  -- Specifies the border color of the cursor when the cursor style is set to Block
  cursor_border = '#52ad70',

  -- The foreground color of selected text
  selection_fg = '#1e1e1e',
  -- The background color of selected text
  selection_bg = '#3a3d41',

  -- The color of the scrollbar "thumb"; the portion that represents the current viewport
  scrollbar_thumb = '#3a3d41',

  -- The color of the split lines between panes
  split = '#444444',

  -- ANSI color palette (colors 0-7)
  ansi = {
    '#1e1e1e', -- black
    '#f48771', -- red
    '#a1cd5e', -- green
    '#e4c877', -- yellow
    '#6ab0f3', -- blue
    '#f47590', -- magenta
    '#00bcd4', -- cyan
    '#d4d4d4', -- white
  },

  -- Bright ANSI colors (colors 8-15)
  brights = {
    '#8b8b8b', -- bright black
    '#f48771', -- bright red
    '#a1cd5e', -- bright green
    '#e4c877', -- bright yellow
    '#6ab0f3', -- bright blue
    '#f47590', -- bright magenta
    '#00bcd4', -- bright cyan
    '#ffffff', -- bright white
  },
}

Color Palette Structure

colors · table · default: "nil"

A table defining the color palette for the terminal.

colors.foreground · string

The default text color in hex format (e.g., #d4d4d4).

colors.background · string

The default background color in hex format.

colors.cursor_bg · string

The cursor background color.

colors.cursor_fg · string

The cursor foreground/text color.

colors.cursor_border · string

The cursor border color (when using block cursor).

colors.selection_fg · string

The text color for selected text.

colors.selection_bg · string

The background color for selected text.

colors.ansi · array

An array of 8 colors for the standard ANSI palette (colors 0-7).

colors.brights · array

An array of 8 colors for the bright ANSI palette (colors 8-15).

Indexed Colors

You can also define indexed colors for the 256-color palette:

config.colors = {
  -- ... other colors ...
  indexed = {
    [16] = '#1a1a1a',
    [17] = '#2a2a2a',
    [52] = '#fbdada', -- Used by diff tools
    [88] = '#f6b6b6',
  },
}

colors.indexed · table · default: "{}"

A table mapping color indices (16-255) to hex color values.

Indices 0-15 should be specified using ansi and brights arrays, not the indexed table.

Tab Bar Colors

Customize the appearance of the tab bar:

config.colors = {
  tab_bar = {
    -- The color of the strip that goes along the top of the window
    background = '#0b0022',

    -- The active tab is the one that has focus in the window
    active_tab = {
      bg_color = '#2b2042',
      fg_color = '#c0c0c0',
      intensity = 'Normal',
      underline = 'None',
      italic = false,
      strikethrough = false,
    },

    -- Inactive tabs are the tabs that do not have focus
    inactive_tab = {
      bg_color = '#1b1032',
      fg_color = '#808080',
    },

    -- You can configure some additional styling when the mouse pointer
    -- moves over inactive tabs
    inactive_tab_hover = {
      bg_color = '#3b3052',
      fg_color = '#909090',
      italic = true,
    },

    -- The new tab button that let you create new tabs
    new_tab = {
      bg_color = '#1b1032',
      fg_color = '#808080',
    },

    -- When hovering over the new tab button
    new_tab_hover = {
      bg_color = '#3b3052',
      fg_color = '#909090',
      italic = true,
    },
  },
}

colors.tab_bar · table

Configuration for tab bar appearance.

Dynamic Color Schemes

You can change color schemes dynamically based on system appearance or time of day:

Based on System Appearance

local wezterm = require 'wezterm'
local config = wezterm.config_builder()

function scheme_for_appearance(appearance)
  if appearance:find('Dark') then
    return 'Dracula'
  else
    return 'GitHub Light'
  end
end

if wezterm.gui then
  config.color_scheme = scheme_for_appearance(wezterm.gui.get_appearance())
end

return config

Based on Time of Day

local wezterm = require 'wezterm'
local config = wezterm.config_builder()

function scheme_for_time()
  local hour = tonumber(os.date('%H'))
  if hour < 8 or hour >= 20 then
    return 'Tokyo Night'
  else
    return 'GitHub Light'
  end
end

config.color_scheme = scheme_for_time()

return config

Color Transformations

Foreground Text Adjustments

You can adjust the foreground text colors using HSB (Hue, Saturation, Brightness) transformations:

config.foreground_text_hsb = {
  hue = 1.0,        -- multiplier, 1.0 = no change
  saturation = 1.0, -- multiplier, 1.0 = no change  
  brightness = 1.0, -- multiplier, 1.0 = no change
}

foreground_text_hsb · table · default: "{hue=1.0, saturation=1.0, brightness=1.0}"

HSB transformation applied to foreground text colors.

Example - make text slightly brighter:

config.foreground_text_hsb = {
  hue = 1.0,
  saturation = 1.0,
  brightness = 1.2, -- 20% brighter
}

Bold Text Brightening

bold_brightens_ansi_colors · string · default: "BrightAndBold"

Controls whether bold text is rendered using bright colors. Valid values are:

• BrightAndBold: Use bright colors for bold text
• BrightOnly: Use bright colors but don’t render as bold
• No: Don’t use bright colors for bold text

config.bold_brightens_ansi_colors = 'BrightAndBold'

Custom Color Scheme Files

You can define color schemes in separate files and load them:

Creating a Color Scheme File

Create a file ~/.config/wezterm/colors/mytheme.toml:

[colors]
foreground = "#d4d4d4"
background = "#1e1e1e"
cursor_bg = "#52ad70"
cursor_border = "#52ad70"
cursor_fg = "#1e1e1e"
selection_bg = "#3a3d41"
selection_fg = "#1e1e1e"

ansi = ["#1e1e1e", "#f48771", "#a1cd5e", "#e4c877", "#6ab0f3", "#f47590", "#00bcd4", "#d4d4d4"]
brights = ["#8b8b8b", "#f48771", "#a1cd5e", "#e4c877", "#6ab0f3", "#f47590", "#00bcd4", "#ffffff"]

[metadata]
name = "My Custom Theme"
author = "Your Name"

Loading Custom Color Schemes

config.color_scheme_dirs = { '~/.config/wezterm/colors' }
config.color_scheme = 'My Custom Theme'

color_scheme_dirs · array · default: "[]"

Additional directories to search for color scheme files (TOML format).

Quick Select and Copy Mode Colors

Customize colors for WezTerm’s quick select and copy mode features:

config.colors = {
  -- Quick select labels (like vim-easymotion)
  quick_select_label_bg = { Color = '#fb4934' },
  quick_select_label_fg = { Color = '#ebdbb2' },
  quick_select_match_bg = { Color = '#b8bb26' },
  quick_select_match_fg = { Color = '#3c3836' },

  -- Copy mode colors
  copy_mode_active_highlight_bg = { Color = '#fabd2f' },
  copy_mode_active_highlight_fg = { Color = '#282828' },
  copy_mode_inactive_highlight_bg = { Color = '#d65d0e' },
  copy_mode_inactive_highlight_fg = { Color = '#ebdbb2' },
}

When setting a color_scheme, it will override any values you set in the colors table. If you want to customize specific colors while using a base scheme, you need to get the scheme first and modify it.

Modifying Built-in Color Schemes

local wezterm = require 'wezterm'
local config = wezterm.config_builder()

-- Get the built-in color scheme
local scheme = wezterm.color.get_builtin_schemes()['Dracula']

-- Modify specific colors
scheme.background = '#1a1a1a'
scheme.tab_bar.background = '#1a1a1a'

-- Add it as a custom scheme
config.color_schemes = {
  ['Dracula Modified'] = scheme,
}

config.color_scheme = 'Dracula Modified'

return config

See Also

• Window Configuration - Window appearance options
• Appearance Documentation - General appearance configuration
• Color Scheme Gallery - Browse available schemes