WezTerm on Windows and across platforms

WezTerm uses Lua configuration and provides tabs, panes and multiplexer facilities. It can launch PowerShell or WSL on Windows, but each environment retains its own paths, variables and executables.

Sharing configuration preserves interaction habits, fonts and colours. Installed fonts, shell paths, graphics drivers and display scaling still require per-machine checks.

A complete configuration

Save this as .wezterm.lua in the user directory. It assumes the font is installed and, on Windows, pwsh.exe is available on PATH.

local wezterm = require("wezterm")
local config = wezterm.config_builder()

config.font = wezterm.font("JetBrains Mono")
config.font_size = 12.0
config.color_scheme = "Builtin Solarized Dark"

if wezterm.target_triple:find("windows") then
  config.default_prog = { "pwsh.exe", "-NoLogo" }
end

return config

require loads the API, config_builder() creates the configuration object and the final return supplies it to WezTerm. Copying only config.xxx assignments omits essential context.

Check PowerShell availability from an existing PowerShell window:

Get-Command pwsh

If missing, install PowerShell 7 or choose an existing shell. powershell.exe and pwsh.exe are different programs with potentially different versions and encoding behaviour.

Tabs, panes and WSL

Tabs group workspaces; panes display tasks side by side. Begin with the default key bindings, then customise only what you need.

List installed WSL distributions:

wsl --list --verbose

Launch one by its actual name:

wsl -d Ubuntu

Ubuntu is an example. Run pwd after entering WSL. Windows paths such as C:\Users\... and Linux paths such as /home/... are not interchangeable. Keep the editor, compiler and dependencies in the environment containing the project whenever practical.

Adjust rendering for an observed need

These optional assignments select WebGPU and a frame-rate limit:

config.front_end = "WebGpu"
config.max_fps = 144

They are not universal optimisations. Drivers, remote-desktop sessions and display refresh rates affect the result. For flicker, blank output or extra power use, remove the overrides and compare the default backend. front_end reference

Font size is expressed in points; scaling affects the rendered pixels. Compare actual character width and line height after sharing settings between Windows and Linux.

Verify and recover configuration

WezTerm normally watches configuration changes, but some launch settings affect new windows or processes. This read-only command loads configuration and lists keys:

wezterm show-keys

Use the reported file and line when parsing fails. Check Lua syntax, the API import and return value before investigating fonts, executable paths and rendering. If the application cannot start, restore the backup from another terminal.

Decide whether to add Zellij

Built-in tabs and panes may be sufficient locally. For a separately running remote session, launch Zellij on the SSH host. WezTerm mux servers and domains provide another option, with their own process location and connection setup.

A local window, SSH process and independent mux server have different lifetimes. Test disconnect, reattach and exit with a harmless running task before relying on persistence.

Once stable, manage handwritten .wezterm.lua settings with chezmoi and express platform differences explicitly.