obsidian/wiki/dotfiles/wezterm-config.md

title	aliases	tags	sources	created	updated
WezTerm Configuration Guide	wezterm-lua-config wezterm-setup wezterm-config-files	wezterm terminal lua dotfiles config	raw/Configuration - Wez's Terminal Emulator.md	2026-04-17	2026-04-17

Overview

WezTerm is configured via a Lua script (wezterm.lua). The config system is live-reloading, highly flexible, and supports modular file splits.

Config File Locations

WezTerm searches for config in this priority order:

1. $HOME/.wezterm.lua — recommended starting point
2. $XDG_CONFIG_HOME/wezterm/wezterm.lua (X11/Wayland)
3. $HOME/.config/wezterm/wezterm.lua — all other systems
4. Same directory as wezterm.exe (Windows thumb drive mode — not recommended)

Quick Start

local wezterm = require 'wezterm'
local config = wezterm.config_builder()

config.initial_cols = 120
config.initial_rows = 28
config.font_size = 10
config.color_scheme = 'AdventureTime'

return config

• wezterm.config_builder() is the recommended way to build the config table — it provides better error messages than a plain {}.

Live Reload

• WezTerm watches the config file and reloads on change automatically
• Force reload: CTRL+SHIFT+R
• Warning: the config file can be evaluated multiple times per process (startup + each reload). Avoid side effects in the top-level flow (e.g., spawning background processes unconditionally).

CLI Config Overrides

Override any config key from the command line — these always win over file values, even after reload:

wezterm --config enable_scroll_bar=true
wezterm --config 'exit_behavior="Hold"'

Per-window overrides are possible via window:set_config_overrides() in Lua.

Modular Config (Multiple Files)

Break config into Lua modules. package.path includes (in order):

• ~/.config/wezterm/
• ~/.wezterm/
• System Lua paths

~/.config/wezterm/helpers.lua:

local wezterm = require 'wezterm'
local module = {}

function module.apply_to_config(config)
  config.color_scheme = 'Batman'
end

return module

~/.config/wezterm/wezterm.lua:

local helpers = require 'helpers'
local config = {}
helpers.apply_to_config(config)
return config

Convention: modules export an apply_to_config(config) function that mutates the config table in place.

Key Takeaways

• Config file is Lua — use full language features (functions, modules, conditionals)
• Use wezterm.config_builder() over raw {} for better error output
• Default config location: ~/.wezterm.lua or ~/.config/wezterm/wezterm.lua
• Auto-reloads on file change; CTRL+SHIFT+R for manual reload
• CLI --config key=value overrides always beat file values
• Split large configs into modules under ~/.config/wezterm/ using require
• Avoid side effects at the top level — config is evaluated multiple times

Related

• wiki/dotfiles/wezterm-colors-appearance — color schemes, tab bar, opacity
• wiki/dotfiles/wezterm-cli-reference — CLI subcommands and scripting
• wiki/dotfiles/terminal-cheatsheet — daily WezTerm + Fish stack reference
• wiki/dotfiles/linux-terminal-ricing — full setup guide with themes

Sources

• raw/Configuration - Wez's Terminal Emulator.md (clipped from wezterm.org/config/files.html)