Skip to main content
The wezterm module is the primary module that exposes WezTerm configuration and control to your Lua config file. It provides functions for font configuration, formatting, actions, and various utility functions.

​
Importing the Module

You will typically place this at the top of your configuration file: 
local wezterm = require 'wezterm'

​
Core Functions

The wezterm module provides several categories of functions:

​
Configuration

  • config_builder() - Create a configuration builder object with enhanced error checking
  • config_dir - Path to the directory containing your configuration file
  • config_file - Path to your configuration file
  • executable_dir - Directory containing the wezterm executable
  • home_dir - Path to the user’s home directory

​
Font Functions

​
Formatting and Text

  • format() - Format text with colors and attributes
  • column_width() - Calculate the column width of a string
  • pad_left() - Pad string to width on the left
  • pad_right() - Pad string to width on the right
  • truncate_left() - Truncate string from the left
  • truncate_right() - Truncate string from the right

​
Actions

  • action - Key assignment action constructors
  • action_callback() - Create custom action callbacks
  • has_action() - Check if an action exists

​
Utility Functions

  • log_error() - Log error messages
  • log_info() - Log info messages
  • log_warn() - Log warning messages
  • run_child_process() - Execute a child process
  • sleep_ms() - Sleep for milliseconds
  • hostname() - Get the system hostname
  • version - WezTerm version string
  • target_triple - Rust compilation target triple

​
State Management

  • GLOBAL - Global in-memory state storage that persists across config reloads
  • emit() - Emit custom events
  • on() - Register event handlers

​
Color Schemes

  • get_builtin_color_schemes() - Get all built-in color schemes
  • gradient_colors() - Generate gradient colors

​
Platform Detection

  • running_under_wsl() - Check if running under WSL
  • default_wsl_domains() - Get default WSL domains
  • default_ssh_domains() - Get default SSH domains

​
Basic Usage Example

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

-- Configure font
config.font = wezterm.font('JetBrains Mono', { weight = 'Medium' })
config.font_size = 12.0

-- Configure color scheme
config.color_scheme = 'Tokyo Night'

-- Add key bindings
config.keys = {
  {
    key = 't',
    mods = 'CTRL|SHIFT',
    action = wezterm.action.SpawnTab('CurrentPaneDomain'),
  },
}

return config

​
Version Information

You can access version information to conditionally enable features: 
local wezterm = require 'wezterm'

wezterm.log_info('Running WezTerm version: ' .. wezterm.version)
wezterm.log_info('Target triple: ' .. wezterm.target_triple)

​
Next Steps