tmux Cheat Sheet

Setup

Install tmux, verify its version, and start a named session.

Install and Start tmux

Install tmux with a platform package manager and create a session.

bash

# macOS
brew install tmux

# Ubuntu or Debian
sudo apt update
sudo apt install tmux

📌 tmux runs inside a terminal on Unix-like systems

💡 Distribution packages can lag behind the newest tmux release

🔍 tmux -V prints the installed version

🎯 Name sessions so they are easy to identify and reattach

installpackage-managerversionsession

Start and Inspect

Start tmux and inspect the running server.

Start tmux

Create a new session or attach to an existing one.

bash

tmux

🟢 tmux starts a server when none exists

💡 Use a named session for easier reconnection

📌 The default prefix is Ctrl-b

🔍 -A attaches when the named session exists

startserverversion

List Server State

Inspect sessions, clients, windows, and panes.

bash

tmux list-sessions

💡 Most list commands have short aliases

📌 -a includes every session where supported

🔍 A server can host multiple sessions and clients

⚠️ tmux info can produce a large diagnostic report

listinspectserver

Sessions

Create, name, attach to, and remove sessions.

Create and Rename Sessions

Create a named session and rename it later.

bash

tmux new-session -s api

💡 Name sessions by project or task

📌 -d creates the session without attaching

🔍 Session names must be unique on the server

⚡ Ctrl-b $ renames the attached session

sessionscreaterename

Attach and Detach

Reconnect clients without stopping running programs.

bash

tmux attach-session -t backend

📌 Detaching leaves the session running

💡 Use attach -d when a stale client owns the session

⚡ Ctrl-b d detaches the current client

🔍 Multiple clients can view one session

attachdetachclients

Kill Sessions

Stop one session or every session except one.

bash

tmux kill-session -t backend

⚠️ Killing a session stops programs inside it

📌 -a kills all sessions except the target

🔍 kill-server removes every tmux session

🎯 Confirm targets before destructive commands

killsessionscleanup

Windows

Create and organize terminal workspaces within a session.

Create and Rename Windows

Add a window and give it a useful name.

bash

# Inside tmux
# Ctrl-b c

⚡ Ctrl-b c creates a window

💡 Name windows by responsibility

📌 Targets use session:window syntax

🔍 Window indexes start at zero by default

windowscreaterename

Select and Reorder Windows

Move between windows and change their indexes.

bash

# Ctrl-b n  next
# Ctrl-b p  previous
# Ctrl-b 0  window zero

⚡ Ctrl-b w opens the window chooser

💡 A named target survives index changes

📌 Numeric prefix keys select matching indexes

🔍 move-window can leave index gaps

windowsnavigationreorder

Panes

Split windows and control individual terminals.

Split Panes

Split the current pane vertically or horizontally.

bash

# Ctrl-b %  left and right
# Ctrl-b "  top and bottom

📌 -h creates left and right panes

📌 -v creates top and bottom panes

💡 -c starts the pane in a chosen directory

🔍 -p sets the new pane size as a percentage

panessplitlayout

Navigate and Identify Panes

Select panes by direction, number, or target.

bash

# Ctrl-b Arrow  select by direction
# Ctrl-b o      select next pane

⚡ Ctrl-b q displays pane indexes

📌 Pane targets use session:window.pane

💡 Directional selection works well in scripts

🔍 Pane IDs beginning with % are server-wide

panesnavigationtargets

Resize, Zoom, and Close Panes

Adjust pane space or focus on one pane.

bash

# Ctrl-b z  toggle zoom
# Ctrl-b x  kill pane

⚡ Zoom keeps the layout while focusing one pane

⚠️ Ctrl-b x asks before killing the pane

💡 Exit the shell for a normal pane shutdown

🔍 resize-pane accepts direction and cell count

panesresizezoomclose

Layouts

Apply and preserve standard pane arrangements.

Choose a Layout

Cycle or select a built-in pane layout.

bash

# Ctrl-b Space  cycle layouts

⚡ Ctrl-b Space cycles built-in layouts

💡 tiled is useful for many equal panes

🔍 Layouts apply to the current window

📌 Manual resizing changes the active layout string

layoutspanesarrangement

Targets and Commands

Address tmux objects and run commands precisely.

Target Syntax

Address sessions, windows, and panes.

bash

session:window.pane
work:editor.1

📌 The full form is session:window.pane

💡 Names are clearer than changing indexes

🔍 $ IDs identify sessions and % IDs identify panes

⚠️ Quote shell values passed through send-keys

targetssyntaxautomation

Command Prompt and Sequences

Run tmux commands interactively or in sequence.

bash

# Ctrl-b :
new-window -n logs

⚡ Ctrl-b : opens the tmux command prompt

📌 Escape semicolons from the shell

