# WezTerm — GPU-Accelerated Terminal Emulator with Lua Scripting

> WezTerm is a cross-platform terminal emulator written in Rust with a full Lua-based config and scripting layer. It packs multiplexing, SSH mux, image protocols, and ligatures into one fast binary — think Alacritty + Neovim for scriptability.

## Install

Save in your project root:

# WezTerm — Scriptable GPU Terminal

## Quick Use
```bash
# macOS
brew install --cask wezterm
# Windows
winget install wez.wezterm
# Linux (Flatpak)
flatpak install flathub org.wezfurlong.wezterm
```

```lua
-- ~/.config/wezterm/wezterm.lua
local wezterm = require("wezterm")
local config = wezterm.config_builder()

config.font = wezterm.font("JetBrains Mono")
config.font_size = 14.0
config.color_scheme = "Catppuccin Mocha"
config.window_background_opacity = 0.95
config.use_fancy_tab_bar = false
config.enable_scroll_bar = true
config.keys = {
  { key = "d", mods = "CMD",       action = wezterm.action.SplitHorizontal{} },
  { key = "d", mods = "CMD|SHIFT", action = wezterm.action.SplitVertical{} },
}

return config
```

## Introduction
WezTerm, built by Wez Furlong, is the most scriptable GPU-accelerated terminal. It uses Lua for configuration (same philosophy as Neovim) and exposes virtually every rendering, multiplexing, and SSH aspect as scriptable. The combination of speed, features, and scripting makes it a favorite among serious terminal users.

With over 26,000 GitHub stars, WezTerm supports Metal (macOS), WebGPU (cross-platform), or OpenGL rendering. It also bundles a multiplexer — so it can replace tmux in many workflows, including for persistent sessions over SSH.

## What WezTerm Does
WezTerm renders terminal cells on the GPU, supports tabs + splits + ligatures + true color + the kitty and iTerm2 image protocols, and exposes a Lua API that lets you write custom event handlers, dynamic configs, domains (SSH/WSL/Docker), and status-bar widgets. The mux domain feature makes it a tmux alternative with persistent sessions.

## Architecture Overview
```
[WezTerm binary]
      |
[GPU Renderer: Metal / OpenGL / WebGPU]
      |
  +----+----+----+
  |    |    |    |
Tabs Splits Panes Mux
      |
[Lua Config + Event System]
  on("format-tab-title", ...)
  on("bell", ...)
  on("window-resized", ...)
      |
[Domains]
  local, unix:path, SSH: user@host, WSL:Ubuntu,
  Docker: containerid, tls://host:port
      |
[Image Protocols]
  iTerm2 + kitty — broad compatibility
```

## Self-Hosting & Configuration
```lua
-- Multi-domain configuration: SSH mux persistent sessions
config.ssh_domains = {
  { name = "prod",    remote_address = "prod.example.com", username = "deploy" },
  { name = "staging", remote_address = "staging.example.com", username = "deploy" },
}

-- WSL / Docker domains also supported
config.wsl_domains = wezterm.default_wsl_domains()

-- Dynamic status bar
wezterm.on("update-status", function(window, pane)
  local workspace = window:active_workspace()
  window:set_right_status(wezterm.format({
    { Text = " " .. workspace .. " | " .. os.date("%H:%M") .. " " },
  }))
end)

-- Automatic reload: saving the Lua file applies changes instantly
```

## Key Features
- **GPU rendering** — Metal (macOS), WebGPU or OpenGL elsewhere
- **Lua config + scripting** — event handlers, dynamic values, custom widgets
- **Built-in multiplexer** — persistent sessions, SSH mux, WSL, Docker domains
- **Image protocols** — kitty and iTerm2 protocols both supported
- **Ligatures** — first-class rendering for Fira Code / JetBrains Mono
- **Workspaces** — group tabs across windows for project contexts
- **Copy mode + search** — vim-like navigation in scrollback
- **Cross-platform** — macOS, Linux, Windows, FreeBSD

## Comparison with Similar Tools
| Feature | WezTerm | kitty | Alacritty | Ghostty | Windows Terminal |
|---|---|---|---|---|---|
| Scripting | Lua | Python kittens | None | None | JSON + keybindings |
| Multiplexer | Built-in + SSH mux | Via ssh kitten | None (use tmux) | None | None |
| Image protocol | kitty + iTerm2 | kitty | None | kitty | No |
| Cross-platform | macOS/Linux/Windows | macOS/Linux (no Win) | All | macOS/Linux | Windows only |
| GPU backend | Metal/OpenGL/WebGPU | OpenGL | OpenGL | Metal/OpenGL | DirectX |
| Best For | Power users scripting | Feature-rich Unix | Pure speed | Modern macOS | Windows-first |

## FAQ
**Q: WezTerm vs kitty?**
A: Both are feature-rich GPU terminals. WezTerm has Lua scripting and cross-platform Windows support. kitty has kittens (Python). Configs look different; feature parity is close. Pick based on scripting language and OS preference.

**Q: Does the built-in mux replace tmux?**
A: For many users yes — persistent sessions, splits, SSH mux all work. Advanced tmux users will still want tmux for scripts and ecosystem.

**Q: Is Lua hard to configure?**
A: Not if you start by copying the example config and tweaking. The Lua API is well-documented. Unlike Vim's Vimscript, Lua is a proper language.

**Q: How is performance vs Alacritty?**
A: Competitive. WezTerm has more features which add overhead but still feels instant. For pure raw speed dumping gigabytes, Alacritty sometimes wins marginally.

## Sources
- GitHub: https://github.com/wezterm/wezterm
- Website: https://wezterm.org
- License: MIT

---
Source: https://tokrepo.com/en/workflows/a634f04a-380a-11f1-9bc6-00163e2b0d79
Author: AI Open Source