How to Use tmux

tmux is a terminal multiplexer: it lets you run multiple terminal sessions inside a single window, detach from them without killing processes, and reattach later from any login. That last property makes it indispensable for long-running jobs on remote servers, but it's just as useful on a local workstation for keeping your workflow organized. This guide covers the daily-driver features: sessions, windows, panes, detach/reattach, and a sane ~/.tmux.conf to make it feel like home.

Installing tmux

Most distros ship a reasonably current version. Anything 3.x is fine for everything covered here.

# Debian / Ubuntu
sudo apt install tmux

# Fedora / RHEL 9+ / Rocky
sudo dnf install tmux

# Arch
sudo pacman -S tmux

tmux -V
# tmux 3.3a

The Prefix Key

Every tmux keybinding is a two-step chord: press the prefix, release it, then press the command key. The default prefix is Ctrl-b. This guide writes that as prefix. For example, "prefix d" means press Ctrl-b, release, then press d.

Many people remap the prefix to Ctrl-a (the GNU Screen default) or Ctrl-Space. We'll do that in the config section.

Sessions

A session is the top-level container. You can have multiple independent sessions, each with its own set of windows. Sessions persist until the tmux server is killed or you explicitly destroy them — not when you close your terminal.

Starting and naming a session

tmux new-session -s work

Always name sessions. Without a name tmux assigns a number, and tmux attach with multiple unnamed sessions becomes guesswork.

Detaching and reattaching

Detach from the current session without killing anything running inside it:

# Keyboard shortcut inside tmux
prefix d

Reattach later, from the same machine or a new SSH login:

tmux attach-session -t work

If there is only one session, tmux attach (no flags) suffices.

Listing and switching sessions

tmux list-sessions
# work: 2 windows (created Mon Jun  2 10:14:22 2025)

# From inside tmux: open the session chooser
prefix s

The session chooser is a navigable list. Arrow keys move the cursor; Enter switches to the selected session.

Creating and killing sessions

# New session without leaving the current one (from inside tmux)
prefix :new-session -s logs

# Kill a named session from the shell
tmux kill-session -t logs

Windows

Windows are tabs within a session. Each window occupies the full terminal area and runs one or more panes.

Creating and navigating windows

• prefix c — create a new window
• prefix , — rename the current window
• prefix n / prefix p — next / previous window
• prefix 0-9 — jump to window by number
• prefix w — visual window list (works across sessions)

Rename every window immediately after creating it. A status bar showing 0:vim 1:server 2:logs is far more useful than 0:bash 1:bash 2:bash.

Closing a window

Exit all shells in the window, or use:

prefix &

tmux will ask for confirmation before closing.

Panes

Panes split a window into independent terminal regions. They're ideal for side-by-side editing and output monitoring.

Splitting

• prefix % — split vertically (left | right)
• prefix " — split horizontally (top / bottom)

Moving between panes

• prefix ←↑→↓ — move by arrow key
• prefix o — cycle through panes
• prefix q — briefly show pane numbers; press a number to jump

Resizing panes

# Hold prefix and tap an arrow key to resize one cell at a time
prefix Ctrl-←  # resize left
prefix Ctrl-→  # resize right

For larger jumps, enter command mode with prefix : and run resize-pane -R 20 (right 20 cells) or -D 10 (down 10 rows).

Zooming a pane

prefix z

This toggles the current pane to full-screen. Press prefix z again to restore the split layout. Useful when you need to read a wall of output without closing other panes.

Closing a pane

Type exit in the pane's shell, or:

prefix x

Copy Mode and Scrollback

tmux has its own scrollback buffer. Enter copy mode to scroll, search, and yank text:

prefix [

In copy mode, arrow keys and Page Up/Page Down scroll. Press / to search forward, ? to search backward. Press q to exit copy mode. By default the keybindings are emacs-style; adding set-window-option -g mode-keys vi to your config switches to vi bindings (Space to start selection, Enter to copy).

The Configuration File

tmux reads ~/.tmux.conf at startup. Changes take effect after prefix :source-file ~/.tmux.conf or restarting the server. Here is a practical baseline:

cat > ~/.tmux.conf <<'EOF'
# Remap prefix to Ctrl-a
unbind C-b
set-option -g prefix C-a
bind-key C-a send-prefix

# Reload config with prefix r
bind r source-file ~/.tmux.conf \; display "Config reloaded"

# More intuitive splits (same directory)
bind | split-window -h -c "#{pane_current_path}"
bind - split-window -v -c "#{pane_current_path}"
unbind '"'
unbind %

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

# Vi copy mode
set-window-option -g mode-keys vi
bind-key -T copy-mode-vi v send-keys -X begin-selection
bind-key -T copy-mode-vi y send-keys -X copy-selection-and-cancel

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

# Start windows and panes at 1, not 0
set -g base-index 1
setw -g pane-base-index 1

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

# Enable mouse support
set -g mouse on

# Nicer status bar
set -g status-style 'bg=#1e1e2e fg=#cdd6f4'
set -g status-left '[#S] '
set -g status-right ' %H:%M %d-%b'
EOF

After saving, reload without restarting:

tmux source-file ~/.tmux.conf

Practical Workflow: Long-Running Remote Job

1. SSH into the server.
2. Start a named session: tmux new-session -s deploy
3. Run your job: ./run_migration.sh
4. Detach: prefix d
5. Close the SSH connection. The job keeps running.
6. SSH back in later: tmux attach-session -t deploy

This is tmux's killer feature on servers. Combine it with systemd-run --user for truly persistent services, but for interactive jobs that need a terminal, tmux is the right tool.

Verification

# Confirm a session survives logout/login by checking from outside tmux
tmux list-sessions

You should see your named session listed. If the tmux server exited (e.g., after a reboot), the session is gone — tmux is not a persistent service by default. For that, combine it with a @reboot cron entry or a systemd user service.

Troubleshooting

"sessions should be nested with care"

This warning appears when you run tmux inside an existing tmux session. Use prefix s to switch sessions instead of nesting. If you genuinely need nesting, set a different prefix for the inner instance.

Colors look wrong or 256-color themes are broken

Add set -g default-terminal "tmux-256color" and set -ga terminal-overrides ",xterm-256color:Tc" to ~/.tmux.conf. Also ensure your outer terminal (Alacritty, Kitty, GNOME Terminal) advertises 256 or truecolor support.

Clipboard doesn't work between tmux and the system

On Wayland, install wl-clipboard and add bind-key -T copy-mode-vi y send-keys -X copy-pipe-and-cancel 'wl-copy'. On X11, use xclip or xsel in the pipe instead.

Prefix key conflicts with another application

Change the prefix in ~/.tmux.conf. Ctrl-Space (set-option -g prefix C-Space) rarely collides with anything.