WezTerm + tmux on Windows: the terminal setup that actually works

Your terminal and multiplexer are probably fighting.

Most Windows terminal emulators claim they play nice with tmux. They don’t — not really. They render enough to make a split pane look fine, then quietly fall apart when you actually live inside it. Status bars leave ghosts. Mouse selection stops working across panes. Key combinations get intercepted by Windows before they ever reach tmux. Neovim inside a tmux pane inside Windows Terminal is three layers of “almost works.”

It’s not that Windows is bad for development. It’s that the window you type into and the multiplexer inside it were never built to agree.

The real problem is the split

A terminal workflow has two jobs: draw the characters correctly, and manage the sessions/splits/windows. The terminal emulator handles the first. The multiplexer handles the second. When they disagree, every bug looks like tmux’s fault but it’s actually the emulator lying about what it supports.

Ghost characters, broken mouse support, wrong key codes, colors that shift between panes — those are protocol failures, not tmux failures. tmux is speaking correctly. The terminal just isn’t listening.

Windows Terminal is the worst offender. It intercepts keys, renders escape sequences its own way, and has quirks when you mix native Windows shells with WSL. It tries to be everything at once and ends up mediocre at the actual terminal protocol.

If you spend most of your day in a terminal, mediocre isn’t acceptable.

Why WezTerm for the emulator

WezTerm implements the terminal protocol correctly. It understands the escape sequences tmux depends on, reports itself accurately, and renders text well without looking like a science experiment.

Set TERM=screen-256color or tmux-256color — or wezterm if your terminfo has it — and the sequences land the way tmux expects. Mouse works. Colors stay consistent. Status bars don’t leave artifacts. The basics, done right.

It also handles ligatures, high-DPI displays, and real color schemes. Those are nice extras. The real win is that it stops being the weak link in the chain.

Why tmux for the multiplexer

WezTerm has a built-in multiplexer. It’s good. For purely local work it can replace tmux entirely.

But tmux has something WezTerm’s mux doesn’t: persistence. When you disconnect from a remote server, your tmux session keeps running. Reconnect later and everything is exactly where you left it. For anyone who SSHs into boxes regularly — which is most developers — that’s non-negotiable.

tmux is also the de facto standard. Learn its key bindings once and they work on every server, every cloud VM, every CI debug session. It doesn’t matter what’s installed locally; tmux is almost always there.

So my setup is simple: WezTerm locally, tmux everywhere I need persistence or portability.

Even on Windows

The real argument isn’t that WezTerm is good on Unix. It’s that WezTerm makes Windows feel like a proper development machine for tmux users.

Install the native Windows build and it just runs. No WSL required. It talks to PowerShell, CMD, Git Bash, MSYS2, and WSL equally well. I open WezTerm, SSH into a server, attach to tmux, and forget I’m on Windows.

Your config file is the same one you use on macOS or Linux, with small per-platform overrides if you need them. That portability matters. You stop maintaining one terminal setup for work and another for home. You stop explaining to teammates why your Windows terminal “almost” works.

Installing both

WezTerm:

Windows:

winget install wez.wezterm

macOS:

brew install --cask wezterm

Linux: most distros package it as wezterm. If yours doesn’t, the AppImage on the releases page works without fighting your package manager.

tmux:

Inside WSL or any Linux machine:

sudo apt install tmux

macOS:

brew install tmux

Windows native? Don’t. Run tmux inside WSL or SSH into a box that has it. That’s the whole point.

Set the right TERM

Inside tmux, use:

export TERM=screen-256color

Or tmux-256color if the host’s terminfo supports it. Outside tmux, let WezTerm handle it — wezterm if you installed the terminfo, otherwise xterm-256color works fine.

The goal is the same in both cases: stop letting the emulator claim compatibility it doesn’t have.

The config that travels with you

WezTerm is configured in Lua. tmux is configured in .tmux.conf. Both are plain text you can version control.

One wezterm.lua sets your font, color scheme, launch menu, and key bindings. One .tmux.conf sets your prefix, status bar, mouse mode, and pane behavior. After a day of tweaking, you have a terminal that behaves identically across every machine you touch.

There’s no registry editing. No JSON settings UI that moved between versions. No mystery checkboxes.

What to do next

Install WezTerm. Install tmux. SSH into something, start a session, detach, and reconnect. Open a few panes. Click around with your mouse. Notice how nothing breaks.

Stop apologizing for your terminal. Get an emulator and a multiplexer that agree with each other.