WezTerm
GPU-accelerated terminal with multiplexer
WezTerm — Official Website
Quick Take: WezTerm
WezTerm is the terminal for developers who believe configuration should be code. The Lua config gives you power that no other terminal matches: conditionals, functions, imports, computed values, dynamic behavior. The built-in multiplexer, SSH domains, and cross-platform consistency make it a complete terminal environment. The tradeoff is complexity—you need to be comfortable writing Lua, and the documentation (while excellent) is dense. If you enjoy the process of configuring your tools as much as using them, WezTerm rewards that investment. If you want to open a terminal and start typing without reading any docs, choose Ghostty or Kitty instead.
Best For
- •Developers who want programmable terminal configuration
- •Cross-platform users who want identical config on Mac, Linux, and Windows
- •SSH power users who want remote tabs alongside local tabs
- •Tinkerers who enjoy customizing every aspect of their tools
What is WezTerm?
WezTerm is a terminal emulator configured entirely in Lua. That single fact defines it and separates it from every other terminal: your configuration isn't a static settings file—it's a program. You can write conditionals, define functions, compute values, import modules, and generate configuration dynamically based on the current hostname, time of day, operating system, or anything else you can express in code. If you've ever wished your terminal config had 'if' statements, WezTerm is built for you. Created by Wez Furlong (a former Facebook/Meta engineer who also contributed to PHP and Mercurial), WezTerm is written in Rust and uses GPU rendering for fast text display. It runs on macOS, Linux, and Windows with the same Lua config format across all platforms—write your config once and it works everywhere. The terminal ships with a built-in multiplexer (splits and tabs without tmux), font ligature support, the Kitty Graphics Protocol for inline images, and SSH domain integration that lets you open remote tabs as naturally as local ones. On macOS with Apple Silicon, WezTerm runs as a native ARM64 binary. It uses Metal for GPU rendering (via wgpu, a cross-platform graphics abstraction). The app supports macOS features like system dark mode detection, native notifications, and proper window management. Memory usage is typically 80-150MB depending on the number of tabs and panes open. WezTerm's Lua configuration is both its greatest strength and the reason it's not for everyone. If you enjoy writing config as code—the way you'd enjoy writing a build script or a CI pipeline—WezTerm gives you unmatched control. If you prefer a GUI preferences panel or a simple key-value config file, Kitty or Ghostty will serve you better. WezTerm is the terminal for people who think configuration should be programmable.
Install with Homebrew
brew install --cask weztermDeep Dive: Why Lua Is the Right Config Language for a Terminal
Most terminals use YAML, TOML, or custom key-value formats for configuration. WezTerm uses Lua—a real programming language. This is a deliberate choice that reflects a specific philosophy about developer tools.
History & Background
WezTerm was first released in 2018. Wez Furlong created it partly as a Rust learning project and partly because no existing terminal satisfied his requirements: cross-platform consistency, programmable configuration, and a built-in multiplexer. The choice of Lua for configuration was inspired by Neovim's migration from VimScript to Lua—both projects recognized that a real programming language gives users more power than a static format. WezTerm grew steadily through word-of-mouth in the Rust and Neovim communities.
How It Works
WezTerm is written in Rust with an embedded Lua runtime (mlua). The rendering pipeline uses wgpu, which abstracts Metal, Vulkan, and DirectX 12 behind a single API. Text shaping uses HarfBuzz, font rendering uses FreeType, and the multiplexer is a custom Rust implementation. The Lua config is evaluated at startup and on every config reload. The architecture separates rendering (Rust, performance-critical) from configuration (Lua, user-programmable)—similar to how game engines separate the engine (C++) from game logic (Lua or C#).
Ecosystem & Integrations
WezTerm's ecosystem is growing around shared Lua configs. Developers share config snippets on GitHub, Reddit, and the WezTerm Discussions board. The documentation includes a comprehensive Lua API reference with examples for every feature. Community contributions include themes, keybinding presets, and tab formatting functions. The project's GitHub repository is active with regular releases and responsive issue handling. WezTerm integrates with the broader terminal ecosystem through its support for the Kitty Graphics Protocol, iTerm2 image protocol, and standard terminal escape sequences.
Future Development
WezTerm development is driven by the maintainer's vision and community feedback. Recent development has focused on performance improvements, better macOS integration, and expanding the Lua API surface. The multiplexer protocol is evolving to support more sophisticated session management. The project doesn't publish a formal roadmap but maintains a GitHub milestone system for tracking planned features. The developer has expressed interest in improving the SSH domain experience and adding more built-in Lua helpers for common configuration patterns.
Key Features
Lua Configuration
WezTerm's config is a Lua script (`~/.config/wezterm/wezterm.lua`) that returns a configuration table. Since it's a real programming language, you can do things impossible in static config files: compute font sizes based on screen DPI, switch color schemes based on time of day, define different keybindings per hostname, generate tab titles from the running process, and import shared config from a separate module. Lua is lightweight (the entire runtime is embedded in WezTerm), fast to evaluate, and has a gentle learning curve if you've used any scripting language. WezTerm hot-reloads the config when the file changes, so you see updates immediately.
Built-in Multiplexer
WezTerm includes a full multiplexer—splits (horizontal and vertical), tabs, and the ability to detach and reattach to sessions. You can split panes with keyboard shortcuts, drag pane borders to resize, and navigate between panes with configurable keys. The multiplexer works locally and over SSH connections. For many developers, this eliminates the need for tmux for local work. The multiplexer protocol is WezTerm's own, so it won't interfere with tmux if you use both.
Font Ligatures and Advanced Typography
WezTerm supports OpenType font ligatures, color emoji, font fallback chains, and variable fonts. Coding fonts like Fira Code, JetBrains Mono, and Cascadia Code display their ligatures correctly. You can configure font rules in Lua to apply different fonts to different character ranges—for example, use one font for ASCII and another for CJK characters or Nerd Font icons. Font rendering uses FreeType and HarfBuzz for consistent cross-platform results.
Image Protocol Support
WezTerm supports the Kitty Graphics Protocol and the iTerm2 image protocol, allowing programs to display inline images, charts, and plots. CLI tools like `wezterm imgcat`, `timg`, `viu`, and matplotlib can render images directly in your terminal. WezTerm also supports the Sixel protocol. This multi-protocol approach means most image-aware terminal tools work with WezTerm without additional configuration.
SSH Domains
WezTerm's SSH domains let you define remote hosts in your Lua config and open remote tabs alongside local tabs in the same window. When you open a tab in an SSH domain, WezTerm establishes the SSH connection, runs a remote WezTerm multiplexer server, and presents the remote shell as if it were local. You can split a window with a local pane and a remote pane side by side. This is different from simply running `ssh` in a terminal—the remote shell gets WezTerm's multiplexer integration, including tab titles and pane management.
GPU Rendering via wgpu
WezTerm renders text using wgpu, a Rust-based cross-platform graphics library that targets Metal on macOS, Vulkan on Linux, and DirectX 12 on Windows. This gives smooth scrolling and consistent frame pacing, especially noticeable when scrolling through large amounts of output. The GPU rendering handles 120Hz ProMotion displays on modern MacBooks. Performance is comparable to Kitty and Alacritty for text-heavy workloads.
Customizable Status Bar and Tab Bar
WezTerm's tab bar and right-status area are fully programmable in Lua. You can display the current working directory, git branch, battery level, hostname, or any computed value in the tab title or status bar. Since the formatting code is Lua, you can add conditional logic—show the git branch only when you're in a repo, change the tab color when a command fails, or display the current Kubernetes context when kubectl is in the PATH. This level of tab customization is unique to WezTerm.
Cross-Platform with Identical Config
Your wezterm.lua works on macOS, Linux, and Windows without modification (unless you want platform-specific behavior, which you can add with Lua conditionals). This is valuable for developers who use multiple operating systems—your terminal looks and behaves the same everywhere. Settings, keybindings, colors, fonts, and even multiplexer behavior carry over. Few other terminals achieve this level of cross-platform consistency.
Who Should Use WezTerm?
1The Config-as-Code Developer
Your dotfiles are a carefully maintained git repo. Your tools are configured in code: Neovim in Lua, Nix for system packages, Terraform for infrastructure. WezTerm fits naturally—your terminal config is Lua, version-controlled, and shareable. You define functions for common config patterns, import shared modules for color schemes, and use conditionals to adjust behavior per machine. When a colleague asks about your setup, you send them your wezterm.lua and they can reproduce it exactly.
2The Cross-Platform Developer
You use macOS on your laptop and Linux on your workstation. You want the same terminal experience on both. WezTerm's Lua config works identically on both platforms. Your font configuration, keybindings, and color scheme are the same everywhere. You add a platform check in Lua (`wezterm.target_triple:find('apple')`) to adjust a few macOS-specific settings (like window decorations), and everything else is shared.
3The SSH Power User
You manage servers across three environments and SSH into them constantly. With WezTerm's SSH domains, you define each server in your Lua config with connection parameters. You open remote tabs in the same window as your local tabs—no separate terminal windows for each server. The remote tabs show the hostname in their title. When you split a pane, you can put a local shell next to a remote shell for comparing outputs.
4The Tab Customizer
You want your terminal tabs to show useful information: the current directory (shortened), the running process, and the git branch. In most terminals, you'd need a separate tool or a complex shell configuration. In WezTerm, you write a Lua function in your config that formats the tab title from process info, environment variables, and file system checks. The tab updates in real time as you navigate directories and switch between programs.
How to Install WezTerm on Mac
WezTerm is available via Homebrew with native Apple Silicon support.
Install via Homebrew
Run `brew install --cask wezterm` in your current terminal. WezTerm installs to /Applications.
Create Your Lua Config
Create the config directory and file: `mkdir -p ~/.config/wezterm && touch ~/.config/wezterm/wezterm.lua`. Open the file in any editor. Start with the minimal config: ```lua local wezterm = require 'wezterm' local config = wezterm.config_builder() config.font = wezterm.font('JetBrains Mono') config.font_size = 14 return config ```
Choose a Color Scheme
WezTerm ships with hundreds of built-in color schemes. Add `config.color_scheme = 'Catppuccin Mocha'` to your config. Run `wezterm ls-color-schemes` in the terminal to see all available schemes.
Test Multiplexer and Splits
Press Cmd+Shift+Enter to split horizontally. Press Cmd+Shift+| to split vertically. Press Cmd+T to open a new tab. Navigate between panes with Ctrl+Shift+Arrow keys. All shortcuts are configurable in your Lua config.
Pro Tips
- • Use `wezterm.config_builder()` in your config (available since version 20230326) for better error messages when you mistype a config key.
- • WezTerm hot-reloads your config on save. You'll see changes immediately without restarting—just save wezterm.lua.
- • Check WezTerm's built-in documentation with `wezterm --help` and the comprehensive online docs at wezterm.org.
Configuration Tips
Use config_builder() for Type Safety
Start your config with `local config = wezterm.config_builder()`. This enables runtime validation of config keys—if you misspell a key name, WezTerm will show an error instead of silently ignoring it. This saves debugging time when you can't figure out why a setting isn't taking effect.
Dynamic Color Scheme Based on Time of Day
Since your config is Lua, you can switch themes automatically: ```lua local hour = tonumber(os.date('%H')) if hour >= 7 and hour < 19 then config.color_scheme = 'Catppuccin Latte' else config.color_scheme = 'Catppuccin Mocha' end ``` This switches to a light theme during the day and dark at night—no manual toggling needed.
Define SSH Domains for Remote Servers
Add SSH domains to your config for one-click remote tabs: ```lua config.ssh_domains = { { name = 'prod', remote_address = 'prod.example.com', username = 'deploy' }, { name = 'staging', remote_address = 'staging.example.com', username = 'deploy' }, } ``` Then open a remote tab from the launcher (Cmd+Shift+L → select the domain). The remote shell appears as a tab alongside your local tabs.
Custom Tab Titles with Lua Functions
Override tab titles to show useful information: ```lua wezterm.on('format-tab-title', function(tab, tabs, panes, config, hover, max_width) local pane = tab.active_pane local title = pane.title if pane.current_working_dir then title = pane.current_working_dir.file_path:gsub('.*/', '') end return ' ' .. title .. ' ' end) ``` This shows the current directory name in each tab title instead of the process name.
Import Shared Config Modules
Split your config into modules for organization: ```lua local keybindings = require('keybindings') -- ~/.config/wezterm/keybindings.lua config.keys = keybindings.keys config.key_tables = keybindings.key_tables ``` This keeps your main wezterm.lua clean and lets you share specific config modules across machines.
Alternatives to WezTerm
WezTerm competes with other modern, configurable terminal emulators:
Kitty
Kitty uses a simple key-value config file (kitty.conf) instead of Lua. Its graphics protocol is more widely adopted by CLI tools. Kitty's kittens (Python scripts) provide extensibility but can't modify the config itself. Choose Kitty for simpler config and better graphics protocol support; choose WezTerm for programmable configuration and cross-platform consistency.
Ghostty
Ghostty is a native macOS terminal with Metal rendering and AppKit UI. It has the best macOS integration of any modern terminal. Its config is a simple key-value file. Ghostty is faster at startup and feels more like a Mac app. Choose Ghostty for the native Mac experience; choose WezTerm for Lua config and cross-platform use.
Alacritty
Alacritty is the minimalist option—GPU-rendered, YAML config, no splits, no tabs. It's the fastest at raw text rendering and the most resource-efficient. WezTerm is more feature-rich (multiplexer, images, SSH domains, Lua) at the cost of slightly higher resource usage. Choose Alacritty if you use tmux and want the absolute minimum terminal.
iTerm2
iTerm2 has a GUI preferences panel with extensive options, profiles, triggers, and deep macOS integration. It's CPU-rendered and slower than WezTerm for heavy output. WezTerm is faster, more configurable (via Lua), and cross-platform. iTerm2 is easier to set up and has more macOS-specific features.
Pricing
WezTerm is free and open-source under the MIT license. There are no paid features, no premium tier, and no donation requirements. The project is maintained by Wez Furlong with community contributions. Development is funded by the developer personally.
Pros
- ✓Lua configuration gives you a full programming language for terminal settings
- ✓Built-in multiplexer eliminates tmux for most local workflows
- ✓Cross-platform with identical config (macOS, Linux, Windows)
- ✓SSH domains let you open remote tabs alongside local tabs
- ✓Supports Kitty Graphics Protocol, iTerm2 protocol, and Sixel for inline images
- ✓Font ligatures and advanced typography work correctly
- ✓GPU rendering via wgpu for smooth scrolling
- ✓Programmable tab bar and status line
- ✓Free and open-source (MIT license)
- ✓Active development with frequent releases
Cons
- ✗Lua config has a steeper learning curve than key-value config files
- ✗Startup time is slightly slower than Kitty or Alacritty (200-300ms vs 100ms)
- ✗The documentation is comprehensive but can be overwhelming for new users
- ✗Some macOS-specific features (like native tabs) feel less polished than Ghostty or iTerm2
- ✗The community is smaller than Kitty or iTerm2
- ✗Occasional rendering glitches with complex Unicode (rare but reported)
Community & Development
WezTerm has an active community on GitHub with over 20,000 stars and a responsive issue tracker. The developer, Wez Furlong, is actively involved in issue discussions and development. The project has a GitHub Discussions board where users share configs, ask questions, and request features. There's a growing collection of community-contributed Lua config snippets and themes. The documentation at wezterm.org is comprehensive and well-organized, with examples for common configuration patterns. WezTerm is frequently discussed alongside Kitty, Ghostty, and Alacritty in terminal comparison threads on Reddit, Hacker News, and various developer forums.
Video Tutorials
Getting Started with WezTerm
More Tutorials
Why I am switching from Kitty to WezTerm? (How to setup WezTerm)
Lazar Nikolov • 43.7K views
Make Your Mac Terminal Awesome: Easy WezTerm & Starship Setup
Henry Misc • 64.8K views
WezTerm Terminal Setup for Nushell on macOS
Learning Nushell: My Journey • 216 views
Frequently Asked Questions about WezTerm
Our Verdict
WezTerm is the terminal for developers who believe configuration should be code. The Lua config gives you power that no other terminal matches: conditionals, functions, imports, computed values, dynamic behavior. The built-in multiplexer, SSH domains, and cross-platform consistency make it a complete terminal environment. The tradeoff is complexity—you need to be comfortable writing Lua, and the documentation (while excellent) is dense. If you enjoy the process of configuring your tools as much as using them, WezTerm rewards that investment. If you want to open a terminal and start typing without reading any docs, choose Ghostty or Kitty instead.
About the Author
Related Technologies & Concepts
Related Topics
Sources & References
Key Verified Facts
- WezTerm is a GPU-accelerated cross-platform terminal emulator and multiplexer written in Rust.[cite-1]
- Configuration is implemented entirely via a Lua script, allowing users to write dynamic conditionals, define functions, and import modules.[cite-2]
- WezTerm features built-in terminal multiplexing, allowing users to detach and reattach sessions natively without relying on external tools like tmux or screen.[cite-3]
- The terminal includes robust built-in support for font ligatures, color emojis, and complex font fallback rules.[cite-4]
- The official GitHub repository confirms WezTerm is an open-source project primarily developed in the Rust programming language.[cite-5]
- 1WezTerm - Wez's Terminal Emulator
Accessed May 6, 2026
"WezTerm is a GPU-accelerated cross-platform terminal emulator and multiplexer written in Rust."
- 2Configuration - WezTerm
Accessed May 6, 2026
"Configuration is implemented entirely via a Lua script, allowing users to write dynamic conditionals, define functions, and import modules."
- 3Multiplexing - WezTerm
Accessed May 6, 2026
"WezTerm features built-in terminal multiplexing, allowing users to detach and reattach sessions natively without relying on external tools like tmux or screen."
- 4Fonts - WezTerm
Accessed May 6, 2026
"The terminal includes robust built-in support for font ligatures, color emojis, and complex font fallback rules."
- 5wezterm/wezterm: A GPU-accelerated cross-platform terminal emulator
Accessed May 6, 2026
"The official GitHub repository confirms WezTerm is an open-source project primarily developed in the Rust programming language."
- 6Releases · wezterm/wezterm
Accessed May 6, 2026
"Release notes demonstrate active, ongoing cross-platform support, providing compiled binaries for macOS, Linux, and Windows environments."
- 7Top Rust terminal emulators - LogRocket Blog
Accessed May 6, 2026
"WezTerm is highlighted in the Rust ecosystem as a highly customizable alternative to Alacritty, specifically praised for its dynamic Lua scripting capabilities."
- 8WezTerm Terminal Setup and Configuration - DEV Community
Accessed May 6, 2026
"Developers utilize WezTerm's dynamic Lua configuration to automatically compute values and switch themes based on the operating system's time of day or light/dark mode settings."
- 9WezTerm: A GPU-accelerated cross-platform terminal emulator | Hacker News
Accessed May 6, 2026
"Community discussions highlight WezTerm's ability to replace multiple separate tools, such as Alacritty and tmux, with a single, unified Rust binary."
- 10Typing Latency Benchmark · Issue #224 · wezterm/wezterm
Accessed May 6, 2026
"Performance benchmarks and latency tracking indicate that WezTerm's GPU-accelerated rendering significantly reduces input lag and CPU overhead compared to standard software-rendered terminals."