Configuration Files

Learn about WezTerm’s configuration file structure, locations, and how to organize your configuration

Quick Start

Create a file named .wezterm.lua in your home directory with the following contents:

-- Pull in the wezterm API
local wezterm = require 'wezterm'

-- This will hold the configuration.
local config = wezterm.config_builder()

-- This is where you actually apply your config choices.

-- For example, changing the initial geometry for new windows:
config.initial_cols = 120
config.initial_rows = 28

-- or, changing the font size and color scheme.
config.font_size = 10
config.color_scheme = 'AdventureTime'

-- Finally, return the configuration to wezterm:
return config

Configuration File Locations

WezTerm searches for your configuration file in the following order:

1. Command Line Argument

   Use the --config-file CLI argument to specify a custom location:

   wezterm --config-file /path/to/config.lua
   
2. Environment Variable

   Set the WEZTERM_CONFIG_FILE environment variable:

   export WEZTERM_CONFIG_FILE="$HOME/my-configs/wezterm.lua"
   
3. Windows Portable Mode

   On Windows, WezTerm checks if wezterm.lua exists in the same directory as wezterm.exe (useful for running from a USB drive).

4. XDG Config Directory

   If $XDG_CONFIG_HOME is set:

   $XDG_CONFIG_HOME/wezterm/wezterm.lua
   
5. Standard Config Directory

   Platform-specific standard locations:

   Linux/macOS

   ~/.config/wezterm/wezterm.lua
   

   Windows

   %USERPROFILE%\.config\wezterm\wezterm.lua
   
6. Home Directory (Recommended)

   The simplest option for single-file configurations:

   Linux/macOS

   ~/.wezterm.lua
   

   Windows

   %USERPROFILE%\.wezterm.lua
   

For simple configurations, use $HOME/.wezterm.lua. For complex multi-file setups, use ~/.config/wezterm/wezterm.lua.

Configuration File Structure

The configuration file is a Lua script that must return a configuration table:

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

-- Your configuration goes here
config.color_scheme = 'Batman'
config.font = wezterm.font 'JetBrains Mono'

return config

Using config_builder()

The wezterm.config_builder() function creates a configuration object with built-in validation:

Basic Example

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

config.font_size = 12
config.color_scheme = 'Dracula'

return config

-- Alternative (less recommended)
local wezterm = require 'wezterm'
local config = {}

config.font_size = 12
config.color_scheme = 'Dracula'

return config

Configuration Reloading

WezTerm automatically watches your configuration file for changes:

• Changes take effect immediately for most options
• Use CTRL+SHIFT+R to manually reload the configuration
• Some options (like domain configurations) may require restart

Your configuration file may be evaluated multiple times. Avoid side effects like unconditionally spawning background processes or writing to files in the main configuration flow.

Command Line Overrides

You can override configuration values via command line arguments:

# Override a single value
wezterm --config enable_scroll_bar=true

# Override with string values
wezterm --config 'exit_behavior="Hold"'

# Multiple overrides
wezterm --config font_size=14 --config 'color_scheme="Dracula"'

Command line overrides persist even after configuration reloads.

Multi-File Configurations

For complex configurations, organize your config across multiple files:

Module Path Configuration

Lua’s package.path is pre-configured with these directories:

• ~/.config/wezterm/
• ~/.wezterm/
• System-specific Lua module paths

Creating Modules

Create a helper module at ~/.config/wezterm/helpers.lua:

helpers.lua

local wezterm = require 'wezterm'

-- Module table
local module = {}

-- Private function
local function private_helper()
  wezterm.log_info 'Configuring appearance'
end

-- Public function
function module.apply_to_config(config)
  private_helper()
  
  config.color_scheme = 'Batman'
  config.font_size = 12
end

return module

Use the module in ~/.config/wezterm/wezterm.lua:

wezterm.lua

local wezterm = require 'wezterm'
local helpers = require 'helpers'

local config = wezterm.config_builder()

-- Apply helper configuration
helpers.apply_to_config(config)

-- Add more configuration
config.enable_tab_bar = true

return config

Example Multi-File Structure

Directory Structure

~/.config/wezterm/
├── wezterm.lua          # Main config file
├── appearance.lua       # Colors and themes
├── keys.lua            # Keyboard shortcuts
├── domains.lua         # SSH and multiplexer domains
└── utils.lua           # Helper functions

-- ~/.config/wezterm/wezterm.lua
local wezterm = require 'wezterm'
local appearance = require 'appearance'
local keys = require 'keys'
local domains = require 'domains'

local config = wezterm.config_builder()

appearance.apply_to_config(config)
keys.apply_to_config(config)
domains.apply_to_config(config)

return config

-- ~/.config/wezterm/appearance.lua
local wezterm = require 'wezterm'
local module = {}

function module.apply_to_config(config)
  config.color_scheme = 'Dracula'
  config.font = wezterm.font 'JetBrains Mono'
  config.font_size = 12
  config.window_background_opacity = 0.95
end

return module

Per-Window Configuration Overrides

You can set window-specific overrides dynamically:

local wezterm = require 'wezterm'

wezterm.on('update-status', function(window, pane)
  local overrides = window:get_config_overrides() or {}
  
  -- Dim inactive windows
  if window:is_focused() then
    overrides.window_background_opacity = 1.0
  else
    overrides.window_background_opacity = 0.8
  end
  
  window:set_config_overrides(overrides)
end)

local config = wezterm.config_builder()
return config

Configuration Validation

WezTerm validates your configuration on load:

If your configuration file has syntax errors or fails to load, WezTerm will display an error and use default settings.

To test your configuration:

# Check for syntax errors
wezterm start --config-file ~/.wezterm.lua

# View configuration in effect
wezterm show-keys

Best Practices

1. Use config_builder()

   Always use wezterm.config_builder() for better error messages and validation.

2. Avoid Side Effects

   Don’t spawn processes or write files in the main configuration flow. Use event handlers instead.

3. Comment Your Config

   Add comments explaining non-obvious configuration choices.

4. Version Control

   Keep your configuration in version control (git) for easy backups and history.

5. Start Simple

   Begin with a minimal configuration and add features as needed.

Troubleshooting

Configuration Not Loading

1. Check file location:

   wezterm --version
   # Look for "Config file: /path/to/config.lua" in output
   

2. Verify Lua syntax:

   lua -c ~/.wezterm.lua
   

3. Check WezTerm logs:

   • Press CTRL+SHIFT+L to open the debug overlay
   • Look for error messages

Changes Not Taking Effect

• Manually reload: CTRL+SHIFT+R
• Some options require restart
• Check for command-line overrides that may conflict

Module Not Found

If require 'mymodule' fails:

1. Verify file is named mymodule.lua
2. Place in ~/.config/wezterm/ or ~/.wezterm/
3. Check file permissions
4. Verify no syntax errors in the module file