> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/wezterm/wezterm/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

```lua theme={null}
-- 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
```

<Note>
  Using `wezterm.config_builder()` provides better error messages and validation compared to using a plain Lua table.
</Note>

## 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

<CodeGroup>
  ```lua Simple Configuration theme={null}
  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
  ```

  ```lua Advanced Configuration theme={null}
  local wezterm = require 'wezterm'
  local config = wezterm.config_builder()

  -- Conditional configuration based on platform
  if wezterm.target_triple == 'x86_64-pc-windows-msvc' then
    config.default_prog = { 'pwsh.exe', '-NoLogo' }
  else
    config.default_prog = { '/bin/zsh', '-l' }
  end

  -- Dynamic color scheme based on appearance
  if wezterm.gui then
    config.color_scheme = wezterm.gui.get_appearance():find('Dark') and 'Dracula' or 'GitHub Light'
  end

  return config
  ```
</CodeGroup>

## 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:

```lua theme={null}
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:

```lua theme={null}
local wezterm = require 'wezterm'

-- This will print the default font size
wezterm.log_info('Default font size: ', wezterm.font_size)
```

<ParamField path="font_size" type="number" default="12.0">
  The font size measured in points. Default is platform-dependent.
</ParamField>

<ParamField path="initial_rows" type="number" default="24">
  The height of a new window in character cells.
</ParamField>

<ParamField path="initial_cols" type="number" default="80">
  The width of a new window in character cells.
</ParamField>

## Automatic Configuration Reloading

<ParamField path="automatically_reload_config" type="boolean" default="true">
  When true, WezTerm will automatically reload your configuration file when it detects changes.
</ParamField>

```lua theme={null}
config.automatically_reload_config = true
```

This means you can edit your `wezterm.lua` file and see changes take effect immediately in running WezTerm instances.

<Warning>
  Some configuration changes require creating a new tab or window to take full effect, particularly those related to spawning new processes or domain configuration.
</Warning>

## Debugging Configuration

WezTerm provides several tools for debugging your configuration:

### Logging

```lua theme={null}
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:

```bash theme={null}
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

```lua theme={null}
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](./color-schemes) - Customize your terminal colors
* [Fonts](./fonts) - Configure font rendering and selection
* [Window Configuration](./window) - Control window appearance and behavior
* [Key Bindings](./keys) - Customize keyboard shortcuts

## See Also

* [CLI Reference](/cli/overview)
* [Default Key Bindings](https://wezfurlong.org/wezterm/config/default-keys.html)
* [wezterm Module API](/lua/wezterm/overview)