> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/wezterm/wezterm/llms.txt
> Use this file to discover all available pages before exploring further.

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

```lua theme={null}
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:

```lua theme={null}
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
```

<Tip>
  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.
</Tip>

### Bold and Italic Font Rules

Customize font selection for different text styles:

```lua theme={null}
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:

```lua theme={null}
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:

```lua theme={null}
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:

```lua theme={null}
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:

```lua theme={null}
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

<CodeGroup>
  ```lua Retro Style theme={null}
  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
  ```

  ```lua Fancy Tab Bar theme={null}
  local wezterm = require 'wezterm'
  local config = {}

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

  config.colors = {
    tab_bar = {
      inactive_tab_edge = '#575757',
    },
  }

  return config
  ```
</CodeGroup>

### Custom Tab Titles with User Variables

Display custom information in tab titles:

```lua theme={null}
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
```

<Note>
  This requires setting user variables from your shell. See the [Passing Data recipe](https://wezfurlong.org/wezterm/recipes/passing-data.html) for details on setting up user variables.
</Note>

## Key Bindings

### Leader Key Configuration

Set up tmux-style leader key bindings:

```lua theme={null}
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

```lua theme={null}
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

```lua theme={null}
local wezterm = require 'wezterm'
local config = {}

config.window_background_opacity = 0.9
config.text_background_opacity = 0.3

return config
```

<Warning>
  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.
</Warning>

### Background Image

```lua theme={null}
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:

```lua theme={null}
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:

```lua theme={null}
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
```

<Note>
  For this recipe to work best, configure your shell with hyperlink support:

  ```bash theme={null}
  alias ls='ls --hyperlink --color=auto'
  alias delta="delta --hyperlinks --hyperlinks-file-link-format='file://{path}#{line}'"
  alias rg='rg --hyperlink-format=kitty'
  ```
</Note>

### Require Modifier for Hyperlink Clicks

Prevent accidental hyperlink clicks:

```lua theme={null}
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:

```lua theme={null}
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

<Tip>
  Use `wezterm ls-fonts` to see which fonts are available on your system and how WezTerm will render them.
</Tip>

<Tip>
  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.
</Tip>

<Tip>
  Use `wezterm show-keys` or `wezterm show-keys --lua` to see all effective key bindings defined by your configuration.
</Tip>