tmux Complete Guide: Terminal Multiplexing for Developers

tmux is a terminal multiplexer that lets you run multiple shell sessions inside a single window, split panes side by side, and keep everything alive even when your SSH connection drops. Install it with apt install tmux or brew install tmux, and start a session with tmux new -s myproject.

"My SSH connection dropped and killed the build." "I have twenty terminal tabs open and can't tell them apart." "Switching between my editor, dev server, and test runner is getting old."

If any of these sound familiar, tmux is the answer. It lets you manage multiple virtual terminals inside a single window, and your sessions survive SSH disconnects. Once you start using it, you won't go back.

What is tmux?

tmux (terminal multiplexer) is a tool that lets you run and manage multiple terminal sessions inside one window. It's open source under the ISC license and widely used on Linux and macOS. The tmux wiki is the go-to resource for in-depth documentation.

You may have heard of GNU Screen — tmux is its modern successor with more features and far more flexible configuration. In today's developer community, tmux is the standard choice.

The biggest benefit of tmux is session persistence. When your SSH connection drops, processes keep running on the tmux server. Reconnect, reattach to your session, and everything is exactly where you left it. Long builds and deployments are safe even on flaky connections.

tmux organizes your workspace in three layers:

• Session: a named group of work. Typically one session per project
• Window: like a tab within a session. One session can hold many windows
• Pane: a subdivision of a window. Multiple shells side by side in one view

Session: "dev"
├── Window 0: "editor"
│   ├── Pane 0: vim
│   └── Pane 1: file browser
├── Window 1: "server"
│   └── Pane 0: npm run dev
└── Window 2: "test"
    ├── Pane 0: test runner
    └── Pane 1: log tail

Installation

# WSL (Ubuntu)
sudo apt install tmux

Verify the installation:

tmux -V
# tmux 3.6a

Core concepts: Sessions, windows, and panes

Every tmux operation starts with the prefix key. The default prefix is Ctrl+b. When you see prefix below, it means press Ctrl+b first, then the next key.

Session operations

Sessions are the top-level unit. Create one per project or task.

# Create a named session
tmux new -s work

# List sessions
tmux ls

# Attach to a session (reconnect)
tmux attach -t work
# Short form
tmux a -t work

# Kill a session
tmux kill-session -t work

Inside a session:

• prefix d — Detach (leave the session; processes keep running in the background)
• prefix s — List and switch sessions
• prefix $ — Rename the current session

Window operations

Windows are like browser tabs. They appear in the status bar at the bottom.

• prefix c — Create a new window
• prefix n — Next window
• prefix p — Previous window
• prefix 0-9 — Jump to window by number
• prefix w — Tree view of all windows for selection
• prefix , — Rename the current window
• prefix & — Close the current window (with confirmation)

Pane operations

Panes split a window so you can see multiple shells at once — perfect for running an editor next to a terminal.

• prefix % — Split left/right
• prefix " — Split top/bottom
• prefix Arrow — Move between panes
• prefix Ctrl+Arrow — Resize panes (press repeatedly)
• prefix z — Toggle zoom (fullscreen the current pane)
• prefix x — Close the current pane (with confirmation)
• prefix Space — Cycle through layouts

Copy mode

To scroll back through output or select text inside tmux, enter copy mode.

• prefix [ — Enter copy mode
• q — Exit copy mode
• prefix ] — Paste buffer contents

With vi mode enabled (see .tmux.conf below):

1. prefix [ to enter copy mode
2. Space to start selection
3. Arrow keys or hjkl to extend the selection
4. Enter to copy (yanks to buffer)
5. prefix ] to paste

Key bindings cheat sheet

A quick reference for common operations. All keys are pressed after prefix.

Sessions:

Windows:

Panes:

Other:

Customizing with .tmux.conf

The tmux config file lives at ~/.tmux.conf. The default key bindings are frankly hard to remember, so customizing tmux to match your muscle memory is the key to using it long-term.

Here's a practical config. Pick the parts that make sense for your workflow.

# -------------------------------------------
# Change prefix to Ctrl+a
# -------------------------------------------
# Same as GNU Screen and easier to reach than Ctrl+b
unbind C-b
set -g prefix C-a
bind C-a send-prefix

# -------------------------------------------
# Intuitive pane splitting
# -------------------------------------------
# | for horizontal, - for vertical. New panes inherit the current directory
bind | split-window -h -c "#{pane_current_path}"
bind - split-window -v -c "#{pane_current_path}"
unbind '"'
unbind %

# -------------------------------------------
# Vim-style pane navigation
# -------------------------------------------
bind h select-pane -L
bind j select-pane -D
bind k select-pane -U
bind l select-pane -R

