A terminal window closes, an SSH connection drops, or you need more than one shell in the same workspace. tmux helps by keeping terminal sessions organized—and, when it runs on a server, alive after your SSH client disconnects.
On a Mac, the setup is straightforward. The important distinction is where tmux runs: a local tmux session belongs to your Mac, while a tmux session started after SSHing into a server belongs to that server.
Install tmux
If you use Homebrew, install and verify tmux from Terminal or iTerm2:
brew install tmux
tmux -V
If you use MacPorts instead, install it with:
sudo port install tmux
Use one package manager for the installation rather than installing duplicate copies through both. You do not need to run tmux itself with sudo.
To see which executable your shell will use, run:
command -v tmux
That is useful if you have more than one installation on your Mac. Your shell runs the first matching executable in its PATH.
Start a session and come back to it
Create a named session so it is easy to find later:
tmux new-session -s work
You are now working inside tmux. Run commands as usual. To leave the session running and return to the regular terminal, press the default prefix Ctrl+b, release it, then press d.
These are sequential keystrokes—not a three-key chord. To reconnect, list sessions and attach to the one you want:
tmux list-sessions
tmux attach-session -t work
If there is only one session, tmux attach is also enough.
A local session stays available while your Mac is running, but it does not survive a Mac reboot. A session running on a remote server can remain available after your SSH connection drops, as long as the server and the session keep running. If you’re setting up that remote connection for the first time, this Mac-to-Linux SSH walkthrough covers the connection side.
The few keys worth learning first
Most tmux actions use the prefix Ctrl+b: press and release it, then press the action key.
| Action | Keys |
|---|---|
| Detach and leave the session running |
Ctrl+b, then d
|
| Create a window |
Ctrl+b, then c
|
| Next or previous window |
Ctrl+b, then n or p
|
| Split a window side by side |
Ctrl+b, then %
|
| Split a window into stacked panes |
Ctrl+b, then "
|
| Move between panes |
Ctrl+b, then an arrow key |
| Close the active pane |
Ctrl+b, then x
|
A window is a workspace inside a session. A pane divides a window into multiple terminals. Closing a pane ends the shell running in it, so check which pane is active before confirming the prompt. You can also type exit in a pane when you are finished with its shell.
Copying text to the Mac clipboard
On macOS, tmux’s copy buffer and the system clipboard are separate. Copying a selection in tmux does not necessarily make it available to paste into another Mac app.
To select text in the default copy mode, press Ctrl+b, then [; move with the arrow keys, press Space to start selecting, and press Enter to copy into tmux’s buffer. To send that buffer to the Mac clipboard, run:
tmux show-buffer | pbcopy
pbcopy writes standard input to the macOS clipboard. You can then paste into another app normally.
There’s a location detail to watch for: if tmux is running on a remote server, a command inside that session runs on the server. pbcopy is a macOS utility, so running it remotely does not directly write to your Mac’s clipboard. The tmux buffer and the Mac clipboard are on different machines unless you set up a clipboard-forwarding method.
Troubleshooting a couple of common snags
tmux: command not found
Check whether Homebrew lists tmux and whether your shell can locate it:
brew list tmux
command -v tmux
If it is installed but command -v prints nothing, open a new terminal window and check again. If the problem remains, check your Homebrew shell setup and PATH rather than guessing where the executable lives.
The wrong tmux version starts
Run command -v tmux to see which executable is selected. This can reveal an older copy earlier in your PATH, or different installations managed by Homebrew and MacPorts.
SSH agent access behaves differently in an existing session
Long-running tmux sessions can retain environment variables from when they started. If SSH key access is the issue, first identify which machine and shell are running the command; SSH_AUTH_SOCK and agent sockets are a useful next step for understanding how an SSH agent is reached.
A practical way to think about it
Use local tmux when you want multiple terminal workspaces on your Mac. Use tmux on a remote machine when you want the server-side session to keep running through a dropped SSH connection. In either case, name sessions, detach instead of closing them, and reconnect with tmux attach-session -t name.
I originally published a more detailed version of this guide on the SSHFlow blog.
I'm also building SSHFlow — an SSH client where every server gets its own workspace for terminals, SFTP, code, and databases.
Top comments (0)