Skip to main content

​
Lua Configuration Overview

WezTerm uses Lua for configuration, providing a powerful and flexible way to customize every aspect of your terminal emulator. This guide covers the fundamentals of WezTerm’s Lua configuration system.

​
Configuration File Location

WezTerm looks for a configuration file at:
  • Unix/Linux/macOS: ~/.config/wezterm/wezterm.lua or ~/.wezterm.lua
  • Windows: %USERPROFILE%\.config\wezterm\wezterm.lua or %USERPROFILE%\.wezterm.lua

​
Basic Configuration Structure

A minimal WezTerm configuration file follows this structure: 
-- 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
config.font_size = 12.0
config.color_scheme = 'Batman'

-- and finally, return the configuration to wezterm
return config
Using wezterm.config_builder() provides better error messages and validation compared to using a plain Lua table.

​
The Config Object

The configuration is represented as a Lua table that gets converted into WezTerm’s internal Config struct. You can set any configuration option as a field on this table.

​
Common Configuration Patterns

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

-- Font configuration
config.font = wezterm.font 'JetBrains Mono'
config.font_size = 13.0

-- Color scheme
config.color_scheme = 'Dracula'

-- Window configuration
config.initial_cols = 120
config.initial_rows = 30

return config

​
Configuration Categories

WezTerm configuration options are organized into several categories:

​
Appearance & Colors

  • Color Schemes: Pre-built color themes for your terminal
  • Custom Colors: Define your own color palettes
  • Tab Bar: Customize tab appearance and behavior
  • Window Frame: Configure window decorations and title bar

​
Fonts

  • Font Selection: Choose primary and fallback fonts
  • Font Sizing: Configure size, line height, and cell width
  • Font Rules: Apply different fonts based on text attributes (bold, italic)
  • Font Rendering: Control anti-aliasing, hinting, and other rendering options

​
Window & Panes

  • Window Size: Set initial dimensions
  • Padding: Control spacing around terminal content
  • Decorations: Configure title bars and window chrome
  • Background: Set background colors, images, or gradients

​
Key Bindings

  • Key Assignments: Map keys to actions
  • Key Tables: Create modal key binding sets
  • Leader Key: Configure Tmux-style leader key patterns
  • Mouse Bindings: Customize mouse button actions

​
Domains & Multiplexing

  • SSH Domains: Connect to remote systems
  • Unix Domains: Local multiplexing
  • WSL Domains: Windows Subsystem for Linux integration

​
Using the WezTerm API

WezTerm provides a rich API through the wezterm module: 
local wezterm = require 'wezterm'

-- Font functions
local font = wezterm.font('JetBrains Mono', { weight = 'Bold' })
local font_with_fallback = wezterm.font_with_fallback({
  'JetBrains Mono',
  'Noto Color Emoji',
})

-- Action builders
local act = wezterm.action
config.keys = {
  { key = 't', mods = 'CTRL|SHIFT', action = act.SpawnTab 'CurrentPaneDomain' },
  { key = 'w', mods = 'CTRL|SHIFT', action = act.CloseCurrentTab { confirm = true } },
}

​
Type Information and Defaults

Most configuration options have sensible defaults. You can check the current value of any option using: 
local wezterm = require 'wezterm'

-- This will print the default font size
wezterm.log_info('Default font size: ', wezterm.font_size)
​
font_size
number
default:"12.0"
The font size measured in points. Default is platform-dependent.
​
initial_rows
number
default:"24"
The height of a new window in character cells.
​
initial_cols
number
default:"80"
The width of a new window in character cells.

​
Automatic Configuration Reloading

​
automatically_reload_config
boolean
default:"true"
When true, WezTerm will automatically reload your configuration file when it detects changes.
config.automatically_reload_config = true
This means you can edit your wezterm.lua file and see changes take effect immediately in running WezTerm instances.
Some configuration changes require creating a new tab or window to take full effect, particularly those related to spawning new processes or domain configuration.

​
Debugging Configuration

WezTerm provides several tools for debugging your configuration:

​
Logging

local wezterm = require 'wezterm'

-- Log messages for debugging
wezterm.log_info('This is an info message')
wezterm.log_warn('This is a warning')
wezterm.log_error('This is an error')

​
Configuration Errors

If there’s an error in your configuration file, WezTerm will:
  1. Display an error message in a notification
  2. Log the error to the WezTerm log file
  3. Fall back to default configuration

​
Show Configuration

You can view the resolved configuration using: 
wezterm show-config
This shows all configuration values, including defaults.

​
Best Practices

  1. Use config_builder(): Always use wezterm.config_builder() for better error messages
  2. Organize your config: Split large configurations into multiple files using require()
  3. Comment your code: Document non-obvious configuration choices
  4. Test incrementally: Add configuration options gradually and test each change
  5. Use version checks: Guard new features with version checks for backward compatibility
local wezterm = require 'wezterm'
local config = wezterm.config_builder()

-- Only use this feature if it exists in this version
if wezterm.some_new_feature then
  config.some_new_option = true
end

return config

​
Next Steps

Explore specific configuration areas:

​
See Also

Build docs developers (and LLMs) love

Get started for freeTalk to us