3 +description: WezTerm terminal emulator configuration — Lua config, panes, tabs, multiplexer (SSH/WSL domains), key bindings, CLI, and appearance. Use when configuring WezTerm, writing ~/.wezterm.lua, building key bindings, using mux workspaces, or automating the CLI.
8 +WezTerm is a Rust-based GPU-accelerated terminal emulator with a built-in
9 +multiplexer, cross-platform (Linux/macOS/Windows/FreeBSD/NetBSD). Configuration
10 +uses **Lua 5.4** in `~/.wezterm.lua` or `~/.config/wezterm/wezterm.lua`.
12 +**Config file discovery order:** CLI `--config-file` > `$WEZTERM_CONFIG_FILE` >
13 +Windows exe dir > `$XDG_CONFIG_HOME/wezterm/wezterm.lua` >
14 +`~/.config/wezterm/wezterm.lua` > `~/.wezterm.lua`
16 +**Auto-reload:** enabled by default (`automatically_reload_config = true`).
17 +Changes take effect without restart.
22 +local wezterm = require 'wezterm'
23 +local config = wezterm.config_builder()
25 +config.font = wezterm.font 'JetBrains Mono'
26 +config.font_size = 11
27 +config.color_scheme = 'nord'
28 +config.enable_tab_bar = false
33 +##
Config File Location 36 +| -------- | -------------------------------------------------- |
37 +| 1 | `--config-file` CLI argument |
38 +| 2 | `$WEZTERM_CONFIG_FILE` env var |
39 +| 3 | Windows: exe directory (portable/thumb drive mode) |
40 +| 4 | `$XDG_CONFIG_HOME/wezterm/wezterm.lua` |
41 +| 5 | `~/.config/wezterm/wezterm.lua` |
42 +| 6 | `~/.wezterm.lua` |
44 +**Key config options:**
47 +config.automatically_reload_config = true -- default
48 +config.config_file = 'path/to/wezterm.lua' -- explicit path
51 +##
Colors & Appearance 54 +-- Use a built-in color scheme
55 +config.color_scheme = 'nord' -- see wezterm.color.get_builtin_schemes()
57 +-- Fully custom colors
59 + foreground = '#cccccc',
60 + background = '#1e1e1e',
61 + cursor_bg = '#ffffff',
62 + cursor_border = '#ffffff',
63 + cursor_fg = '#1e1e1e',
64 + selection_bg = '#264f78',
65 + tab_bar = { background = '#0d1117', active_tab = { bg_color = '#161b22', fg_color = '#cccccc' } },
66 + ansi = { '#484848', '#cc4444', '#44cc44', '#cccc44', '#4444cc', '#cc44cc', '#44cccc', '#cccccc' },
67 + brightness = { '#303030', '#e06060', '#60e060', '#e0e060', '#6060e0', '#e060e0', '#60e0e0', '#e0e0e0' },
71 +**Background layers** (multiple can be combined):
74 +-- Solid background color
75 +config.background = { { source = 'solid_color', color = '#0d1117' } }
78 +config.background = {
79 + { source = 'linear_gradient', orientation = 'Vertical', colors = { '#0d1117', '#161b22' } },
83 +config.background = {
84 + { source = 'radial_gradient', anchor = 'bottom', colors = { '#0d1117', '#161b22' } },
88 +config.background = {
89 + { source = 'image', path = '/path/to/image.png', hscan = 'Flip', vscan = 'Tile' },
90 + { source = 'solid_color', color = '#0d1117', alpha = 0.7 }, -- overlay
97 +config.window_decorations = 'RESIZE' -- 'RESIZE' | 'MACOS_BORDERLESS' | 'NONE' | 'ALWAYS_FORCE_OPAQUE'
98 +config.window_background_opacity = 0.95
99 +config.window_padding = { left = 8, right = 8, top = 0, bottom = 0 }
100 +config.hide_tab_bar_if_only_one_tab = true
101 +config.use_fancy_tab_bar = false
102 +config.tab_bar_at_bottom = false
109 +config.font = wezterm.font 'JetBrains Mono'
111 +-- With fallback chain
112 +config.font = wezterm.font_with_fallback { 'JetBrains Mono', 'Fira Code', 'Noto Sans' }
114 +-- Font with size and line height
115 +config.font_size = 12
116 +config.line_height = 1.2
117 +config.font_rules = {
118 + { italic = true, font = wezterm.font('JetBrains Mono', { italic = true }) },
119 + { weight = 'Bold', font = wezterm.font('JetBrains Mono', { weight = 'Bold' }) },
123 +**Harfbuzz shaping features:**
126 +config.font_rules = {
128 + intensity = 'Bold',
129 + font = wezterm.font('JetBrains Mono', { weight = 'Bold' }),
133 + font = wezterm.font('JetBrains Mono', { italic = true }),
142 + -- Basic keybinding
143 + { key = 't', mods = 'CTRL|SHIFT', action = wezterm.action.SpawnTab 'CurrentPaneDomain' },
145 + -- With multiple modifiers
146 + { key = 'Enter', mods = 'ALT', action = wezterm.action.ToggleFullScreen },
148 + -- Send string (type text)
149 + { key = 'w', mods = 'CTRL|SHIFT', action = wezterm.action.SpawnWindow },
151 + -- Encode special keys
152 + { key = 'LeftArrow', mods = 'ALT', action = wezterm.action.EmitEvent 'noop' },
155 +config.leader = { key = 'a', mods = 'CTRL' } -- chord: Ctrl-a then key
158 +**Modifier names:** `CTRL`, `SHIFT`, `ALT`, `SUPER` (macOS Cmd), `CMD`, `META`,
161 +**Key names:** single chars, `Enter`, `Escape`, `Space`, `Backspace`, `Tab`,
162 +`F1`–`F12`, `LeftArrow`, `RightArrow`, `UpArrow`, `DownArrow`, `Home`, `End`,
163 +`PageUp`, `PageDown`, `Insert`, `Delete`
165 +**Key tables** for mode switching:
168 +config.key_tables = {
170 + { key = 'Escape', mods = 'NONE', action = wezterm.action.ActivateCopyMode 'Prev' },
171 + { key = 'q', mods = 'NONE', action = wezterm.action.ActivateCopyMode 'Close' },
172 + { key = 'g', mods = 'NONE', action = 'ScrollByPage', args = { -1 } },
173 + { key = 'G', mods = 'SHIFT', action = 'ScrollToBottom' },
174 + { key = 'j', mods = 'NONE', action = 'ScrollByLine', args = { 1 } },
175 + { key = 'k', mods = 'NONE', action = 'ScrollByLine', args = { -1 } },
176 + { key = 'v', mods = 'NONE', action = wezterm.action.CopyMode 'Select' },
177 + { key = 'V', mods = 'SHIFT', action = wezterm.action.CopyMode 'SelectLine' },
178 + { key = 'y', mods = 'NONE', action = wezterm.action.CopyTo 'Clipboard' },
179 + { key = '/', mods = 'NONE', action = wezterm.action.Search { Regex = '', mode = 'CopyMode' } },
184 +##
Key Actions Reference 189 +wezterm.action.SplitHorizontal { domain = 'CurrentPaneDomain' }
190 +wezterm.action.SplitVertical { domain = 'CurrentPaneDomain' }
191 +wezterm.action.SplitPane { program = '/bin/bash', cwd = '/home', domain = 'CurrentPaneDomain' }
192 +wezterm.action.CloseCurrentPane { confirm = true }
193 +wezterm.action.AdjustPaneSize { direction = 'Down', amount = 3 }
194 +wezterm.action.TogglePaneZoomState
195 +wezterm.action.PaneSelect { mode = 'Swap' } -- 'Activate' | 'Swap' | 'ForceSelected' | 'Reset'
201 +wezterm.action.SpawnTab 'CurrentPaneDomain'
202 +wezterm.action.SpawnTab { domain = 'CurrentPaneDomain', program = '/bin/bash', cwd = '/home' }
203 +wezterm.action.CloseCurrentTab { confirm = true }
204 +wezterm.action.ActivateTab 2
205 +wezterm.action.MoveTab 3
206 +wezterm.action.ShowTabNavigator
209 +###
Window Operations 212 +wezterm.action.SpawnWindow
213 +wezterm.action.ActivateWindow 0
214 +wezterm.action.SwitchToWorkspace { name = 'main', spawn = { 'wezterm', 'start' } }
215 +wezterm.action.ToggleFullScreen
216 +wezterm.action.Maximize
222 +wezterm.action.ActivatePaneDirection 'Down'
223 +wezterm.action.ActivatePaneDirection 'Left'
224 +wezterm.action.ActivatePaneDirection 'Right'
225 +wezterm.action.ActivatePaneDirection 'Up'
226 +wezterm.action.ActivatePaneByIndex 0 -- 0-indexed
227 +wezterm.action.PaneSelect -- interactive
228 +wezterm.action.PaneSelect { mode = 'Activate' }
234 +wezterm.action.SendString 'hello'
235 +wezterm.action.SendKey { key = 'Enter' }
236 +wezterm.action.Paste 'Clipboard'
237 +wezterm.action.CompleteSelection 'Clipboard'
238 +wezterm.action.CopyTo 'Clipboard'
244 +wezterm.action.ActivateCopyMode 'CopyMode'
245 +wezterm.action.CopyMode { preset = 'vim' } -- vim or emacs
246 +wezterm.action.ScrollByPage -1
247 +wezterm.action.ScrollByLine 5
248 +wezterm.action.Search { Regex = 'pattern', mode = 'CopyMode' }
249 +wezterm.action.QuickSelect
255 +wezterm.action.ShowLauncher { titles = {}, cli_labels = {} }
256 +wezterm.action.ShowDebugOverlay
257 +wezterm.action.PromptInputLine {
258 + description = 'Enter command',
259 + action = wezterm.action_callback(function(window, pane, line)
260 + if line then window:perform_action(wezterm.action.SendString(line), pane) end
263 +wezterm.action.InputSelector {
264 + description = 'Select option',
265 + choices = { { label = 'opt1', id = '1' } },
266 + action = wezterm.action_callback(function(window, pane, id, label) end),
270 +###
Multiple / Chaining 273 +wezterm.action.Multiple {
274 + wezterm.action.SplitHorizontal { domain = 'CurrentPaneDomain' },
275 + wezterm.action.ActivatePaneDirection 'Right',
282 +wezterm.action.EmitEvent 'my-event-name'
283 +wezterm.action.ReloadConfiguration
284 +wezterm.action.QuitApplication
285 +wezterm.action.CharSelect { copy_on_select = true, }
293 +wezterm.action(action_obj) -- perform an action
294 +wezterm.action_callback(fn) -- callback(fn(window, pane, ...)) -> action
295 +wezterm.config_builder() -- returns config table
296 +wezterm.default_hyperlink_rules() -- returns hyperlink rules
297 +wezterm.font(name, opts) -- font with optional weight/italic/slant
298 +wezterm.font_with_fallback({'Font1', 'Font2'})
299 +wezterm.format({ { Foreground = { Color = 'red' }, Text = 'hello' } })
300 +wezterm.glob(pattern) -- glob expansion
301 +wezterm.json_encode(val) -- JSON string
302 +wezterm.json_parse(str) -- parse JSON
303 +wezterm.log_error(msg)
304 +wezterm.log_info(msg)
305 +wezterm.log_warn(msg)
306 +wezterm.nerdfonts -- table of icon names
307 +wezterm.now() -- Unix timestamp
308 +wezterm.on('event', fn) -- register event handler
309 +wezterm.read_dir(dir) -- list directory entries
310 +wezterm.reload_configuration()
311 +wezterm.run_child_process(cmd) -- returns { stdout, stderr, exit_code }
312 +wezterm.sleep_ms(ms)
313 +wezterm.strftime(fmt, ts) -- format timestamp
316 +**Programmatic config reload:**
319 +wezterm.on('window-config-reloaded', function(window)
320 + wezterm.log_info('config reloaded for ' .. window:panel():get_title())
327 +wezterm.color.parse('#ff0000') -- returns { r=1, g=0, b=0, a=1 }
328 +wezterm.color.from_hsla(180, 0.5, 0.5, 1.0) -- returns Color
329 +wezterm.color.gradient({'#red', 'blue'}, 'horizontal', 10) -- interpolate colors
330 +wezterm.color.get_builtin_schemes() -- list all built-in schemes
331 +wezterm.color.load_scheme('nord') -- load scheme as color table
332 +wezterm.color.extract_colors_from_image('/path/to/image.png') -- extract palette
338 +wezterm.gui.get_appearance() -- 'Dark' | 'Light' | 'Unknown'
339 +wezterm.gui.screens() -- list screens: { { width, height, xscale, yscale, name } }
340 +wezterm.gui.enumerate_gpus() -- list available GPUs
341 +wezterm.gui.default_keys() -- default keybindings as table
342 +wezterm.gui.default_key_tables() -- default key tables (copy mode, etc.)
343 +wezterm.gui.gui_windows() -- all GUI windows
346 +**Dark/light mode switching:**
349 +wezterm.on('update-status', function(window, pane)
350 + local appearance = wezterm.gui.get_appearance()
351 + local scheme = appearance == 'Dark' and 'nord' or 'nord-light'
352 + window:configure_actions({
353 + { SetColorScheme = scheme },
361 +wezterm.mux.spawn_window({ domain = 'local', workspace = 'main', cwd = '/home' })
362 +wezterm.mux.get_active_workspace() -- current workspace name
363 +wezterm.mux.all_windows() -- all mux windows
364 +wezterm.mux.rename_workspace(old_name, new_name)
365 +wezterm.mux.set_active_workspace(name)
368 +**Window/Pane objects:**
371 +window:gui_window() -- GuiWindow
372 +window:mux_window() -- MuxWindow
373 +pane:split({ program = '/bin/bash', domain = 'CurrentPaneDomain' })
374 +pane:send_text('text\n')
377 +pane:get_current_working_dir() -- returns Path or nil
378 +pane:get_foreground_process_info() -- returns ProcessInfo { pid, name, cwd }
379 +pane:get_text_from_region(0, 0, 100, 200) -- get text rectangle
380 +pane:inject_output('text\n')
386 +wezterm.plugin.require('github.com/path/to/plugin') -- load plugin
387 +wezterm.plugin.list() -- list loaded plugins
388 +wezterm.plugin.update_all() -- update all plugins
393 +| Event | Callback |
394 +| ------------------------ | ------------------------------------- |
395 +| `gui-startup` | `fn(window)` |
396 +| `gui-attached` | `fn(window)` |
397 +| `mux-startup` | `fn()` |
398 +| `format-tab-title` | `fn(tab, tabs, panes, config, hover)` |
399 +| `format-window-title` | `fn(window)` |
400 +| `update-status` | `fn(window, pane)` |
401 +| `update-right-status` | `fn(window, pane)` |
402 +| `window-config-reloaded` | `fn(window)` |
403 +| `window-focus-changed` | `fn(window, bool)` |
404 +| `window-resized` | `fn(window, size)` |
405 +| `bell` | `fn(window, pane)` |
406 +| `open-uri` | `fn(uri, action)` |
407 +| `user-var-changed` | `fn(pane, name, value)` |
409 +**Example — dynamic tab titles:**
412 +wezterm.on('format-tab-title', function(tab, tabs, panes, config, hover)
413 + return tab.tab_index + 1 .. ': ' .. tab.active_pane.title
417 +**Example — status line:**
420 +wezterm.on('update-right-status', function(window, pane)
421 + window:set_right_status(wezterm.format {
422 + { Text = wezterm.strftime('%H:%M:%S') },
427 +##
Multiplexing & Domains 430 +config.unix_domains = { { name = 'unix', socket_dir = '/tmp/wezterm' } }
431 +config.ssh_domains = {
433 + name = 'prod-server',
434 + host = 'example.com',
437 + -- or use SSH config: remote_addr = 'example.com'
438 + ssh_option = 'value',
441 +config.wsl_domains = { { name = 'WSL:Ubuntu', distribution = 'Ubuntu' } }
442 +config.tls_domains = { { name = 'tls-server', host = 'example.com', port = 443 } }
445 +**Spawning in domains:**
448 +{ key = 'c', mods = 'CTRL|SHIFT', action = wezterm.action.SpawnCommandInDomain { domain = 'unix', program = '/bin/bash' } }
456 +wezterm start --config-file ~/.wezterm.lua
457 +wezterm start --prefix-search
'ssh' 460 +wezterm ssh user@host
461 +wezterm ssh user@host --domian-name prod
464 +wezterm connect domain-name
467 +wezterm cli split-pane --right
-- /bin/bash
468 +wezterm cli split-pane --down --weight 0.3
-- bash -c
'top' 470 +wezterm cli activate-pane-direction Left
471 +wezterm cli activate-pane 2
472 +wezterm cli zoom-pane
475 +wezterm cli send-text --pane-id 1
"echo hello\n" 478 +wezterm cli get-text --pane-id 1 --start-cell 0,0 --end-cell 100,50
481 +wezterm cli set-tab-title --pane-id 1
"My Tab" 482 +wezterm cli set-window-title --window-id 0
"My Window" 483 +wezterm cli rename-workspace --name main
486 +wezterm cli list --format json
489 +wezterm show-keys --help
491 +wezterm imgcat /path/to/image.png
492 +wezterm serial /dev/ttyUSB0 115200
493 +wezterm record --label
"session" 494 +wezterm replay /path/to/recording
497 +**CLI flags for `wezterm start`:**
500 +wezterm start --config-file FILE
501 +wezterm start --cwd DIR
502 +wezterm start --position X,Y
503 +wezterm start --size WIDTH,HEIGHT
504 +wezterm start --domain SOCKET_DIR
505 +wezterm start --workspace NAME
510 +**Dark/light mode colors:**
513 +local function get_colors()
514 + local appearance = wezterm.gui.get_appearance()
515 + local scheme = appearance == 'Dark' and 'nord' or 'nord-bright'
516 + return wezterm.color.load_scheme(scheme)
519 +wezterm.on('update-status', function(window, pane)
520 + local colors = get_colors()
521 + pane:set_config_overrides {
522 + colors = { foreground = colors.foreground, background = colors.background },
527 +**Gradient background with overlay:**
530 +config.background = {
531 + { source = 'linear_gradient', orientation = 'Vertical', colors = { '#0d1117', '#161b22' } },
532 + { source = 'solid_color', color = '#000000', width = '100%', opacity = 0.3, fill = 'Gradient' },
536 +**Workspace-aware status:**
539 +wezterm.on('format-window-title', function(window)
540 + local workspace = wezterm.mux.get_active_workspace()
541 + return workspace .. ' — ' .. window:gui_window().title
545 +**Conditional action with callback:**
548 +wezterm.on('update-status', function(window, pane)
549 + local has_jobs = #pane:get_foreground_process_info() > 0
550 + window:perform_action(
551 + has_jobs and wezterm.action.ShowTabNavigator()
552 + or wezterm.action_callback(function() end),
561 +| --------------------- | --------------------------------------------- |
562 +| Main docs | https://wezterm.org/ |
563 +| Config overview | https://wezterm.org/config/ |
564 +| Lua config options | https://wezterm.org/config/lua/config/ |
565 +| Lua API reference | https://wezterm.org/config/lua/wezterm/ |
566 +| Color module | https://wezterm.org/config/lua/wezterm.color/ |
567 +| GUI module | https://wezterm.org/config/lua/wezterm.gui/ |
568 +| Mux module | https://wezterm.org/config/lua/wezterm.mux/ |
569 +| KeyAssignment actions | https://wezterm.org/config/lua/keyassignment/ |
570 +| Window events | https://wezterm.org/config/lua/window-events/ |
571 +| GUI events | https://wezterm.org/config/lua/gui-events/ |
572 +| CLI reference | https://wezterm.org/cli/cli/ |
573 +| Key binding config | https://wezterm.org/config/keys.html |
574 +| Key tables | https://wezterm.org/config/key-tables.html |
575 +| Default keys | https://wezterm.org/config/default-keys.html |
576 +| Launching programs | https://wezterm.org/config/launch.html |
577 +| Plugin system | https://wezterm.org/config/plugins.html |
578 +| Mouse bindings | https://wezterm.org/config/mouse.html |
579 +| Color schemes | https://wezterm.org/config/colors.html |