tmux Mac Setup: Install, Configure and Split Panes
Nemo · · 4 min read
To use tmux on a Mac, install it with Homebrew (brew install tmux), run tmux in any terminal, and press Ctrl+b followed by % or " to split the window into panes. A few lines in ~/.tmux.conf make it feel at home on macOS: mouse support, copying to the system clipboard and splits that open in the current folder. The real reason to use it is sessions: your shells keep running after you close the terminal window, and you attach to them again later.
How do you install tmux on a Mac?
macOS doesn’t ship tmux, so install it with a package manager:
brew install tmux
tmux -V # prints the version
With MacPorts it is sudo port install tmux. Then open the terminal (our guide on how to open the terminal on a Mac lists every way) and type tmux. A green status bar at the bottom means you are in.
What are the first commands to learn?
Every tmux key starts with the prefix, Ctrl+b by default: press it, let go, then press the next key.
| Keys | What it does |
|---|---|
| Ctrl+b % | Split into left and right panes |
| Ctrl+b “ | Split into top and bottom panes |
| Ctrl+b arrow | Move to the pane in that direction |
| Ctrl+b z | Zoom the current pane, again to unzoom |
| Ctrl+b c | New window (a tab, in tmux terms) |
| Ctrl+b d | Detach: leave tmux running in the background |
tmux attach |
Come back to the last session |
The full list, with sessions, windows and copy mode, is in our tmux cheat sheet.
What should a Mac .tmux.conf have?
Create ~/.tmux.conf with a few lines that fix the usual Mac annoyances:
set -g mouse on # click panes, drag borders, scroll
bind | split-window -h -c "#{pane_current_path}"
bind - split-window -v -c "#{pane_current_path}"
set -g base-index 1 # number windows from 1
bind -T copy-mode-vi y send -X copy-pipe-and-cancel "pbcopy"
setw -g mode-keys vi
Reload it with tmux source-file ~/.tmux.conf. The pbcopy line sends text you copy in tmux’s copy mode to the macOS clipboard, so Cmd+V works in other apps. The -c "#{pane_current_path}" part makes new panes start in the folder you were in.
Which terminal works best with tmux?
Any of them. The built-in Terminal is fine; terminals with their own splits matter less once tmux draws the panes. Two settings help: let the Option key act as Meta if you use Alt bindings (Terminal: Settings, Profiles, Keyboard), and pick a theme with good contrast for the status bar. The best terminal for Mac compares the main options.
How do you work with sessions?
A session is a set of windows and panes that keeps running on its own. Name one per project and switching projects becomes one command:
tmux new -s site # start a session called "site"
tmux ls # list running sessions
tmux attach -t site # go back to it
tmux kill-session -t site
Inside tmux, Ctrl+b s shows the sessions as a list you can pick from, and Ctrl+b $ renames the current one. Sessions live as long as the tmux server does: they survive closing the terminal window, but not a restart of the Mac.
Do you need tmux if your app already splits?
It depends on what you want from it:
| You want | tmux | App splits (iTerm2, a browser with panes) |
|---|---|---|
| Shells that keep running after you close the window | Yes, detach and attach | No |
| The same setup over SSH on a server | Yes | No |
| Panes next to web pages | No | Yes, in a browser with panes |
| No prefix key to learn | No | Yes |
Monok borrows the tmux layout for a browser: every tab is a tree of panes, and a pane can be a web page or a native terminal running your login shell. Cmd+D splits right, Shift+Cmd+D splits down, Option+Cmd+arrows move the focus and Shift+Cmd+Return zooms a pane, with no prefix. Layouts come back with the session, but a terminal comes back as an empty pane: it doesn’t keep processes running the way tmux does. So the two work together well. Run tmux inside a Monok terminal pane and you get detachable sessions next to your pages. The home page shows the panes in a real window.
FAQ
Is tmux built into macOS?
No. Install it with brew install tmux or MacPorts.
How do I scroll in tmux on a Mac?
Add set -g mouse on to ~/.tmux.conf and scroll with the trackpad, or press Ctrl+b then [ to enter copy mode and use the arrow keys.
Can I change the Ctrl+b prefix?
Yes. Many people use Ctrl+a: add unbind C-b, set -g prefix C-a and bind C-a send-prefix to the config.
Why do my colors look wrong inside tmux?
tmux needs to know the terminal supports more colors. Adding set -g default-terminal "screen-256color" to the config fixes most cases.
Does Monok replace tmux?
No. Its panes cover splitting a window; tmux adds sessions that outlive it. Monok 0.1.0 is on the download page.