Appearance Configuration

Customize colors, themes, backgrounds, transparency, and visual styles in WezTerm

Color Schemes

WezTerm includes over 700 built-in color schemes from popular collections:

• iTerm2-Color-Schemes
• base16
• Gogh
• terminal.sexy

Applying a Color Scheme

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

config.color_scheme = 'Dracula'

return config

Browse all available color schemes at the WezTerm Color Schemes Gallery.

Dynamic Color Scheme Selection

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 'Solarized Light'
  end
end

config.color_scheme = scheme_for_appearance(wezterm.gui.get_appearance())

return config

Random Color Scheme

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

-- Get all built-in color schemes
local schemes = wezterm.get_builtin_color_schemes()
local scheme_names = {}
for name, _ in pairs(schemes) do
  table.insert(scheme_names, name)
end

-- Pick a random one
math.randomseed(os.time())
config.color_scheme = scheme_names[math.random(#scheme_names)]

return config

Custom Colors

Define your own colors or override specific colors from a scheme:

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

config.colors = {
  -- The default text color
  foreground = '#c0c0c0',
  -- The default background color
  background = '#1a1a1a',
  
  -- Cursor colors
  cursor_bg = '#52ad70',
  cursor_fg = '#000000',
  cursor_border = '#52ad70',
  
  -- Selection colors
  selection_fg = '#000000',
  selection_bg = '#fffacd',
  
  -- Scrollbar thumb color
  scrollbar_thumb = '#333333',
  
  -- Split separator color
  split = '#444444',
  
  -- ANSI color palette
  ansi = {
    '#000000', -- black
    '#cc0403', -- red
    '#19cb00', -- green
    '#cecb00', -- yellow
    '#0d73cc', -- blue
    '#cb1ed1', -- magenta
    '#0dcdcd', -- cyan
    '#dddddd', -- white
  },
  
  -- Bright ANSI colors
  brights = {
    '#767676', -- bright black
    '#f2201f', -- bright red
    '#23fd00', -- bright green
    '#fffd00', -- bright yellow
    '#1a8fff', -- bright blue
    '#fd28ff', -- bright magenta
    '#14ffff', -- bright cyan
    '#ffffff', -- bright white
  },
  
  -- Arbitrary colors (indices 16-255)
  indexed = { [136] = '#af8700' },
  
  -- Compose cursor color
  compose_cursor = '#ff9e64',
}

return config

Color Formats

WezTerm supports multiple color formats:

Named Colors

config.colors = {
  foreground = 'silver',
  background = 'black',
}

Precedence: colors vs color_scheme

Since version 20220903-194523-3bb1ed61, the color_scheme is applied first, then any colors defined in colors override the scheme values.

config.color_scheme = 'Dracula'

-- Override just the background
config.colors = {
  background = '#000000', -- Darker than Dracula's default
}

Custom Color Schemes

Define reusable color schemes in your configuration:

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

config.color_schemes = {
  ['My Red Scheme'] = {
    background = '#330000',
    foreground = '#ffffff',
    ansi = {
      '#000000', '#dd0000', '#00dd00', '#dddd00',
      '#0000dd', '#dd00dd', '#00dddd', '#dddddd',
    },
    brights = {
      '#444444', '#ff0000', '#00ff00', '#ffff00',
      '#0000ff', '#ff00ff', '#00ffff', '#ffffff',
    },
  },
  ['My Blue Scheme'] = {
    background = '#000033',
    foreground = '#ffffff',
  },
}

config.color_scheme = 'My Red Scheme'

return config

Tab Bar Appearance

Tab Bar Styles

WezTerm offers two tab bar styles:

Fancy (Default)

config.use_fancy_tab_bar = true
config.window_frame = {
  font = wezterm.font { family = 'Roboto', weight = 'Bold' },
  font_size = 12.0,
  active_titlebar_bg = '#2b2042',
  inactive_titlebar_bg = '#2b2042',
}

Retro

config.use_fancy_tab_bar = false
config.tab_bar_at_bottom = false

Retro Tab Bar Colors

config.use_fancy_tab_bar = false

config.colors = {
  tab_bar = {
    background = '#0b0022',
    
    active_tab = {
      bg_color = '#2b2042',
      fg_color = '#c0c0c0',
      intensity = 'Normal',
      underline = 'None',
      italic = false,
      strikethrough = false,
    },
    
    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,
    },
  },
}

Tab Bar Position and Visibility

-- Hide tab bar when only one tab
config.hide_tab_bar_if_only_one_tab = true

-- Disable tab bar completely
config.enable_tab_bar = false

-- Place tab bar at bottom
config.tab_bar_at_bottom = true

-- Maximum tab width in cells (retro mode only)
config.tab_max_width = 32

Window Transparency

Background Opacity

-- Fully opaque (default)
config.window_background_opacity = 1.0

-- Semi-transparent
config.window_background_opacity = 0.9

-- Very transparent
config.window_background_opacity = 0.5

Background opacity requires a compositing window manager (macOS, Windows, Wayland, or X11 with compositor).

Text Background Opacity

-- Make text backgrounds less opaque
config.text_background_opacity = 0.7

Platform-Specific Effects

macOS

-- Background blur effect
config.macos_window_background_blur = 30

Windows 11

-- Acrylic, Mica, or Tabbed effects
config.win32_system_backdrop = 'Acrylic'
-- Options: 'Auto', 'Disable', 'Acrylic', 'Mica', 'Tabbed'

config.win32_acrylic_accent_color = '#2b2042'

KDE (Linux)

-- Enable blur effect
config.kde_window_background_blur = 20

Background Images

Simple Background Image

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

-- Adjust image appearance
config.window_background_image_hsb = {
  brightness = 0.3,   -- Darken to 30%
  hue = 1.0,          -- No hue change
  saturation = 1.0,   -- No saturation change
}

Advanced Multi-Layer Backgrounds

Create complex backgrounds with multiple layers:

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

config.background = {
  -- Background layer
  {
    source = { File = '/path/to/background.png' },
    width = '100%',
    height = '100%',
    opacity = 0.3,
    hsb = { brightness = 0.1 },
  },
  -- Overlay layer with parallax scrolling
  {
    source = { File = '/path/to/overlay.png' },
    width = '100%',
    repeat_x = 'NoRepeat',
    repeat_y = 'Mirror',
    vertical_align = 'Bottom',
    attachment = { Parallax = 0.2 }, -- Scrolls at 20% speed
    opacity = 0.5,
  },
  -- Gradient overlay
  {
    source = {
      Gradient = {
        colors = { '#000000', '#2b2042' },
        orientation = 'Vertical',
      },
    },
    width = '100%',
    height = '100%',
    opacity = 0.8,
  },
}

return config

Background Layer Options

1. Source

   Define the image source:

   source = { File = '/path/to/image.png' }
   source = { Color = '#2b2042' }
   source = { Gradient = { preset = 'Warm' } }
   
2. Sizing

   Control dimensions:

   width = '100%'      -- Viewport percentage
   height = '50%'
   width = 800         -- Pixels
   height = '20cell'   -- Terminal cells
   width = 'Cover'     -- Scale to cover (default)
   width = 'Contain'   -- Scale to fit
   
3. Positioning

   Align the layer:

   horizontal_align = 'Center'  -- Left, Center, Right
   vertical_align = 'Middle'    -- Top, Middle, Bottom
   horizontal_offset = '10%'
   vertical_offset = '5cell'
   
4. Repetition

   Control tiling:

   repeat_x = 'Repeat'   -- Repeat, Mirror, NoRepeat
   repeat_y = 'NoRepeat'
   repeat_x_size = '100%'
   
5. Scrolling

   Set scroll behavior:

   attachment = 'Fixed'        -- Stays in place
   attachment = 'Scroll'       -- Scrolls 1:1
   attachment = { Parallax = 0.5 }  -- Scrolls at 50% speed
   

Background Gradients

Create gradient backgrounds without image files:

Vertical Gradient

config.window_background_gradient = {
  colors = { '#1a1a1a', '#2b2042' },
  orientation = 'Vertical',
}

Window Padding

Add spacing around terminal content:

config.window_padding = {
  left = 20,
  right = 20,
  top = 10,
  bottom = 10,
}

-- Or use uniform padding
config.window_padding = {
  left = '1cell',
  right = '1cell',
  top = '0.5cell',
  bottom = '0.5cell',
}

Pane Styling

Inactive Pane Dimming

-- Dim and desaturate inactive panes
config.inactive_pane_hsb = {
  saturation = 0.9,  -- Reduce color intensity
  brightness = 0.8,  -- Dim slightly
  hue = 1.0,         -- No hue shift
}

-- No dimming
config.inactive_pane_hsb = {
  saturation = 1.0,
  brightness = 1.0,
}

Pane Borders

config.colors = {
  split = '#444444',  -- Border color between panes
}

Window Decorations

Control window frame appearance:

-- Full decorations (default on most platforms)
config.window_decorations = 'TITLE | RESIZE'

-- No title bar
config.window_decorations = 'RESIZE'

-- No decorations at all
config.window_decorations = 'NONE'

-- Integrated buttons (macOS-style)
config.window_decorations = 'INTEGRATED_BUTTONS | RESIZE'

Integrated Title Buttons

config.integrated_title_buttons = { 'Hide', 'Maximize', 'Close' }
config.integrated_title_button_style = 'Windows'  -- or 'MacOsNative', 'Gnome'
config.integrated_title_button_alignment = 'Right'  -- or 'Left'

config.integrated_title_button_color = {
  text = '#cccccc',
  hover_bg = '#3b3052',
  hover_fg = '#ffffff',
}

Cursor Appearance

-- Cursor style
config.default_cursor_style = 'SteadyBlock'
-- Options: 'SteadyBlock', 'BlinkingBlock', 'SteadyUnderline',
--          'BlinkingUnderline', 'SteadyBar', 'BlinkingBar'

-- Cursor blink rate
config.cursor_blink_rate = 800  -- milliseconds
config.cursor_blink_ease_in = 'Constant'
config.cursor_blink_ease_out = 'Constant'

-- Cursor thickness (for bar/underline)
config.cursor_thickness = '2px'

Complete Appearance Example

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

-- Color scheme
config.color_scheme = 'Dracula'

-- Override specific colors
config.colors = {
  background = '#1a1a1a',
  tab_bar = {
    background = '#1a1a1a',
    active_tab = {
      bg_color = '#2b2042',
      fg_color = '#c0c0c0',
    },
    inactive_tab = {
      bg_color = '#1a1a1a',
      fg_color = '#808080',
    },
  },
}

-- Transparency and effects
config.window_background_opacity = 0.95
config.macos_window_background_blur = 20

-- Window frame
config.window_decorations = 'RESIZE'
config.window_padding = {
  left = 20,
  right = 20,
  top = 10,
  bottom = 10,
}

-- Tab bar
config.use_fancy_tab_bar = true
config.hide_tab_bar_if_only_one_tab = true
config.tab_bar_at_bottom = false

-- Panes
config.inactive_pane_hsb = {
  saturation = 0.9,
  brightness = 0.8,
}

-- Cursor
config.default_cursor_style = 'BlinkingBar'
config.cursor_blink_rate = 500

return config