Appearance Configuration

Color Schemes

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

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
Random Color Scheme

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

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:

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)
Retro

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',
}

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
Windows 11
KDE (Linux)

-- Background blur effect
config.macos_window_background_blur = 30

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

config.win32_acrylic_accent_color = '#2b2042'

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

Source

Define the image source:

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

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

Positioning

Align the layer:

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

Repetition

Control tiling:

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

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:

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

Get Started

Core Concepts

Features

Configuration

Guides

Appearance Configuration

Color Schemes

Applying a Color Scheme

Dynamic Color Scheme Selection

Custom Colors

Color Formats

Precedence: colors vs color_scheme

Custom Color Schemes

Tab Bar Appearance

Tab Bar Styles

Retro Tab Bar Colors

Tab Bar Position and Visibility

Window Transparency

Background Opacity

Text Background Opacity

Platform-Specific Effects

Background Images

Simple Background Image

Advanced Multi-Layer Backgrounds

Background Layer Options

Background Gradients

Window Padding

Pane Styling

Inactive Pane Dimming

Pane Borders

Window Decorations

Integrated Title Buttons

Cursor Appearance

Complete Appearance Example

Get Started

Core Concepts

Features

Configuration

Guides

​Color Schemes

​Applying a Color Scheme

​Dynamic Color Scheme Selection

​Custom Colors

​Color Formats

​Precedence: colors vs color_scheme

​Custom Color Schemes

​Tab Bar Appearance

​Tab Bar Styles

​Retro Tab Bar Colors

​Tab Bar Position and Visibility

​Window Transparency

​Background Opacity

​Text Background Opacity

​Platform-Specific Effects

​Background Images

​Simple Background Image

​Advanced Multi-Layer Backgrounds

​Background Layer Options

​Background Gradients

​Window Padding

​Pane Styling

​Inactive Pane Dimming

​Pane Borders

​Window Decorations

​Integrated Title Buttons

​Cursor Appearance

​Complete Appearance Example

Color Schemes

Applying a Color Scheme

Dynamic Color Scheme Selection

Custom Colors

Color Formats

Precedence: colors vs color_scheme

Custom Color Schemes

Tab Bar Appearance

Tab Bar Styles

Retro Tab Bar Colors

Tab Bar Position and Visibility

Window Transparency

Background Opacity

Text Background Opacity

Platform-Specific Effects

Background Images

Simple Background Image

Advanced Multi-Layer Backgrounds

Background Layer Options

Background Gradients

Window Padding

Pane Styling

Inactive Pane Dimming

Pane Borders

Window Decorations

Integrated Title Buttons

Cursor Appearance

Complete Appearance Example