Tmux: A Complete Guide to Terminal Multiplexing

Tmux is a terminal multiplexer — it lets you run multiple terminal sessions inside a single window, detach and reattach them later, and split your screen into panes. If you spend significant time in the terminal, tmux is one of the highest-ROI tools you can learn. It gives you the power of a full IDE terminal experience right inside your SSH session or local terminal.

The core value proposition is persistence. You can start a tmux session on a remote server, detach it, close your laptop, reconnect the next day, and find everything exactly as you left it. No more lost work when your SSH connection drops. No more juggling multiple terminal windows.

Sessions, Windows, and Panes

Tmux has three tiers: sessions (project-level containers), windows (like tabs), and panes (splits inside a window).

Session: myproject
├── Window: editor (vim)
│   ├── Pane 1: code
│   └── Pane 2: file tree
├── Window: server
│   └── Pane 1: dev server logs
└── Window: git
    ├── Pane 1: git status
    └── Pane 2: terminal

Sessions

Use one session per project.

tmux new -s myproject          # Create a new named session
tmux ls                        # List all sessions
tmux attach -t myproject       # Attach to an existing session
tmux kill-session -t myproject # Kill a session

Windows

Windows work like tabs. Inside a session, you can create and switch between windows freely.

Panes

Panes let you split a window into multiple terminal regions — perfect for side-by-side editing or watching logs while you work.

Getting Started

Install tmux on your system:

# macOS
brew install tmux

# Ubuntu / Debian
sudo apt install tmux

# Fedora
sudo dnf install tmux

# Arch
sudo pacman -S tmux

# Verify
tmux -V

Start your first session:

tmux new -s demo

You are now inside tmux. The status bar shows your session name and window list. Try splitting: Ctrl+b then % for vertical, Ctrl+b then " for horizontal. Navigate with Ctrl+b + arrow keys.

Customizing Tmux

Tmux is configured through ~/.tmux.conf. The default prefix Ctrl+b can be remapped. Here is a solid starting configuration:

# ~/.tmux.conf
set -g prefix C-a                    # Use Ctrl+a instead of Ctrl+b
unbind C-b
bind C-a send-prefix
set -g mouse on                      # Mouse support
set -g base-index 1                  # Start numbering at 1
set -g history-limit 50000           # Large scrollback
set -g default-terminal "tmux-256color"
bind r source-file ~/.tmux.conf \; display "Config reloaded"

# Split keys
bind | split-window -h
bind - split-window -v

Status Bar Customization

The tmux status bar is highly customizable. Display session name, window list, time, date, and system information:

set -g status-bg colour235
set -g status-fg colour250
set -g status-left '#[fg=green]#S #[fg=white]|'
set -g status-right '#[fg=yellow]%Y-%m-%d %H:%M #[fg=cyan]#h'
set -g window-status-current-style fg=white,bg=blue

You can add battery, CPU, and network information using plugins or custom shell commands in the status-right option.

Advanced Workflows

Session Management

Automate project setup with a script:

#!/bin/bash
# ~/bin/tmux-project.sh

SESSION="myproject"

tmux has-session -t $SESSION 2>/dev/null
if [ $? != 0 ]; then
    tmux new-session -d -s $SESSION -n "editor"
    tmux send-keys -t $SESSION "cd ~/projects/myproject && nvim" C-m

    tmux new-window -t $SESSION -n "server"
    tmux send-keys -t $SESSION:2 "cd ~/projects/myproject && npm run dev" C-m

    tmux new-window -t $SESSION -n "git"
    tmux send-keys -t $SESSION:3 "cd ~/projects/myproject && git status" C-m

    tmux select-window -t $SESSION:1
fi

tmux attach -t $SESSION

Run tmux-project.sh once and your entire development environment is ready — editor, server, and git terminal all in the right directories.

Copy Mode and Scrolling

Tmux’s scrollback buffer lets you navigate through output history:

