Tmux Terminal Multiplexer Guide: Sessions, Panes, and Configuration

Why a Terminal Multiplexer?

Tmux is a terminal multiplexer — it lets you run multiple terminal sessions in one window, detach and reattach sessions, and split panes. If you've ever lost work because an SSH connection dropped, tmux solves that permanently.

This guide covers everything: sessions, panes, windows, configuration, and the workflow patterns that make tmux indispensable.

By the end of this 18-min guide, you'll never need to open more than one terminal window again.

• Run multiple shells in a single terminal window
• Detach sessions and resume them later — even after reboot
• Split panes vertically and horizontally for side-by-side work
• Customize tmux.conf to match your muscle memory

Installing Tmux & First Session

Install tmux with your package manager. On macOS:

brew install tmux

On Ubuntu/Debian:

sudo apt install tmux

• tmux 3.4 or later (check with tmux -V)
• A terminal that supports 256 colors
• No prior tmux experience needed
• Optional: a tmux config to start from (we'll build one)

Sessions, Windows & Panes

Tmux has a nested hierarchy: sessions contain windows, windows contain panes. Understanding this is the key to everything else.

• tmux new -s work — create a session named "work"
• tmux ls — list all sessions
• tmux attach -t work — reattach to the "work" session
• tmux kill-session -t old — destroy a session

Windows are like tabs. Panes are splits within a window. The default prefix is Ctrl-b — you press it, release, then press the next key.

# Key bindings (prefix is Ctrl-b)
Ctrl-b c        # new window
Ctrl-b ,        # rename window
Ctrl-b 0-9      # switch to window N
Ctrl-b %        # split pane vertically
Ctrl-b "        # split pane horizontally
Ctrl-b o        # cycle to next pane
Ctrl-b d        # detach session

Daily Session Workflow

The real power of tmux is persistent sessions. Start a session on a remote server, run a build, detach, go home, and reattach to see the result.

• Project sessions: One session per project, with panes for editor, server, and logs
• SSH survival: Always run tmux on remote servers — if your connection drops, your work survives
• Pair programming: tmux -S /tmp/pair lets two people share a session
• Session scripts: Use tmuxinator or a shell script to recreate your ideal layout

Custom Keybindings & Prefix

Your ~/.tmux.conf is where tmux becomes yours. Here's a battle-tested config to start with:

# Change prefix to Ctrl-a (closer to home row)
set -g prefix C-a
unbind C-b
bind C-a send-prefix
# Split panes more intuitively
bind | split-window -h
bind - split-window -v
# Reload config with Ctrl-a r
bind r source-file ~/.tmux.conf \; display "Reloaded!"
# Mouse support
set -g mouse on
# 256 colors
set -g default-terminal "tmux-256color"
set -ag terminal-overrides ",xterm-256color:RGB"

• Remap the prefix to something comfortable (Ctrl-a is popular)
• Set up reload keybinding so you don't restart tmux to test config
• Enable mouse for pane selection and scrolling
• Use TPM to manage plugins (see [[Tmux Plugin Manager]])

Config Not Loading?

Common issues and their fixes:

• Colors look wrong? Set default-terminal "tmux-256color" and add the terminal-overrides line
• Paste is slow? Use set -g set-clipboard on and install reattach-to-user-namespace on macOS
• Config not loading? Run tmux source ~/.tmux.conf or use your reload keybinding
• Can't scroll? Enter copy mode with Ctrl-b [, then use Page Up/Down

Tmux as Second Nature

You've mastered the basics. Here's how to go further:

• Install TPM and plugins like tmux-resurrect (see [[Tmux Plugin Manager]])
• Design a custom status bar (see [[Tmux Custom Status Bar]])
• Memorize the full cheat sheet (see [[Tmux Cheat Sheet 2026]])
• Try Zellij as a modern alternative (see [[Zellij Terminal Workspace Guide]])