WezTerm Configuration Guide: GPU-Accelerated Terminal with Lua Setup

Why WezTerm?

WezTerm is a GPU-accelerated terminal emulator configured in Lua. Unlike Alacritty (which uses TOML/YAML), WezTerm's Lua config gives you the full power of a programming language for keybindings, tab management, and dynamic theming.

This guide sets up WezTerm from scratch: GPU rendering, fonts, color schemes, tab and pane management, and shell integration.

• GPU-accelerated rendering with zero lag
• Lua-based configuration for infinite flexibility
• Built-in multiplexer (panes and tabs — no tmux needed)
• Shell integration for automatic directory tracking

Installing WezTerm

Install WezTerm:

brew install --cask wezterm

• macOS, Linux, or Windows (WezTerm is cross-platform)
• A GPU that supports OpenGL or Metal (any modern GPU works)
• A Nerd Font installed for icon support
• Basic Lua knowledge helpful but not required

Create your config file:

~/.wezterm.lua

Lua Config Basics

Start with a foundational config that covers the essentials:

local wezterm = require 'wezterm'
return {
-- GPU frontend
front_end = "WebGpu",
-- Font configuration
font = wezterm.font('JetBrains Mono Nerd Font'),
font_size = 14.0,
-- Color scheme
color_scheme = 'Catppuccin Mocha',
-- Window appearance
window_background_opacity = 0.95,
window_decorations = "RESIZE",
-- Tab bar
enable_tab_bar = true,
tab_bar_at_bottom = true,
}

• front_end = "WebGpu" enables GPU rendering
• Use any color scheme from the 200+ built-in options
• Window opacity and decorations are fully configurable
• Tab bar can be at top or bottom, or disabled entirely

Window & Tab Management

WezTerm has its own multiplexer — you don't need tmux. Manage tabs and split panes directly:

• Cmd+T — new tab
• Cmd+D — split pane right
• Cmd+Shift+D — split pane down
• Cmd+[ / Cmd+] — move between panes
• Cmd+W — close pane/tab
• Cmd+Shift+Enter — toggle pane zoom

GPU Rendering & Font Tuning

WezTerm's Lua config means you can do anything. Here are advanced patterns:

• Dynamic color schemes: switch themes based on time of day or system dark/light mode
• Custom keybindings with conditional logic — different keys per pane
• Shell integration: WezTerm tracks your working directory for smart pane splits
• Custom tab titles with process info, git branch, or directory name
• Multiple config profiles loaded per workspace or domain

-- Dynamic theme based on system appearance
function scheme_for_appearance(appearance)
if appearance:find("Dark") then
return "Catppuccin Mocha"
else
return "Catppuccin Latte"
end
end
wezterm.on('window-config-reloaded', function(window)
window:set_config_overrides({
color_scheme = scheme_for_appearance(
wezterm.gui.get_appearance()
)
})
end)

Config & Rendering Issues

Rendering and config issues:

• Fonts look blurry? Try front_end = "WebGpu" or adjust font_size
• Colors wrong? Ensure your color scheme name matches exactly — check with wezterm ls-fonts
• Config not loading? Run wezterm --config-file ~/.wezterm.lua to debug errors
• GPU issues? Fall back to front_end = "OpenGL" for compatibility

Terminal Perfection

Your WezTerm is configured. Explore more:

• Customize color schemes and fonts (see [[WezTerm Color Schemes]])
• Set up keybindings and shell integration (see [[WezTerm Keybindings]])
• Compare with tmux — which multiplexer is right for you? (see [[Tmux Terminal Multiplexer Guide]])
• Try Zellij as another modern alternative (see [[Zellij Terminal Workspace Guide]])