Tmux Terminal Multiplexer

tmux cheatsheet — terminal multiplexer for persistent sessions. Prefix+c new window, Prefix+% split pane, Prefix+d detach, tmux attach. Sessions survive SSH disconnects.

7 min read

What it is

Tmux is a terminal multiplexer that allows you to create, manage, and switch between multiple terminal sessions, windows, and panes within a single terminal window, enabling persistent sessions that survive disconnects.

Installation

Linux

sudo apt update && sudo apt install tmux # Debian/Ubuntu
sudo dnf install tmux # Fedora
sudo yum install tmux # CentOS/RHEL

macOS

brew install tmux

Windows

Using Windows Subsystem for Linux (WSL):

  1. Install WSL.
  2. Open your WSL distribution.
  3. Follow the Linux installation instructions.

Using a native Windows terminal emulator that supports multiplexing (less common, consider WSL for the full experience).

Core Concepts

  • Session: A collection of windows. Tmux can run multiple independent sessions.
  • Window: A single screen within a session, analogous to a tab in a browser. Each window has a name and a number.
  • Pane: A rectangular subdivision of a window. A window can be split into multiple panes.
  • Prefix Key: A special key combination that precedes all tmux commands. By default, it’s Ctrl+b. You press the prefix, release it, then press the command key.

Commands / Usage

All commands below assume the default prefix Ctrl+b. If you’ve changed it, substitute your prefix key.

Session Management

  • Start a new session:

    tmux new-session -s my_session_name

    Starts a new tmux session named my_session_name.

  • List all sessions:

    tmux ls

    Shows all active tmux sessions with their names and process IDs.

  • Attach to an existing session:

    tmux attach-session -t my_session_name

    Connects to the session named my_session_name.

  • Detach from a session: Press Prefix then d. Leaves the current session running in the background and returns you to your original shell.

  • Kill a session:

    tmux kill-session -t my_session_name

    Terminates the session named my_session_name.

  • Kill all sessions:

    tmux kill-server

    Shuts down the tmux server and all running sessions.

Window Management

  • Create a new window: Press Prefix then c. Creates a new window in the current session.

  • List windows: Press Prefix then w. Displays a list of all windows in the current session, allowing you to select one.

  • Rename current window: Press Prefix then ,. Prompts you to enter a new name for the current window.

  • Switch to the next window: Press Prefix then n. Navigates to the next window in the session.

  • Switch to the previous window: Press Prefix then p. Navigates to the previous window in the session.

  • Switch to a specific window by number: Press Prefix then <window_number>. For example, Prefix then 0 switches to window 0.

  • Close the current window: Press Prefix then &. Confirms before closing the current window.

Pane Management

  • Split the current pane vertically: Press Prefix then %. Divides the current pane into two panes side-by-side.

  • Split the current pane horizontally: Press Prefix then ". Divides the current pane into two panes, one above the other.

  • Navigate between panes: Press Prefix then an arrow key (↑, ↓, ←, →). Moves the cursor to the adjacent pane in the specified direction.

  • Close the current pane: Press Prefix then x. Confirms before closing the current pane.

  • Zoom the current pane: Press Prefix then z. Toggles between making the current pane fill the entire window and restoring the previous layout.

  • Resize pane (adjust size by 1 cell): Press Prefix then Ctrl + arrow key (↑, ↓, ←, →). Shrinks or expands the current pane by one unit in the direction of the arrow.

  • Resize pane (adjust size by 5 cells): Press Prefix then Alt + arrow key (↑, ↓, ←, →). Shrinks or expands the current pane by five units in the direction of the arrow.

  • Swap pane with the next one: Press Prefix then { or }. Moves the current pane to the next or previous position in the window’s layout.

  • Set pane to a specific layout: Press Prefix then ; followed by a layout name (e.g., even-horizontal, main-vertical). Applies a predefined layout to the current window’s panes.

