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

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

```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.

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

<Steps>
  <Step title="Command Line Argument">
    Use the `--config-file` CLI argument to specify a custom location:

    ```bash theme={null}
    wezterm --config-file /path/to/config.lua
    ```
  </Step>

  <Step title="Environment Variable">
    Set the `WEZTERM_CONFIG_FILE` environment variable:

    ```bash theme={null}
    export WEZTERM_CONFIG_FILE="$HOME/my-configs/wezterm.lua"
    ```
  </Step>

  <Step title="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).
  </Step>

  <Step title="XDG Config Directory">
    If `$XDG_CONFIG_HOME` is set:

    ```bash theme={null}
    $XDG_CONFIG_HOME/wezterm/wezterm.lua
    ```
  </Step>

  <Step title="Standard Config Directory">
    Platform-specific standard locations:

    <Tabs>
      <Tab title="Linux/macOS">
        ```bash theme={null}
        ~/.config/wezterm/wezterm.lua
        ```
      </Tab>

      <Tab title="Windows">
        ```powershell theme={null}
        %USERPROFILE%\.config\wezterm\wezterm.lua
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step title="Home Directory (Recommended)">
    The simplest option for single-file configurations:

    <Tabs>
      <Tab title="Linux/macOS">
        ```bash theme={null}
        ~/.wezterm.lua
        ```
      </Tab>

      <Tab title="Windows">
        ```powershell theme={null}
        %USERPROFILE%\.wezterm.lua
        ```
      </Tab>
    </Tabs>
  </Step>
</Steps>

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

## Configuration File Structure

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

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

<CodeGroup>
  ```lua Basic Example theme={null}
  local wezterm = require 'wezterm'
  local config = wezterm.config_builder()

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

  return config
  ```

  ```lua Without config_builder theme={null}
  -- Alternative (less recommended)
  local wezterm = require 'wezterm'
  local config = {}

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

  return config
  ```
</CodeGroup>

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

<Warning>
  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.
</Warning>

## Command Line Overrides

You can override configuration values via command line arguments:

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

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

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

<CodeGroup>
  ```bash Directory Structure theme={null}
  ~/.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
  ```

  ```lua Main Config theme={null}
  -- ~/.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
  ```

  ```lua Appearance Module theme={null}
  -- ~/.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
  ```
</CodeGroup>

## Per-Window Configuration Overrides

You can set window-specific overrides dynamically:

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

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

To test your configuration:

```bash theme={null}
# Check for syntax errors
wezterm start --config-file ~/.wezterm.lua

# View configuration in effect
wezterm show-keys
```

## Best Practices

<Steps>
  <Step title="Use config_builder()">
    Always use `wezterm.config_builder()` for better error messages and validation.
  </Step>

  <Step title="Avoid Side Effects">
    Don't spawn processes or write files in the main configuration flow. Use event handlers instead.
  </Step>

  <Step title="Comment Your Config">
    Add comments explaining non-obvious configuration choices.
  </Step>

  <Step title="Version Control">
    Keep your configuration in version control (git) for easy backups and history.
  </Step>

  <Step title="Start Simple">
    Begin with a minimal configuration and add features as needed.
  </Step>
</Steps>

## Troubleshooting

### Configuration Not Loading

1. Check file location:
   ```bash theme={null}
   wezterm --version
   # Look for "Config file: /path/to/config.lua" in output
   ```

2. Verify Lua syntax:
   ```bash theme={null}
   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