WezTerm: A Modern Terminal Emulator

Terminal emulators are a personal choice, and I’ve finally settled on WezTerm after trying many others. Here’s why it stands out and how to get started.

Why WezTerm?

After years of using iTerm2, Alacritty, and others, WezTerm hits the sweet spot:

Key Features

Cross-platform - Works identically on macOS, Linux, and Windows

• Same config file across all systems
• No more maintaining separate setups

Lua Configuration - Powerful but approachable

• Real programming language (not proprietary DSL)
• Conditionals, loops, functions
• Easy to understand and modify

GPU-Accelerated - Smooth and responsive

• No lag even with large scrollback
• Efficient resource usage

Built-in Features - Everything you need out of the box

• Multiplexer (like tmux, but integrated)
• Tabs and splits
• Image protocol support
• Ligature support

Active Development - Frequent updates and fixes

• Responsive maintainer
• Active community
• Well-documented

Getting Started

Installation

macOS:

brew install --cask wezterm

Linux: Download from WezTerm releases

Windows: Download installer from official site

Basic Configuration

WezTerm uses a .wezterm.lua file in your home directory:

-- ~/.wezterm.lua
local wezterm = require 'wezterm'
local config = {}

-- Use config builder for clearer error messages
if wezterm.config_builder then
  config = wezterm.config_builder()
end

-- Font configuration
config.font = wezterm.font 'JetBrains Mono'
config.font_size = 14.0

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

-- Window appearance
config.window_background_opacity = 0.95
config.window_decorations = "RESIZE"

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

return config

My Setup

Font Choice

I use JetBrains Mono for its excellent ligatures and readability:

• Clear distinction between similar characters (0 vs O, 1 vs l)
• Programming ligatures (=>, !=, >=)
• Open source and free

Color Scheme

Tokyo Night for dark mode - easy on the eyes during long coding sessions

Key Bindings

config.keys = {
  -- Split panes
  { key = 'd', mods = 'CMD', action = wezterm.action.SplitHorizontal },
  { key = 'd', mods = 'CMD|SHIFT', action = wezterm.action.SplitVertical },

  -- Navigate panes
  { key = 'LeftArrow', mods = 'CMD', action = wezterm.action.ActivatePaneDirection 'Left' },
  { key = 'RightArrow', mods = 'CMD', action = wezterm.action.ActivatePaneDirection 'Right' },
  { key = 'UpArrow', mods = 'CMD', action = wezterm.action.ActivatePaneDirection 'Up' },
  { key = 'DownArrow', mods = 'CMD', action = wezterm.action.ActivatePaneDirection 'Down' },
}

Useful Resources

Official Documentation

• WezTerm Official Site - Comprehensive docs
• Configuration Examples - Sample configs

Community Resources

• Alex Plescan’s WezTerm Guide - Excellent walkthrough
• GitHub issues and discussions - Active community support

Config Inspiration

• Browse other users’ dotfiles on GitHub
• Search for “wezterm.lua” to find examples
• Many developers share their complete setups

Pro Tips

1. Start Simple

   • Don’t copy massive configs
   • Add features as you need them
   • Understand each line you add

2. Lua is Your Friend

   • Use functions for repeated config
   • Add conditionals for different systems
   • Comment your customizations

3. Built-in Multiplexer

   • Try it before reaching for tmux
   • Simpler integration
   • One less tool to manage

4. Image Support

   • Works with image protocols
   • Great for displaying graphs/charts
   • Useful for data analysis workflows

Migrating From Other Terminals

From iTerm2

• Most keybindings can be replicated
• Better performance on older Macs
• Easier config management

From Alacritty

• More features out of the box
• Still GPU-accelerated
• Lua more flexible than YAML

From tmux

• Built-in multiplexer may be enough
• Can still use tmux if needed
• Native splits feel more integrated

Why I Switched

Before: iTerm2 + tmux + custom scripts After: Just WezTerm

Benefits:

• One tool instead of two
• Consistent across all my machines
• Easier to maintain
• Better performance
• Cleaner configuration

Conclusion

WezTerm isn’t perfect for everyone, but if you want:

• Cross-platform consistency
• Powerful configuration without complexity
• Active development and support
• Modern features with good performance

Give it a try. The Lua configuration might seem unusual at first, but it’s more powerful and maintainable than YAML or TOML alternatives.

My config: Eventually I’ll share my full .wezterm.lua in a dotfiles repo, but start simple and build your own first. The best terminal setup is the one that matches your workflow, not someone else’s.

Using WezTerm or have questions? Let me know what you think!