Other Useful Commands

  • Enter command mode: Press Prefix then :. Opens a command prompt at the bottom of the screen to execute tmux commands.

  • Copy mode: Press Prefix then [ (or Prefix then Esc to enter copy mode, then [ to scroll back). Allows you to scroll through buffer history and select text for copying.

    • Use arrow keys or hjkl to navigate.
    • Press Space to start selection.
    • Press Enter to end selection and copy to buffer.
    • Press Esc to exit copy mode.

  • Paste from buffer: Press Prefix then ]. Pastes the content of the current tmux buffer.

  • List all key bindings: Press Prefix then ?. Displays a list of all available key bindings.

  • Synchronize panes: Press Prefix then s. Toggles input synchronization across all panes in the current window. When enabled, typing in one pane is echoed to all others.

Common Patterns

  • Running a command in all panes:

    # Example: Ping google.com in all panes of current window
tmux setw synchronize-panes on \; send-keys 'ping google.com' Enter \; setw synchronize-panes off

    This command turns on pane synchronization, sends the ping google.com command and presses Enter to all panes, then turns synchronization off.

  • Creating a vertical split and running a command:

    tmux split-window -h -p 50 'htop'

    Creates a new pane that takes 50% of the width and runs htop in it. -h for horizontal split (vertical pane).

  • Creating a horizontal split and running a command:

    tmux split-window -v -p 30 'tail -f /var/log/syslog'

    Creates a new pane that takes 30% of the height and runs tail -f /var/log/syslog in it. -v for vertical split (horizontal pane).

  • Attaching to a session and executing a command:

    tmux attach-session -t my_session_name \; send-keys 'docker ps' Enter

    Attaches to my_session_name and immediately runs docker ps.

  • Creating a new session with pre-defined windows and panes: Create a .tmux.conf file or use a script:

    tmux new-session -d -s my_project 'vim main.py'
tmux split-window -h 'git status'
tmux select-pane -t 0
tmux split-window -v 'docker-compose logs -f'
tmux select-window -t 1 'logs' 'tail -f app.log'
tmux attach-session -t my_project

    This sequence creates a session named my_project, starts vim in the first pane, splits horizontally for git status, splits vertically for docker-compose logs, creates a second window named logs with tail -f app.log, and finally attaches to the session.

  • Scripting tmux layouts:

    # ~/.tmux.conf
bind-key v split-window -h
bind-key s split-window -v

# Then in your shell:
# Prefix + v (splits vertically)
# Prefix + s (splits horizontally)

    Defines custom key bindings for splitting panes.

  • Sending commands to specific panes:

    # Send 'ls -l' to pane 1 (0-indexed) of window 0
tmux send-keys -t 0:0.1 'ls -l' Enter

    The format is session:window.pane.

Gotchas

  • Prefix Key Confusion: The most common issue is forgetting the prefix key. Remember, it’s Ctrl+b by default, followed by the command key.
  • Detaching vs. Killing: Detaching (Prefix + d) leaves sessions running. Killing (tmux kill-session) terminates them. Accidental detachment is usually fine; accidental killing is not.
  • Copy Mode Navigation: Copy mode uses different navigation keys than normal mode. h, j, k, l are common for movement, and Space and Enter for selection.
  • Pane Indexing: Panes are indexed starting from 0. The order can be confusing; tmux list-panes can help visualize it.
  • Synchronization Nuances: synchronize-panes is powerful but can be disruptive if not turned off after use. It also doesn’t work for commands that require interactive input in multiple panes simultaneously.
  • Default Configuration: Tmux has a minimal default configuration. For advanced features like mouse support, better colors, or custom layouts, you’ll need to edit ~/.tmux.conf.
  • send-keys vs. Direct Input: send-keys is for sending commands programmatically. Typing directly after pressing the prefix enters tmux command mode or executes a key binding.
  • Shell Interpretation: Commands sent via send-keys are executed by the shell running in that pane. Ensure the command is valid for that shell.
  • tmux attach-session vs. tmux attach: attach-session is the full command; attach is a common alias.