Skip to main content
WezTerm is a powerful, GPU-accelerated terminal emulator written in Rust with extensive customization via Lua scripting. It offers built-in multiplexing, image protocol support, and cross-platform consistency.

​
Why WezTerm?

Lua Scripting

Powerful configuration with Lua programming

Built-in Multiplexing

Tabs and splits without tmux or screen

Image Protocol

Kitty graphics protocol support

Cross-Platform

Consistent on macOS, Linux, Windows, and WSL

​
Installation

1

Install WezTerm

brew install --cask wezterm
2

Install IosevkaTerm Nerd Font

# macOS
brew tap homebrew/cask-fonts
brew install font-iosevka-term-nerd-font

# Linux - Download from nerdfonts.com
3

Link Gentleman.Dots configuration

# Link the Lua config to home directory
ln -sf ~/Gentleman.Dots/.wezterm.lua ~/.wezterm.lua
4

Launch WezTerm

Open WezTerm and enjoy your feature-rich terminal!

​
Configuration Breakdown

The Gentleman.Dots WezTerm config (.wezterm.lua) leverages Lua for powerful customization:

​
Core Configuration

.wezterm.lua
local wezterm = require("wezterm")
local config = {}

-- Color scheme from built-in themes
config.color_scheme = "Kanagawa (Gogh)"

-- Font configuration
config.font = wezterm.font("IosevkaTerm NF")
config.font_size = 16.0

return config
WezTerm comes with hundreds of built-in color schemes. The Gentleman.Dots config uses “Kanagawa (Gogh)” - a pre-installed theme matching the aesthetic of the other terminal configs.

​
Window Styling

.wezterm.lua
-- Transparency and blur
config.window_background_opacity = 0.85
config.macos_window_background_blur = 20  -- macOS blur radius
config.win32_system_backdrop = "Acrylic" -- Windows acrylic effect

-- Remove padding for maximum space
config.window_padding = {
  top = 0,
  right = 0,
  left = 0,
}
WezTerm intelligently applies platform-specific effects: macos_window_background_blur on macOS, win32_system_backdrop on Windows, providing native-feeling transparency on each platform.

​
Tab Bar Configuration

.wezterm.lua
-- Auto-hide tab bar when only one tab
config.hide_tab_bar_if_only_one_tab = true
This keeps the interface clean when you’re only using a single tab, similar to Alacritty’s minimal approach.

​
Performance Optimizations

.wezterm.lua
-- Higher frame rate for smoother rendering
config.max_fps = 240

-- Kitty graphics protocol support
config.enable_kitty_graphics = true

-- Disable scrollbar for cleaner look
config.enable_scroll_bar = false
The max_fps = 240 setting is a “hack for smoothness”. While it provides buttery-smooth rendering on high-refresh displays, it may increase power consumption on laptops.

​
Platform-Specific Configurations

The config includes commented-out Windows-specific settings:
.wezterm.lua
-- Activate ONLY if on Windows with WSL
-- config.default_domain = 'WSL:Ubuntu'
-- config.front_end = "OpenGL"
-- local gpus = wezterm.gui.enumerate_gpus()
-- if #gpus > 0 then
--   config.webgpu_preferred_adapter = gpus[1]
-- end
For Windows WSL users: Uncomment these lines in .wezterm.lua:56-66 to enable WSL Ubuntu as the default shell and optimize GPU rendering.

​
Key Features

​
Built-in Multiplexing

Unlike Alacritty, WezTerm includes tabs and splits: 
Ctrl+Shift+T  # New tab
Ctrl+Tab      # Next tab
Ctrl+Shift+Tab # Previous tab
Ctrl+Shift+W  # Close tab

​
Lua Scripting Power

WezTerm’s Lua configuration enables:
  • Dynamic color schemes based on time of day
  • Custom key bindings for any workflow
  • Event handlers for automation
  • Font fallbacks for better Unicode support
  • Tab/status bar customization with Lua functions
Example advanced configuration:
.wezterm.lua
-- Auto-switch color scheme based on appearance
wezterm.on('window-config-reloaded', function(window, pane)
  local appearance = window:get_appearance()
  if appearance:find 'Dark' then
    window:set_config_overrides({color_scheme = 'Kanagawa (Gogh)'})
  else
    window:set_config_overrides({color_scheme = 'Kanagawa Light'})
  end
end)

​
Image Protocol Support

