Lua Configuration Overview

Complete guide to configuring WezTerm using Lua

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

Simple Configuration

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:

• Color Schemes - Customize your terminal colors
• Fonts - Configure font rendering and selection
• Window Configuration - Control window appearance and behavior
• Key Bindings - Customize keyboard shortcuts

See Also

• CLI Reference
• Default Key Bindings
• wezterm Module API