💡 Command sequences build repeatable workspaces

🔍 display-message can expand tmux formats

command-promptsequencescommands

Copy Mode and Buffers

Navigate scrollback, copy text, and manage paste buffers.

Enter and Search Copy Mode

Browse pane history without sending input to the app.

bash

# Ctrl-b [  enter copy mode
# q         exit copy mode

📌 Copy mode reads tmux scrollback history

💡 Set mode-keys vi when those motions are familiar

🔍 Search keys depend on the selected mode table

⚡ q exits copy mode without copying

copy-modesearchscrollback

Copy and Paste

Copy a selection into a tmux buffer and paste it.

bash

# In vi copy mode: Space, move, Enter
# Ctrl-b ]  paste

📌 tmux keeps copied text in paste buffers

⚡ Ctrl-b ] pastes the newest buffer

🔍 System clipboard integration is terminal-dependent

⚠️ Buffers can contain sensitive terminal output

bufferscopypaste

Configuration

Set persistent options and reload configuration.

Config Files and Reloading

Store settings and load changes without restarting.

bash

# ~/.tmux.conf
set -g mouse on

📌 User config is read when the server starts

⚡ source-file applies edits to a running server

💡 Show a message after a successful reload

🔍 Existing objects may retain some local options

configurationreloadtmux-conf

Common Options and Scope

Set server, session, window, or pane behavior.

bash

set -g mouse on
set -g history-limit 50000

📌 -g changes the global default scope

🔍 Session and window options have separate scopes

💡 Inspect an option before overriding it

⚠️ Raising history-limit increases memory use

optionsscopemousehistory

Key Bindings

Change the prefix and add focused shortcuts.

Change the Prefix

Replace Ctrl-b while preserving prefix passthrough.

bash

unbind C-b
set -g prefix C-a
bind C-a send-prefix

📌 Keep send-prefix for nested sessions

💡 prefix2 supports a transition period

⚠️ Ctrl-a conflicts with a common shell shortcut

🎯 Change the prefix only when it improves workflow

prefixkey-bindingsnested-tmux

Custom Bindings and Key Tables

Bind keys with or without the prefix.

bash

bind | split-window -h
bind - split-window -v

📌 -n creates a binding in the root key table

⚠️ Root bindings can steal keys from applications

💡 list-keys reveals defaults before customization

🔍 Key tables support modal workflows

bindingskey-tablesnavigation

Mouse and Status Line

Enable pointer support and customize visible context.

Mouse Support

Select panes, resize borders, and scroll with the mouse.

bash

set -g mouse on

📌 Mouse mode changes terminal selection behavior

💡 Hold the terminal modifier for native selection

🔍 Mouse actions are mapped through key tables

🎯 Keep keyboard commands available as a fallback

mouseconfigurationselection

Status Content and Style

Show session context using formats and styles.

bash

set -g status-left '#S '
set -g status-right '%H:%M'

📌 #S expands to the session name

🔍 Formats can include conditions and variables

💡 Keep the status line useful at narrow widths

⚠️ Frequent shell commands can slow status updates

status-linestylesformats

Formats and Automation

Query state and react to tmux events.

Format Variables

Print tmux state for scripts and status content.

bash

tmux display-message -p '#S:#I.#P'

📌 -p prints the expanded result to stdout

💡 -F formats every row from list commands

🔍 Long and short variable names can be mixed

🎯 Prefer formats over parsing human-readable output

formatsscriptingdisplay-message

Hooks

Run a tmux command after a server event.

bash

set-hook -g session-created 'display-message "Session created"'

📌 Hooks run tmux commands, not raw shell syntax

💡 Use run-shell when a hook must call a script

🔍 Multiple hooks can use indexed array options

⚠️ Keep hooks fast to avoid workflow delays

hooksautomationevents

Remote Persistent Workspace

Reconnect to a named tmux session over SSH.

bash

ssh server -t 'tmux new-session -A -s work'

📌 -t gives SSH a terminal for interactive tmux

💡 Named sessions make reconnection predictable

⚠️ tmux does not survive a host reboot by itself

🔍 Network loss usually leaves the session running

sshremotepersistence

Troubleshooting

Inspect configuration and recover from common problems.

Inspect Effective State

Check keys, options, messages, and pane identity.

bash

tmux list-keys
tmux show-options -g

💡 Inspect effective state before editing config

📌 show-messages includes recent server messages

🔍 pane_dead helps locate exited pane processes

⚠️ Use kill-server only as a last resort

troubleshootinginspectdiagnostics

tmux

Table of Contents

Setup

Start and Inspect

Sessions

Windows

Panes

Layouts

Targets and Commands

Copy Mode and Buffers

Configuration

Key Bindings

Mouse and Status Line

Formats and Automation

Troubleshooting