Skip to main content
This page provides practical, ready-to-use configuration examples for WezTerm. Each example is designed to be copied directly into your ~/.wezterm.lua configuration file.

​
Basic Configuration

​
Minimal Setup

A simple starting configuration that sets up basic appearance and behavior: 
local wezterm = require 'wezterm'
local config = wezterm.config_builder()

-- Color scheme
config.color_scheme = 'Batman'

-- Font configuration
config.font = wezterm.font('JetBrains Mono', { weight = 'Bold' })
config.font_size = 12.0

-- Window appearance
config.window_background_opacity = 0.95
config.window_padding = {
  left = 10,
  right = 10,
  top = 10,
  bottom = 10,
}

return config

​
Font Configurations

​
Font with Fallback

Configure a primary font with fallback options for better glyph coverage: 
local wezterm = require 'wezterm'
local config = {}

config.font = wezterm.font_with_fallback {
  'Fira Code',
  'DengXian',  -- Better Chinese glyph coverage
  'Noto Color Emoji',
}

config.font_size = 11.0

return config
WezTerm automatically includes Nerd Font Symbols and Noto Color Emoji in the default fallback, so you don’t need specially patched fonts for powerline or Nerd Font symbols.

​
Bold and Italic Font Rules

Customize font selection for different text styles: 
local wezterm = require 'wezterm'
local config = {}

config.font = wezterm.font('JetBrains Mono')
config.font_rules = {
  {
    intensity = 'Bold',
    italic = true,
    font = wezterm.font({
      family = 'JetBrains Mono',
      weight = 'Bold',
      italic = true,
    }),
  },
  {
    intensity = 'Bold',
    font = wezterm.font({
      family = 'JetBrains Mono',
      weight = 'Bold',
    }),
  },
}

return config

​
Disable Ligatures

If you prefer to disable font ligatures: 
local wezterm = require 'wezterm'
local config = {}

config.font = wezterm.font('Fira Code')
config.harfbuzz_features = { 'calt=0', 'clig=0', 'liga=0' }

return config

​
Color Schemes

​
Custom Color Palette

Define your own color scheme: 
local wezterm = require 'wezterm'
local config = {}

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',
  ansi = {
    'black',
    'maroon',
    'green',
    'olive',
    'navy',
    'purple',
    'teal',
    'silver',
  },
  brights = {
    'grey',
    'red',
    'lime',
    'yellow',
    'blue',
    'fuchsia',
    'aqua',
    'white',
  },
}

return config

​
Multiple Color Schemes

Define multiple schemes and switch between them: 
local wezterm = require 'wezterm'
local config = {}

config.color_scheme = 'Red Scheme'

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

return config

​
Dark/Light Mode Auto-Switching

Automatically adjust colors based on system appearance: 
local wezterm = require 'wezterm'
local config = {}

function scheme_for_appearance(appearance)
  if appearance:find('Dark') then
    return 'Tokyo Night'
  else
    return 'Tokyo Night Day'
  end
end

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

return config

​
Tab Bar Customization

​
Retro Tab Bar

local wezterm = require 'wezterm'
local config = {}

config.use_fancy_tab_bar = false
config.tab_bar_at_bottom = true
config.hide_tab_bar_if_only_one_tab = 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,
    },
  },
}

return config

​
Custom Tab Titles with User Variables

Display custom information in tab titles: 
local wezterm = require 'wezterm'
local config = {}

wezterm.on('format-tab-title', function(tab)
  local prog = tab.active_pane.user_vars.PROG
  return tab.active_pane.title .. ' [' .. (prog or '') .. ']'
end)

return config
This requires setting user variables from your shell. See the Passing Data recipe for details on setting up user variables.

​
Key Bindings

​
Leader Key Configuration

Set up tmux-style leader key bindings: 
local wezterm = require 'wezterm'
local config = {}
local act = wezterm.action

config.leader = { key = 'a', mods = 'CTRL', timeout_milliseconds = 1000 }
config.keys = {
  -- Splitting panes
  {
    key = '|',
    mods = 'LEADER|SHIFT',
    action = act.SplitHorizontal { domain = 'CurrentPaneDomain' },
  },
  {
    key = '-',
    mods = 'LEADER',
    action = act.SplitVertical { domain = 'CurrentPaneDomain' },
  },
  -- Send CTRL-A to terminal when pressing CTRL-A twice
  {
    key = 'a',
    mods = 'LEADER|CTRL',
    action = act.SendKey { key = 'a', mods = 'CTRL' },
  },
}

return config

​
Disable Default Keybindings

local wezterm = require 'wezterm'
local config = {}

config.keys = {
  -- Turn off the default CMD-m Hide action
  {
    key = 'm',
    mods = 'CMD',
    action = wezterm.action.DisableDefaultAssignment,
  },
}

return config

​
Window Appearance

​
Transparent Background

local wezterm = require 'wezterm'
local config = {}

config.window_background_opacity = 0.9
config.text_background_opacity = 0.3