WezTerm supports the Kitty graphics protocol: 
# Display images in terminal (requires kitty graphics support)
wezterm imgcat image.png

# Works with tools like:
# - ranger (file manager)
# - viu (image viewer)
# - neofetch (system info with logo)
The Gentleman.Dots config enables this with config.enable_kitty_graphics = true in .wezterm.lua:51.

​
Background Images (Optional)

The config includes commented-out background image support:
.wezterm.lua
-- config.background = {
--   {
--     source = { File = "/path/to/image.jpg" },
--     width = "100%",
--     height = "100%",
--     opacity = 1,
--     hsb = {
--       brightness = 0.04,  -- Very dark for readability
--       saturation = 1,
--     },
--   },
-- }
Uncomment and customize the path in .wezterm.lua:7-21 for a background image.

​
Working with Gentleman.Dots

​
With or Without Tmux

WezTerm’s built-in multiplexing means you can: Option 1: Use WezTerm tabs/splits alone 
# Just launch WezTerm and use its native features
Option 2: Combine with tmux for additional features 
# Launch tmux inside WezTerm for:
# - Session persistence
# - Remote attachment
# - Advanced scripting
tmux attach || tmux new

​
Shell Integration

Works perfectly with all Gentleman.Dots shells: 
# .zshrc integration works seamlessly
# Supports: oh-my-zsh, starship prompt, etc.

​
Customization Examples

​
Custom Key Bindings

Add custom shortcuts to your .wezterm.lua:
.wezterm.lua
config.keys = {
  -- Split right with Cmd+D (macOS) or Alt+D
  { key = 'D', mods = 'SUPER', action = wezterm.action.SplitHorizontal },
  
  -- Split down with Cmd+Shift+D
  { key = 'D', mods = 'SUPER|SHIFT', action = wezterm.action.SplitVertical },
  
  -- Quick select (URL/path picker)
  { key = 'Space', mods = 'SUPER|SHIFT', action = wezterm.action.QuickSelect },
}

​
Font Fallbacks

.wezterm.lua
config.font = wezterm.font_with_fallback({
  'IosevkaTerm NF',
  'JetBrains Mono',
  'Symbols Nerd Font',  -- For missing icons
})

​
Dynamic Status Bar

.wezterm.lua
wezterm.on('update-status', function(window, pane)
  local date = wezterm.strftime('%Y-%m-%d %H:%M:%S')
  window:set_right_status(wezterm.format({
    { Text = ' ' .. date .. ' ' },
  }))
end)

​
Advanced Features

​
SSH Domain Integration

.wezterm.lua
config.ssh_domains = {
  {
    name = 'production',
    remote_address = 'server.example.com',
    username = 'user',
  },
}
Then connect with: wezterm connect production

​
Workspace Management

WezTerm supports workspaces (similar to tmux sessions): 
# Create/switch workspace
wezterm cli spawn --workspace coding
wezterm cli spawn --workspace writing

# List workspaces
wezterm cli list --format json

​
Troubleshooting

​
Config Errors

1

Check Lua syntax

WezTerm will show errors on startup if the Lua config is invalid.
2

Use wezterm show-keys

wezterm show-keys
# Lists all configured key bindings
3

Test config

wezterm -n start
# Starts with default config (ignores .wezterm.lua)

​
GPU Issues

.wezterm.lua
-- If you experience rendering issues, try:
config.front_end = "OpenGL"  -- Instead of default WebGpu
-- Or
config.front_end = "Software"  -- Software rendering fallback

​
Font Rendering

If fonts look blurry, check your font_size. WezTerm uses precise font metrics - non-integer sizes may look less crisp on some displays.
.wezterm.lua
config.font_size = 16.0  -- Try integer values: 14, 16, 18

​
Performance Comparison

MetricWezTermAlacrittyKitty
Startup Time~200ms~50ms~100ms
Memory (idle)~50MB~15MB~30MB
Memory (10 tabs)~150MBN/A~80MB
GPU Accel✅ WebGPU✅ OpenGL✅ OpenGL
Image Support✅ Kitty❌✅ Kitty
Config LanguageLuaTOMLConf

​
Next Steps

Advanced WezTerm Config

Official WezTerm documentation

Zsh Configuration

Configure your shell environment

Neovim Setup

Complete IDE in your terminal

Compare Terminals

See all terminal options

​
Resources

Build docs developers (and LLMs) love

Get started for freeTalk to us