# -------------------------------------------
# Enable mouse support
# -------------------------------------------
set -g mouse on

# -------------------------------------------
# Start window and pane numbers at 1
# -------------------------------------------
set -g base-index 1
setw -g pane-base-index 1

# -------------------------------------------
# Renumber windows when one is closed
# -------------------------------------------
set -g renumber-windows on

# -------------------------------------------
# 256-color support
# -------------------------------------------
set -g default-terminal "screen-256color"
set -sa terminal-overrides ",xterm-256color:RGB"

# -------------------------------------------
# Vi key bindings in copy mode
# -------------------------------------------
setw -g mode-keys vi

# -------------------------------------------
# Increase scrollback history
# -------------------------------------------
set -g history-limit 10000

# -------------------------------------------
# Status bar customization
# -------------------------------------------
set -g status-style 'bg=colour235 fg=colour136'
set -g status-left '#[fg=green]#S '
set -g status-right '%Y-%m-%d %H:%M'
set -g status-left-length 20

After editing the file, reload it from within tmux:

# From the shell
tmux source-file ~/.tmux.conf

# From the tmux command prompt
# Press prefix : and type
source-file ~/.tmux.conf

Real-world workflows

Knowing the basics is one thing — putting them to work is another. Here are four patterns that make tmux indispensable in practice.

SSH safety net

This is where tmux shines brightest. Your processes survive SSH disconnects, so long builds and deployments run safely even on unreliable connections. If you're managing remote servers regularly, pair tmux with ssh and rsync for a solid workflow.

# SSH into your server
ssh user@server.example.com

# Start a tmux session
tmux new -s deploy

# Run a long deployment
./deploy.sh

# Optionally detach if the connection is flaky
# prefix d

# --- connection drops / come back later ---

# Reconnect
ssh user@server.example.com

# Reattach — everything is still there
tmux a -t deploy

One-command dev environment

Setting up the same window layout by hand every day is a waste of time. Script it. If you're not comfortable with shell scripting yet, this is a great first project.

#!/bin/bash
# dev-tmux.sh — spin up a dev tmux session in one command

SESSION="dev"
PROJECT_DIR="$HOME/projects/myapp"

# If the session already exists, just attach
tmux has-session -t $SESSION 2>/dev/null && {
  tmux attach -t $SESSION
  exit 0
}

# Create session in detached mode
tmux new-session -d -s $SESSION -c $PROJECT_DIR

# Pane 0: editor
tmux send-keys 'vim .' C-m

# Split right: dev server
tmux split-window -h -c $PROJECT_DIR
tmux send-keys 'npm run dev' C-m

# Split bottom-right: test watcher
tmux split-window -v -c $PROJECT_DIR
tmux send-keys 'npm run test -- --watch' C-m

# Focus back on the editor pane
tmux select-pane -t 0

# Attach
tmux attach -t $SESSION

# Make it executable and run
chmod +x dev-tmux.sh
./dev-tmux.sh

Simultaneous multi-server operations

With synchronize-panes, every keystroke is sent to all panes at once. Run the same command across multiple servers in parallel.

# Create panes for each server
tmux new -s servers
tmux split-window -h
tmux split-window -v
tmux select-pane -t 0

# SSH into each server from its pane
# Pane 0: ssh web1.example.com
# Pane 1: ssh web2.example.com
# Pane 2: ssh web3.example.com

# Enable synchronized input
# Press prefix : and type
setw synchronize-panes on

# Now every keystroke goes to all panes simultaneously
# e.g. sudo apt update && sudo apt upgrade -y

# Turn it off when done
setw synchronize-panes off

Pair programming

Multiple terminals can attach to the same tmux session simultaneously. This lets teammates share a screen and collaborate in real time on the same server.

# Developer A creates the session
tmux new -s pair

# Developer B attaches to the same session
tmux attach -t pair

# Both see and can type in real time

When terminals with different sizes attach to the same session, tmux shrinks to the smallest. Use the same terminal size, or run tmux attach -d -t pair to detach any existing connections first.

Advanced techniques

Automating with tmux hooks

Tmux hooks let you auto-run commands when specific events occur.

# Sync pane path when creating a new window
tmux set-hook -g after-new-window 'send-keys "cd #{pane_current_path}" C-m'

# Set status bar color on session creation
tmux set-hook -g session-created 'set status-style bg=colour235'

set-hook -g sets global hooks, while set-hook is session-scoped. Events include after-split-window, pane-focus-in, client-attached, and many more.

Floating windows with display-popup (tmux 3.2+)

tmux 3.2+ introduced display-popup for floating windows. Great for quick one-off commands.

# Open a floating window to take notes
tmux display-popup -E 'vim ~/notes.md'