return config
Window transparency requires compositing support from your OS. macOS and Windows support this out of the box. On Linux, you may need to configure a compositing window manager.

​
Background Image

local wezterm = require 'wezterm'
local config = {}

config.window_background_image = '/path/to/wallpaper.jpg'
config.window_background_image_hsb = {
  brightness = 0.3,  -- Darken to 1/3rd brightness
  hue = 1.0,
  saturation = 1.0,
}

return config

​
Styled Inactive Panes

Make inactive panes visually distinct: 
local wezterm = require 'wezterm'
local config = {}

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

return config

​
Advanced Recipes

Click on file paths to navigate or open files: 
local wezterm = require 'wezterm'
local act = wezterm.action
local config = wezterm.config_builder()

local function is_shell(foreground_process_name)
  local shell_names = { 'bash', 'zsh', 'fish', 'sh', 'ksh', 'dash' }
  local process = string.match(foreground_process_name, '[^/\\]+$')
    or foreground_process_name
  for _, shell in ipairs(shell_names) do
    if process == shell then
      return true
    end
  end
  return false
end

wezterm.on('open-uri', function(window, pane, uri)
  local editor = 'nvim'

  if uri:find('^file:') == 1 and not pane:is_alt_screen_active() then
    local url = wezterm.url.parse(uri)
    if is_shell(pane:get_foreground_process_name()) then
      local success, stdout, _ = wezterm.run_child_process({
        'file',
        '--brief',
        '--mime-type',
        url.file_path,
      })
      if success then
        if stdout:find('directory') then
          pane:send_text(
            wezterm.shell_join_args({ 'cd', url.file_path }) .. '\r'
          )
          pane:send_text(wezterm.shell_join_args({
            'ls',
            '-a',
            '-p',
            '--group-directories-first',
          }) .. '\r')
          return false
        end

        if stdout:find('text') then
          if url.fragment then
            pane:send_text(wezterm.shell_join_args({
              editor,
              '+' .. url.fragment,
              url.file_path,
            }) .. '\r')
          else
            pane:send_text(
              wezterm.shell_join_args({ editor, url.file_path }) .. '\r'
            )
          end
          return false
        end
      end
    end
  end
end)

return config
For this recipe to work best, configure your shell with hyperlink support:
alias ls='ls --hyperlink --color=auto'
alias delta="delta --hyperlinks --hyperlinks-file-link-format='file://{path}#{line}'"
alias rg='rg --hyperlink-format=kitty'
Prevent accidental hyperlink clicks: 
local wezterm = require 'wezterm'
local config = {}
local act = wezterm.action

config.mouse_bindings = {
  {
    event = { Up = { streak = 1, button = 'Left' } },
    mods = 'CTRL',
    action = act.OpenLinkAtMouseCursor,
  },
  -- Disable the default click behavior
  {
    event = { Down = { streak = 1, button = 'Left' } },
    mods = 'CTRL',
    action = act.Nop,
  },
}

return config

​
Complete Example Configuration

A comprehensive configuration combining multiple features: 
local wezterm = require 'wezterm'
local config = wezterm.config_builder()
local act = wezterm.action

-- Appearance
config.color_scheme = 'Tokyo Night'
config.font = wezterm.font_with_fallback({
  'JetBrains Mono',
  'Noto Color Emoji',
})
config.font_size = 12.0

-- Window
config.window_background_opacity = 0.95
config.window_padding = {
  left = 5,
  right = 5,
  top = 5,
  bottom = 5,
}

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

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

-- Leader key
config.leader = { key = 'a', mods = 'CTRL', timeout_milliseconds = 1000 }

-- Key bindings
config.keys = {
  -- Pane splitting
  {
    key = '|',
    mods = 'LEADER|SHIFT',
    action = act.SplitHorizontal({ domain = 'CurrentPaneDomain' }),
  },
  {
    key = '-',
    mods = 'LEADER',
    action = act.SplitVertical({ domain = 'CurrentPaneDomain' }),
  },
  -- Pane navigation
  {
    key = 'h',
    mods = 'LEADER',
    action = act.ActivatePaneDirection('Left'),
  },
  {
    key = 'l',
    mods = 'LEADER',
    action = act.ActivatePaneDirection('Right'),
  },
  {
    key = 'k',
    mods = 'LEADER',
    action = act.ActivatePaneDirection('Up'),
  },
  {
    key = 'j',
    mods = 'LEADER',
    action = act.ActivatePaneDirection('Down'),
  },
  -- Send CTRL-A to terminal
  {
    key = 'a',
    mods = 'LEADER|CTRL',
    action = act.SendKey({ key = 'a', mods = 'CTRL' }),
  },
}

return config

​
Tips for Configuration

Use wezterm ls-fonts to see which fonts are available on your system and how WezTerm will render them.
Enable debug_key_events = true in your config to see what key codes are being generated when you press keys. This is helpful for troubleshooting key bindings.
Use wezterm show-keys or wezterm show-keys --lua to see all effective key bindings defined by your configuration.

Build docs developers (and LLMs) love

Get started for freeTalk to us