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

# Quick Start

> Get up and running with WezTerm in 5 minutes

## Launch WezTerm

After [installing WezTerm](/installation), launch it from your applications menu or command line:

<CodeGroup>
  ```bash macOS theme={null}
  open -a WezTerm
  ```

  ```bash Linux theme={null}
  wezterm
  ```

  ```bash Windows (PowerShell) theme={null}
  wezterm-gui
  ```
</CodeGroup>

WezTerm will start with its default configuration, providing a functional terminal immediately.

## Create Your Configuration File

<Steps>
  <Step title="Create .wezterm.lua">
    Create a configuration file in your home directory:

    <CodeGroup>
      ```bash macOS/Linux theme={null}
      touch ~/.wezterm.lua
      ```

      ```powershell Windows theme={null}
      New-Item -Path $env:USERPROFILE\.wezterm.lua -ItemType File
      ```
    </CodeGroup>
  </Step>

  <Step title="Add basic configuration">
    Open `~/.wezterm.lua` in your text editor and add:

    ```lua theme={null}
    -- Pull in the wezterm API
    local wezterm = require 'wezterm'

    -- This will hold the configuration
    local config = wezterm.config_builder()

    -- Basic configuration
    config.font = wezterm.font 'JetBrains Mono'
    config.font_size = 12.0

    config.color_scheme = 'Tokyo Night'

    config.window_padding = {
      left = 8,
      right = 8,
      top = 8,
      bottom = 8,
    }

    -- Return the configuration to wezterm
    return config
    ```
  </Step>

  <Step title="Reload configuration">
    WezTerm automatically reloads when you save the configuration file. You'll see your changes applied immediately.
  </Step>
</Steps>

## Essential Features

### Tabs and Panes

Create and navigate multiple terminals within one window:

| Action           | macOS         | Linux/Windows      |
| ---------------- | ------------- | ------------------ |
| New tab          | `Cmd+T`       | `Ctrl+Shift+T`     |
| Close tab        | `Cmd+W`       | `Ctrl+Shift+W`     |
| Next tab         | `Cmd+Shift+]` | `Ctrl+Tab`         |
| Previous tab     | `Cmd+Shift+[` | `Ctrl+Shift+Tab`   |
| Split horizontal | `Cmd+Shift+"` | `Ctrl+Shift+Alt+"` |
| Split vertical   | `Cmd+Shift+%` | `Ctrl+Shift+Alt+%` |

### Search Scrollback

Press `Ctrl+Shift+F` to search through your terminal history.

### Copy and Paste

* **Select text** with your mouse, it's automatically copied
* **Paste** with `Ctrl+Shift+V` (Linux/Windows) or `Cmd+V` (macOS)

## Customize Your Setup

### Choose a Font

Browse available fonts:

```bash theme={null}
wezterm ls-fonts
```

Then configure your preferred font:

```lua theme={null}
config.font = wezterm.font 'Fira Code'
config.font_size = 13.0
```

### Pick a Color Scheme

WezTerm includes 700+ color schemes. Some popular options:

```lua theme={null}
-- Dark themes
config.color_scheme = 'Tokyo Night'
config.color_scheme = 'Catppuccin Mocha'
config.color_scheme = 'Dracula'
config.color_scheme = 'Gruvbox Dark'
config.color_scheme = 'Nord'

-- Light themes
config.color_scheme = 'Tokyo Night Day'
config.color_scheme = 'Catppuccin Latte'
```

### Adjust Window Size

```lua theme={null}
config.initial_cols = 120
config.initial_rows = 30
```

### Enable Transparency

```lua theme={null}
config.window_background_opacity = 0.95
config.macos_window_background_blur = 10  -- macOS only
```

## Example Configuration

Here's a complete starter configuration:

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

-- Font configuration
config.font = wezterm.font {
  family = 'JetBrains Mono',
  weight = 'Medium',
}
config.font_size = 12.0

-- Color scheme
config.color_scheme = 'Tokyo Night'

-- Window appearance
config.window_background_opacity = 0.95
config.window_padding = {
  left = 8,
  right = 8,
  top = 8,
  bottom = 8,
}

-- Tab bar
config.hide_tab_bar_if_only_one_tab = true
config.use_fancy_tab_bar = false

-- Scrollback
config.scrollback_lines = 10000

-- Disable audible bell
config.audible_bell = 'Disabled'

return config
```

## Next Steps

<CardGroup cols={2}>
  <Card title="Configuration Guide" icon="sliders" href="/config/files">
    Learn about all configuration options
  </Card>

  <Card title="Key Bindings" icon="keyboard" href="/config/keys">
    Customize keyboard shortcuts
  </Card>

  <Card title="Features" icon="sparkles" href="/features/overview">
    Explore advanced features
  </Card>

  <Card title="Lua API" icon="code" href="/lua/config/overview">
    Deep dive into Lua configuration
  </Card>
</CardGroup>

## Troubleshooting

<Accordion title="Configuration not loading?">
  Check the configuration file location:

  ```bash theme={null}
  wezterm show-config
  ```

  Look for syntax errors in the output.
</Accordion>

<Accordion title="Font not displaying correctly?">
  List available fonts:

  ```bash theme={null}
  wezterm ls-fonts
  ```

  Verify your chosen font is installed and available.
</Accordion>

<Accordion title="Colors look wrong?">
  Ensure your color scheme name is correct:

  ```bash theme={null}
  wezterm show-config | grep color_scheme
  ```

  Browse available schemes in the WezTerm source or documentation.
</Accordion>

<Info>
  Press `Ctrl+Shift+L` to show the debug overlay with detailed configuration information.
</Info>