Configuration Examples

Real-world WezTerm configuration examples and recipes for common use cases

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

Retro Style

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

Hyperlink Navigation

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'

Require Modifier for Hyperlink Clicks

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.