Wezterm: A Browser-Style Terminal
Setup guide for Linux, Mac, and Windows
A terminal emulator with browser-like tabs, GPU acceleration, and sane defaults. Here's my config.
I switched from Konsole to Wezterm recently. The selling point: tabs that work like a browser. Ctrl+T for new tab, Ctrl+W to close, Ctrl+Tab to cycle. After years of muscle memory from Chrome and Firefox, having the same shortcuts in my terminal just makes sense.
Other things I like:
- GPU-accelerated rendering (fast, smooth)
- Config hot-reloads on save (no restart needed)
- Lua config file (scriptable if you want, ignorable if you don’t)
- Pane splits built in (like tmux, but native)
- Cross-platform (same config works on Linux, Mac, and Windows)
Installation
Linux (Debian/Ubuntu)
The distro packages are often outdated. Use the official repo:
curl -fsSL https://apt.fury.io/wez/gpg.key | sudo gpg --yes --dearmor -o /usr/share/keyrings/wezterm-fury.gpg
echo 'deb [signed-by=/usr/share/keyrings/wezterm-fury.gpg] https://apt.fury.io/wez/ * *' | sudo tee /etc/apt/sources.list.d/wezterm.list
sudo apt update && sudo apt install -y wezterm
Also grab JetBrains Mono (excellent programming font):
sudo apt install fonts-jetbrains-mono
To set as default terminal:
sudo update-alternatives --install /usr/bin/x-terminal-emulator x-terminal-emulator /usr/bin/wezterm 50
sudo update-alternatives --set x-terminal-emulator /usr/bin/wezterm
Mac
brew install --cask wezterm
JetBrains Mono:
brew tap homebrew/cask-fonts
brew install --cask font-jetbrains-mono
Windows
Download the installer from wezfurlong.org/wezterm or use winget:
winget install wez.wezterm
JetBrains Mono: download from jetbrains.com/lp/mono and install, or use Scoop:
scoop bucket add nerd-fonts
scoop install JetBrains-Mono
Config
Config location:
- Linux/Mac:
~/.config/wezterm/wezterm.lua - Windows:
C:\Users\<username>\.config\wezterm\wezterm.lua
Create the directory if it doesn’t exist.
Linux/Windows Config
local wezterm = require 'wezterm'
local config = wezterm.config_builder()
-- Appearance
config.color_scheme = 'Catppuccin Mocha'
config.window_background_opacity = 1.0
config.hide_tab_bar_if_only_one_tab = false
config.use_fancy_tab_bar = true
config.window_decorations = "RESIZE"
-- Font
config.font = wezterm.font_with_fallback {
'JetBrains Mono',
'Fira Code',
'monospace',
}
config.font_size = 11.0
-- Scrollback
config.scrollback_lines = 10000
-- Browser-like keybindings
config.keys = {
{ key = 't', mods = 'CTRL', action = wezterm.action.SpawnTab 'CurrentPaneDomain' },
{ key = 'w', mods = 'CTRL', action = wezterm.action.CloseCurrentPane { confirm = false } },
{ key = 'Tab', mods = 'CTRL', action = wezterm.action.ActivateTabRelative(1) },
{ key = 'Tab', mods = 'CTRL|SHIFT', action = wezterm.action.ActivateTabRelative(-1) },
{ key = '1', mods = 'CTRL', action = wezterm.action.ActivateTab(0) },
{ key = '2', mods = 'CTRL', action = wezterm.action.ActivateTab(1) },
{ key = '3', mods = 'CTRL', action = wezterm.action.ActivateTab(2) },
{ key = '4', mods = 'CTRL', action = wezterm.action.ActivateTab(3) },
{ key = '5', mods = 'CTRL', action = wezterm.action.ActivateTab(4) },
{ key = '6', mods = 'CTRL', action = wezterm.action.ActivateTab(5) },
{ key = '7', mods = 'CTRL', action = wezterm.action.ActivateTab(6) },
{ key = '8', mods = 'CTRL', action = wezterm.action.ActivateTab(7) },
{ key = '9', mods = 'CTRL', action = wezterm.action.ActivateTab(-1) },
{ key = 'T', mods = 'CTRL|SHIFT', action = wezterm.action.SpawnTab 'CurrentPaneDomain' },
{ key = 'e', mods = 'CTRL|SHIFT', action = wezterm.action.SplitHorizontal { domain = 'CurrentPaneDomain' } },
{ key = 'h', mods = 'CTRL|SHIFT', action = wezterm.action.SplitVertical { domain = 'CurrentPaneDomain' } },
{ key = 'w', mods = 'CTRL|SHIFT', action = wezterm.action.CloseCurrentTab { confirm = false } },
}
-- Copy on select + click URLs without modifier + smaller scroll increment
config.mouse_bindings = {
{ event = { Up = { streak = 1, button = 'Left' } }, mods = 'NONE', action = wezterm.action.CompleteSelection 'ClipboardAndPrimarySelection' },
{ event = { Up = { streak = 1, button = 'Left' } }, mods = 'NONE', action = wezterm.action.OpenLinkAtMouseCursor, mouse_reporting = false },
{ event = { Down = { streak = 1, button = { WheelUp = 1 } } }, mods = 'NONE', action = wezterm.action.ScrollByLine(-2) },
{ event = { Down = { streak = 1, button = { WheelDown = 1 } } }, mods = 'NONE', action = wezterm.action.ScrollByLine(2) },
}
return config
Mac Config
Same thing, but with Cmd instead of Ctrl (and slightly larger font for Retina):
local wezterm = require 'wezterm'
local config = wezterm.config_builder()
-- Appearance
config.color_scheme = 'Catppuccin Mocha'
config.window_background_opacity = 1.0
config.hide_tab_bar_if_only_one_tab = false
config.use_fancy_tab_bar = true
config.window_decorations = "RESIZE"
-- Font
config.font = wezterm.font_with_fallback {
'JetBrains Mono',
'Fira Code',
'monospace',
}
config.font_size = 13.0
-- Scrollback
config.scrollback_lines = 10000
-- Browser-like keybindings (Cmd on Mac)
config.keys = {
{ key = 't', mods = 'CMD', action = wezterm.action.SpawnTab 'CurrentPaneDomain' },
{ key = 'w', mods = 'CMD', action = wezterm.action.CloseCurrentPane { confirm = false } },
{ key = 'Tab', mods = 'CTRL', action = wezterm.action.ActivateTabRelative(1) },
{ key = 'Tab', mods = 'CTRL|SHIFT', action = wezterm.action.ActivateTabRelative(-1) },
{ key = '1', mods = 'CMD', action = wezterm.action.ActivateTab(0) },
{ key = '2', mods = 'CMD', action = wezterm.action.ActivateTab(1) },
{ key = '3', mods = 'CMD', action = wezterm.action.ActivateTab(2) },
{ key = '4', mods = 'CMD', action = wezterm.action.ActivateTab(3) },
{ key = '5', mods = 'CMD', action = wezterm.action.ActivateTab(4) },
{ key = '6', mods = 'CMD', action = wezterm.action.ActivateTab(5) },
{ key = '7', mods = 'CMD', action = wezterm.action.ActivateTab(6) },
{ key = '8', mods = 'CMD', action = wezterm.action.ActivateTab(7) },
{ key = '9', mods = 'CMD', action = wezterm.action.ActivateTab(-1) },
{ key = 'T', mods = 'CMD|SHIFT', action = wezterm.action.SpawnTab 'CurrentPaneDomain' },
{ key = 'e', mods = 'CMD|SHIFT', action = wezterm.action.SplitHorizontal { domain = 'CurrentPaneDomain' } },
{ key = 'h', mods = 'CMD|SHIFT', action = wezterm.action.SplitVertical { domain = 'CurrentPaneDomain' } },
{ key = 'w', mods = 'CMD|SHIFT', action = wezterm.action.CloseCurrentTab { confirm = false } },
}
-- Mouse bindings (copy on select, click URLs, smaller scroll)
config.mouse_bindings = {
{ event = { Up = { streak = 1, button = 'Left' } }, mods = 'NONE', action = wezterm.action.CompleteSelection 'ClipboardAndPrimarySelection' },
{ event = { Up = { streak = 1, button = 'Left' } }, mods = 'NONE', action = wezterm.action.OpenLinkAtMouseCursor, mouse_reporting = false },
{ event = { Down = { streak = 1, button = { WheelUp = 1 } } }, mods = 'NONE', action = wezterm.action.ScrollByLine(-2) },
{ event = { Down = { streak = 1, button = { WheelDown = 1 } } }, mods = 'NONE', action = wezterm.action.ScrollByLine(2) },
}
return config
Keybindings Summary
| Action | Linux/Windows | Mac |
|---|---|---|
| New tab | Ctrl+T | Cmd+T |
| Close pane | Ctrl+W | Cmd+W |
| Close tab | Ctrl+Shift+W | Cmd+Shift+W |
| Next tab | Ctrl+Tab | Ctrl+Tab |
| Previous tab | Ctrl+Shift+Tab | Ctrl+Shift+Tab |
| Jump to tab N | Ctrl+1-9 | Cmd+1-9 |
| Split horizontal | Ctrl+Shift+E | Cmd+Shift+E |
| Split vertical | Ctrl+Shift+H | Cmd+Shift+H |
Notes
Tab bar as title bar: The config uses window_decorations = "RESIZE" which removes the traditional title bar. The tab bar is always visible and acts as a draggable surface for moving the window.
Panes vs tabs: Tabs are separate terminal sessions. Panes are splits within a single tab—useful for seeing two things at once (e.g., editor and logs) without switching tabs.
Copy on select: Selecting text with the mouse automatically copies it to the clipboard. Standard on Linux, less common on Mac, but I find it useful everywhere.
Clickable URLs: Single-click on any URL to open it in your browser. No modifier key needed.
Scroll speed: Config sets scroll to 2 lines per wheel tick (default is 3). Adjust the -2 and 2 values if you want faster/slower.
Hot reload: Save the config file and changes apply immediately. No restart required.