In copy mode, you can use vi or emacs key bindings depending on your mode-keys setting. With vi bindings: j/k to scroll line by line, Ctrl+d/Ctrl+u to page, g/G to jump to top/bottom.

Creating Custom Key Bindings

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

# Quick pane navigation with Alt+arrow
bind -n M-Left select-pane -L
bind -n M-Right select-pane -R
bind -n M-Up select-pane -U
bind -n M-Down select-pane -D

# Resize panes with prefix + H/J/K/L
bind -r H resize-pane -L 5
bind -r J resize-pane -D 5
bind -r K resize-pane -U 5
bind -r L resize-pane -R 5

The -n flag makes the binding work without the prefix key. The -r flag allows the key to be repeated.

Tmux on Remote Servers

Tmux truly shines when you are working on remote machines. The workflow:

1. SSH into your server
2. Start or reattach a tmux session
3. Work as usual
4. Detach (Ctrl+b d) when you close your laptop
5. Reattach later — everything is still running

This pattern eliminates the fear of disconnects during long-running operations. Deployments, database migrations, and data processing jobs can run unattended in tmux while you safely close your terminal.

Persistent Remote Sessions

For 24/7 remote sessions, combine tmux with systemd or a cron job:

# Auto-start tmux on SSH login
if command -v tmux &> /dev/null; then
    if [ -z "$TMUX" ] && [ -n "$SSH_CONNECTION" ]; then
        tmux attach -t remote || tmux new -s remote
    fi
fi

Add this to your server’s ~/.bashrc to automatically attach to or create a tmux session whenever you SSH in.

Common Tmux Commands Reference

tmux new -s name       # New session
tmux ls                # List sessions
tmux attach -t name    # Attach to session
tmux kill-session -t n # Kill session
tmux rename-session -t old new
tmux list-keys         # Show all key bindings
tmux list-commands     # Show all commands
tmux info              # Show session info

Troubleshooting

“Open terminal failed: missing or unsuitable terminal”

Set your terminal type explicitly in ~/.tmux.conf:

set -g default-terminal "screen-256color"

Colors look wrong

Ensure your terminal emulator supports 256 colors and set:

set -g default-terminal "tmux-256color"

Also check that your TERM environment variable is set correctly outside tmux. Some terminal emulators need export TERM=xterm-256color in your shell config.

Mouse scrolling doesn’t work

Enable mouse support:

set -g mouse on

On some systems, you may also need to configure your terminal to send mouse events. For iTerm2 on macOS, enable “Applications in terminal may access mouse” in preferences.

Status bar not updating

The status bar refreshes every 15 seconds by default. If your custom status bar scripts are slow, increase the interval: set -g status-interval 5. For expensive commands (like battery status), cache the output or use a background process.

FAQ

What is the difference between tmux and a terminal emulator like iTerm2?

A terminal emulator displays the terminal window and manages tabs. tmux runs inside the terminal and adds session persistence, pane splitting, and detachment. You can use tmux inside any terminal emulator, including iTerm2, Konsole, or Windows Terminal.

How do I save and restore tmux sessions after a reboot?

Install tmux-resurrect and tmux-continuum via TPM. Resurrect saves the complete session state (windows, panes, layouts) to disk. Continuum auto-saves every 15 minutes and auto-restores on tmux start.

Can I run tmux inside tmux (nested sessions)?

Yes, but you need to configure a different prefix key for the inner session. Press the outer prefix twice to send commands to the inner tmux. Most users avoid nesting as it creates confusion.

How do I share my tmux session for pair programming?

Use tmux new-session -s shared and then tmux attach -t shared from another terminal. Both users see the same terminal output. For write access, use socket sharing: start with tmux -S /tmp/shared new-session -s pair.

Why does tmux use so much memory?

Tmux keeps scrollback history in memory. Reduce history-limit from 50000 to 10000 if memory is a concern. Each pane stores its own buffer, so many panes with large scrollbacks add up.

Related: See our SSH keys guide and VS Code shortcuts.