# Switch sessions via fzf in a popup
tmux display-popup -E 'tmux list-sessions -F "#{session_name}" | fzf | xargs tmux switch-client -t'

Bind it in .tmux.conf for one-key access:

# prefix + g launches session switcher
bind g display-popup -E 'tmux list-sessions -F "#{session_name}" | fzf | xargs tmux switch-client -t'

Saving pane content with capture-pane

capture-pane captures the visible content of a pane into a buffer. Useful for logging and debugging.

# Save current pane content to a file
tmux capture-pane -pS - > ~/tmux-output.log

# Capture the full scrollback buffer (past 5000 lines)
tmux capture-pane -pS -5000 > ~/full-log.txt

-p prints the buffer to stdout, -S - captures from the start of the scrollback.

Batch operations with send-keys

send-keys lets you inject keystrokes into panes from external scripts. Useful for CI/CD and test automation.

# Send a command to a specific pane
tmux send-keys -t dev:0.1 'npm run build' C-m

# Send the same command to all panes (without synchronize-panes)
for pane in $(tmux list-panes -F '#{pane_id}'); do
  tmux send-keys -t "$pane" 'echo "pane: $TMUX_PANE"' C-m
done

Extending tmux with plugins (TPM)

TPM (Tmux Plugin Manager) is the standard way to manage tmux plugins. It handles installation, updates, and cleanup automatically.

Installing TPM

git clone https://github.com/tmux-plugins/tpm ~/.tmux/plugins/tpm

Add the following to the bottom of your .tmux.conf:

# List of plugins
set -g @plugin 'tmux-plugins/tpm'
set -g @plugin 'tmux-plugins/tmux-sensible'
set -g @plugin 'tmux-plugins/tmux-resurrect'

# Initialize TPM (keep this line at the very bottom)
run '~/.tmux/plugins/tpm/tpm'

Then press prefix + I (capital I) inside tmux to install the plugins.

Recommended plugins

• tmux-resurrect — save and restore tmux sessions across reboots. prefix + Ctrl-s to save, prefix + Ctrl-r to restore
• tmux-continuum — automatic session saving every 15 minutes, with optional auto-restore on tmux start
• tmux-yank — copy to system clipboard from tmux copy mode

FAQ

How do I scroll up in tmux?

Press prefix [ to enter copy mode, then use arrow keys or Page Up/Down to scroll. If you have set -g mouse on in your config, you can also scroll with your mouse wheel. Press q to exit copy mode.

What is the difference between tmux and GNU Screen?

tmux offers a more modern codebase, better scripting support, client-server architecture, and more flexible layouts. Screen has been around longer (since 1987), but its development has slowed significantly. Most developers who start fresh today choose tmux.

Can I use tmux inside tmux (nested sessions)?

Yes. When you SSH into a remote server that also runs tmux, you end up with nested sessions. Use prefix prefix <key> (press prefix twice) to send commands to the inner session, or rebind the inner tmux prefix to a different key to avoid confusion.

How do I resize panes in tmux?

Press prefix Ctrl+Arrow to resize in the arrow direction. Alternatively, with mouse mode enabled (set -g mouse on), drag the pane border. You can also use the command tmux resize-pane -D 5 to resize by a specific number of lines.

Does tmux work on macOS?

Yes. Install it with brew install tmux. macOS ships without tmux by default, but Homebrew makes installation trivial. For clipboard integration, add set -g default-command "reattach-to-user-namespace -l $SHELL" or use tmux-yank.

How do I save and restore tmux sessions?

tmux sessions survive disconnects but not reboots. Install tmux-resurrect via TPM to save (prefix + Ctrl-s) and restore (prefix + Ctrl-r) your entire session layout including pane contents and running programs.

What is the tmux prefix key and how do I change it?

The prefix key (default Ctrl+b) is the leader key that precedes all tmux commands. Many users rebind it to Ctrl+a (matching GNU Screen) by adding unbind C-b; set -g prefix C-a; bind C-a send-prefix to .tmux.conf. See the tmux man page for all available options.

Related Articles

• fzf Complete Guide — supercharge search with tmux + fzf
• Shell Alias Complete Guide — shorten tmux commands with aliases
• Modern Rust CLI Tools — make your terminal even more modern
• CLI Toolkit — a quick-reference map of all commands

Wrapping Up

tmux answers a straightforward need: using your terminal more efficiently.

Key takeaways:

• Three layers (Session → Window → Pane) give you a mental model that makes every command intuitive
• Session persistence is your safety net for remote work
• .tmux.conf lets you remap prefix keys, pane navigation, and appearance to suit your habits
• Scripted sessions automate dev environment setup so you never waste time on it again

Start with the prefix key and basic pane splitting. As you get comfortable, grow your .tmux.conf one setting at a time.