Where Is the WezTerm Config File?
WezTerm config file candidates on every OS, and the override that beats all of them.
Last updated
WezTerm uses a single Lua file, and the recommended home is ~/.wezterm.lua on macOS and Linux (%USERPROFILE%\.wezterm.lua on Windows). If you prefer a multi file setup, ~/.config/wezterm/wezterm.lua works on every OS instead.
Two overrides beat both defaults: the $WEZTERM_CONFIG_FILE variable and the --config-file flag, handy for dotfiles or a thumb drive install. Note the failure mode changed years ago. On a parse error, current builds show the error and fall back to built in defaults instead of trying the next candidate path.
Where WezTerm stores this, by platform
%USERPROFILE%\.wezterm.lua
Recommended single file spot. The multi file alternative is %USERPROFILE%\.config\wezterm\wezterm.lua. $WEZTERM_CONFIG_FILE and --config-file beat both. A wezterm.lua next to wezterm.exe enables thumb drive mode.
~/.wezterm.lua
Recommended single file spot. The multi file alternative is ~/.config/wezterm/wezterm.lua (wezterm.config_dir points at whichever directory won). Overrides via $WEZTERM_CONFIG_FILE and --config-file.
~/.wezterm.lua
Recommended single file spot. The multi file alternative is ~/.config/wezterm/wezterm.lua ($XDG_CONFIG_HOME respected). Overrides via $WEZTERM_CONFIG_FILE and --config-file.
Frequently asked questions
WezTerm ignores my config edit. What is wrong?
First check for a Lua parse error: current builds show the error and silently use built in defaults instead of falling through to another path. Also confirm no $WEZTERM_CONFIG_FILE or --config-file override is pointing elsewhere.
Can I keep my WezTerm config in a dotfiles repo?
Yes. Either symlink the repo file to ~/.wezterm.lua (or ~/.config/wezterm/wezterm.lua), or point $WEZTERM_CONFIG_FILE at the checkout. The env var approach keeps the repo layout untouched.
Notice an outdated path? Let us know.