How to Install and Configure WezTerm Terminal Emulator in Linux

Modern Linux command-line workflows demand speed, flexible window tiling, and rich graphical rendering. While traditional terminal emulators often struggle with high-refresh displays or complex font ligatures, WezTerm has emerged as a top-tier GPU-accelerated terminal emulator and multiplexer. Written in Rust and powered by OpenGL and WebGPU, WezTerm delivers blistering rendering speeds alongside a highly expressive Lua configuration engine.

Unlike emulators that rely on inflexible JSON or YAML configuration files, WezTerm’s Lua scripting interface allows you to build dynamic themes, programmatic keybindings, and automated session workspaces. Furthermore, WezTerm includes built-in terminal multiplexing, native support for tabs and splits, and seamless rendering for terminal graphics protocols like Sixel and Kitty graphics.

This guide walks you through installing WezTerm across common Linux distributions, constructing your initial Lua configuration, customising fonts and colour schemes, and mastering split-pane multiplexing.

---

Installing WezTerm on Linux

WezTerm provides pre-built binaries and dedicated repositories across major Linux package managers.

On Ubuntu and Debian

You can install WezTerm directly from the official APT repository:

curl -fsSL https://apt.fury.io/wez/gpg.key | sudo gpg --yes --dearmor -o /etc/apt/keyrings/wezterm-fury.gpg
echo 'deb [signed-by=/etc/apt/keyrings/wezterm-fury.gpg] https://apt.fury.io/wez/ * *' | sudo tee /etc/apt/sources.list.d/wezterm.list
sudo apt update
sudo apt install wezterm

On Fedora and RHEL

Enable the official COPR repository and install WezTerm via DNF:

sudo dnf copr enable wezfurlong/wezterm-nightly
sudo dnf install wezterm

On Arch Linux

WezTerm is available in the extra repository:

sudo pacman -S wezterm

Universal Flatpak or AppImage

If you prefer containerised application packages:

flatpak install flathub org.wezfurlong.wezterm

---

Configuring WezTerm Using Lua

WezTerm reads its configuration from a single Lua file located in your home directory at ~/.wezterm.lua (or ~/.config/wezterm/wezterm.lua). Because it is written in Lua, changes can be loaded dynamically without restarting the application.

Create your configuration file using your preferred text editor:

nano ~/.wezterm.lua

Starter Configuration Template

Paste the following modern, production-ready configuration boilerplate:

local wezterm = require 'wezterm'
local config = {}

-- Use config_builder when available for detailed validation
if wezterm.config_builder then
  config = wezterm.config_builder()
end

-- Font configuration with coding ligatures
config.font = wezterm.font('JetBrains Mono', { weight = 'Regular', italic = false })
config.font_size = 12.0

-- Colour scheme selection
config.color_scheme = 'Tokyo Night'

-- Window padding and layout
config.window_padding = {
  left = 12,
  right = 12,
  top = 10,
  bottom = 10,
}

-- Window decoration and subtle opacity
config.window_background_opacity = 0.95
config.hide_tab_bar_if_only_one_tab = true

-- Cursor styling
config.default_cursor_style = 'BlinkingBar'
config.animation_fps = 60

return config

Save the file and close your editor. WezTerm automatically watches this file and updates its appearance instantly without requiring a restart.

---

Customising Fonts and Colour Schemes

WezTerm ships out of the box with over 1,000 built-in colour schemes, sparing you the trouble of manually copying hex codes.

Browsing Built-in Schemes

You can substitute 'Tokyo Night' in the config above with any popular palette:

• 'Catppuccin Mocha'
• 'Gruvbox Dark (Gogh)'
• 'Dracula'
• 'Nord'
• 'Solarized Dark (Gogh)'

To inspect every installed scheme interactively in your terminal, press Ctrl + Shift + P to launch the built-in Command Palette, type palette, and scroll through live previews.

---

Mastering Tabs, Splits, and Built-in Multiplexing

WezTerm includes a built-in terminal multiplexer that provides tmux-like workspace capabilities without requiring extra software layers.

Essential Navigation Shortcuts

Shortcut	Function
Shift + Ctrl + T	Open a new tab
Shift + Ctrl + W	Close the current tab or pane
Shift + Alt + %	Split active pane horizontally
Shift + Alt + "	Split active pane vertically
Shift + Ctrl + Left / Right	Navigate between split panes
Shift + Ctrl + F	Interactive fuzzy text search across terminal scrollback

---

Troubleshooting Common WezTerm Issues on Linux

Wayland vs X11 Display Glitches

If you encounter window tearing or border anomalies under Wayland desktop environments (such as GNOME or KDE Plasma), force WezTerm to prefer Wayland or XWayland by appending the following line to your ~/.wezterm.lua:

config.enable_wayland = true

Missing Coding Ligatures or Box-Drawing Glyphs

WezTerm automatically falls back to system Nerd Fonts and Noto Color Emoji. However, if glyphs appear as missing rectangles, ensure a dedicated patched font like FiraCode Nerd Font or JetBrains Mono Nerd Font is installed in ~/.local/share/fonts/, and run fc-cache -fv.