tmux on Mac: Homebrew, iTerm2, and the clipboard setup

brew install tmux is the whole installation. What actually takes setup on macOS is the clipboard — copying inside tmux doesn't reach pbcopy by default — and deciding whether to run tmux the normal way inside iTerm2, or hand control of windows over to iTerm2 with -CC, which is a genuinely different mode with real tradeoffs, not just a nicer skin.

Installing#

brew install tmux

Homebrew always builds current upstream, so version lag — the thing that matters on Debian or RHEL — isn't a concern here. tmux -V after installing should print whatever's current.

The clipboard: pbcopy and reattach-to-user-namespace#

Older guides — and some still-circulating dotfiles — wrap every clipboard command in reattach-to-user-namespace, a small tool that existed because Mac OS X 10.5 changed how daemonized processes relate to the pasteboard service, and tmux's server process lost access to it as a side effect. tmux 2.6 absorbed that fix directly, so on a current Homebrew tmux you generally don't need the wrapper — a plain pbcopy binding works:

bind -T copy-mode-vi y send -X copy-pipe-and-cancel "pbcopy"

If you hit a setup where pbcopy from inside tmux silently does nothing — it does still happen on some configurations — reattach-to-user-namespace is still available via brew install reattach-to-user-namespace as a fallback, wrapping the same binding:

bind -T copy-mode-vi y send -X copy-pipe-and-cancel "reattach-to-user-namespace pbcopy"

Try the plain version first. Reach for the wrapper only if copy genuinely isn't working, not as a precaution. If you're on Apple Silicon, note that brew install reattach-to-user-namespace installs under /opt/homebrew rather than the old Intel /usr/local, so a binding copied from an older dotfiles repo that hardcodes /usr/local/bin/reattach-to-user-namespace will fail silently — call the command by name and let PATH resolve it instead.

Two more options worth setting alongside it:

set -g set-clipboard on
setw -g mode-keys vi

set-clipboard on lets tmux talk to the system clipboard via OSC 52 as well, which matters if you're inside an SSH session and want copy-mode selections to reach your local Mac's clipboard, not just the remote one.

Terminal.app vs iTerm2#

Terminal.app is fine for a plain tmux session with 256 colors and works everywhere with zero setup. The two things it genuinely can't do are true 24-bit color and control mode — if either matters to you, iTerm2 is the answer, not a Terminal.app workaround.

Truecolor setup#

Whichever terminal you use, tmux needs telling that the terminal underneath supports RGB color, via the Tc or RGB terminal capability:

set -g default-terminal "tmux-256color"
set -ag terminal-overrides ",xterm-256color:RGB"

tmux-256color is tmux's own terminfo entry and the current recommendation over the older screen-256color. Confirm it worked from inside a session:

If $COLORTERM comes back empty inside tmux but prints truecolor outside it, the terminal-overrides line above is what's missing — the terminal itself already supports it, tmux just hasn't been told.

iTerm2 + tmux control mode (-CC)#

-CC is a different way of running tmux entirely: instead of drawing a text-mode UI inside a single terminal window, tmux sends structured data to iTerm2 and iTerm2 renders each tmux window as a native tab, with native scrollback, search, and copy/paste.

tmux -CC attach -t work

Control mode is worth using if you're on one Mac, reattaching to the same session constantly, and want it to feel like native tabs rather than a terminal-in-a-terminal. It's the wrong choice if you ever attach from somewhere other than iTerm2 on that one machine, or if someone else needs to attach to the same session with plain tmux — they'll see a session that behaves subtly differently than what you're describing to them.

Option as Meta#

By default, macOS terminals don't send an Escape sequence when you press Option — so Option-b / Option-f (word-back, word-forward in readline, and common in vim and tmux copy-mode bindings) do nothing useful inside a shell. Both terminals have a setting to fix it:

This isn't a tmux setting — it's the terminal emulator deciding what escape sequence Option sends — but it's squarely a "why doesn't Option-arrow work in my shell inside tmux" question, so it belongs here.

Checking a session from off your Mac#

None of the above changes the tmux commands themselves — see tmux commands for the full reference. It also doesn't change if you need to check on a session from somewhere that isn't your Mac — your phone, someone else's machine. The normal answer is SSH back in and tmux attach, covered in tmux attach session. If you'd rather get pushed a notification the moment a long job finishes instead of remembering to reattach, that's what mtmux does — npm i -g mtmux on the Mac running the session, and it serves that same tmux to a browser with a notification when a pane goes quiet.