tmux Keyboard Shortcuts: Windows, Panes, Sessions, and Scrollback

tmux can manage multiple windows and split panes in a terminal, and can keep tasks running after an SSH disconnect. Its default prefix key is Ctrl+b. Most shortcuts use the following sequence:

1. Press Ctrl+b;
2. Release both keys;
3. Press the following action key. For example, to create a new window, instead of pressing Ctrl+b+c at the same time, press Ctrl+b first, release it and then press c.

The most important shortcut keys to remember

1
2
3
4
5
6

Ctrl+b d       Detach while keeping tasks running
Ctrl+b %       Split into left and right panes
Ctrl+b "       Split into top and bottom panes
Ctrl+b arrows  Move between panes
Ctrl+b z       Zoom or restore the current pane
Ctrl+b [       Open and scroll through history

Restore the session you just exited:

1

tmux attach

Install and confirm that tmux is available

Debian and Ubuntu:

1
2

sudo apt update
sudo apt install tmux

Fedora:

1

sudo dnf install tmux

Arch Linux:

1

sudo pacman -S tmux

macOS using Homebrew:

1

brew install tmux

Check the version after installation:

1

tmux -V

The terminal returns information similar to tmux 3.x, indicating that the command has entered PATH in the current environment.

Create, exit, and resume sessions

Start an anonymous session directly:

1

tmux

It is more recommended to create a named session:

1

tmux new -s work

work can be replaced by the project name, server name or task name. Press Ctrl+b when leaving temporarily, and press d after releasing. This operation is called detach, which only detaches the current terminal from the session. Compilation, downloads, log monitoring, and scripts within the session will still run. If exit is executed in the pane, the current shell will be closed. After the last pane exits, the corresponding window and session may also end.

1

tmux ls

Then resume the specified session:

1

tmux attach -t work

Shorthand commands also work:

1

tmux a -t work

Window shortcut keys

Windows are similar to browser tabs. A session can have multiple windows, and each window can contain multiple panes.

Split pane and pane operation

Panes are independent terminal areas within the same window.

Resize paness

The common operation is to press Ctrl+b first, then press and hold Ctrl and press the direction keys continuously. If the terminal intercepts the key combination, you can use the tmux command. First press Ctrl+b :, then enter:

1
2
3
4

resize-pane -L 5
resize-pane -R 5
resize-pane -U 3
resize-pane -D 3

L, R, U, and D represent left, right, top, and bottom respectively, and the numbers represent the number of units to be adjusted. Set the current pane width or height as a percentage:

1
2

resize-pane -x 70%
resize-pane -y 60%

Scroll through terminal history

The scroll wheel of a normal terminal sometimes cannot directly scroll the tmux history. First enter copy mode:

1

Ctrl+b [

1

set-window-option -g mode-keys vi

Copy and paste text

When using vi mode, the common process is as follows:

1. Press Ctrl+b [ to enter copy mode;
2. Move to starting point;
3. Press space to start selection;
4. move to end point;
5. Press Enter to copy to the tmux buffer;
6. Press Ctrl+b ] to paste. Different versions or custom configurations may use v to start selection and y to complete copying. Press Ctrl+b ? to view the current real binding. View and save tmux buffers:

1
2

tmux show-buffer
tmux save-buffer ~/tmux-buffer.txt

Enable mouse operation

When you want to use the mouse to select panes, adjust borders and scroll, add in ~/.tmux.conf:

1

set -g mouse on

Reload configuration:

1

tmux source-file ~/.tmux.conf

When you turn on the mouse, the scroll wheel usually automatically enters copy mode. In some terminals, mouse selection will be taken over by tmux; when you need to use the terminal’s native selection, you can try holding down Shift and dragging.

A sufficient basic configuration

Edit ~/.tmux.conf:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

# Enable mouse support
set -g mouse on

# Increase scrollback capacity
set -g history-limit 50000

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

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

# Use vi-style copy mode
setw -g mode-keys vi

# Reduce key-sequence delay
set -sg escape-time 10

After saving, execute:

1

tmux source-file ~/.tmux.conf

You can also press Ctrl+b : and enter source-file ~/.tmux.conf. When there are syntax errors in the configuration, tmux will point out the line number; comment out the recently added configuration and try again without deleting the entire file.

Modify default prefix key

If Ctrl+b conflicts with the editor shortcut key, you can change it to Ctrl+a:

1
2
3

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

After loading, all Ctrl+b operations in this article must be replaced with Ctrl+a. The last line is used to send the prefix to the nested tmux.

Resume task after SSH disconnect

When running a long task remotely, you can follow the following process:

1
2
3

ssh user@server
tmux new -s train
./run-task.sh

When you need to leave, press Ctrl+b d and then exit SSH. Sessions often survive unexpected network disconnections. After reconnecting execute:

1
2

tmux ls
tmux attach -t train

tmux can only save terminal sessions and cannot automatically revive programs that have exited with an error. Important tasks should still be logged:

1

./run-task.sh 2>&1 | tee -a task.log

Common errors and solutions

no server running

When tmux ls is executed, no server running on /tmp/tmux-... appears, indicating that the current user does not have a running tmux server. Just recreate the session:

1

tmux new -s work

sessions should be nested with care

This means that the current shell is already in tmux and tmux has been executed. First check:

1

echo "$TMUX"

When there is output, first press Ctrl+b c to create a new window, or use the following command to switch sessions:

1

tmux switch-client -t session-name

The display size is wrong after attach

When terminals of different sizes are connected to the same session, the display area may be affected by the smaller client. Other clients can be disconnected during recovery:

1

tmux attach -d -t work

View existing clients:

1

tmux list-clients

Shortcut keys are not responding

Check in order:

1. Whether to press the prefix first and release;
2. Whether the prefix has been modified in the configuration;
3. Whether the terminal or remote desktop intercepts the key combination;
4. Whether in nested tmux;
5. Whether the current binding is overwritten by the plugin. Show all real bindings:

1

Ctrl+b ?

Query split-screen bindings from the shell:

1

tmux list-keys | grep 'split-window'

A pane or session was closed accidentally

tmux does not have a general undo shutdown function. Before closing, make sure there are no unsaved editors, interactive tasks, or unwritten output to files. Use tee to save the log, which can reduce the loss after accidentally closing the pane.

Safe shutdown and cleanup

Just end a session:

1

tmux kill-session -t work

Keep work and end other sessions:

1

tmux kill-session -a -t work

End the entire tmux server for the current user:

1

tmux kill-server

kill-server will close all sessions managed by the server and the processes in them. Before execution, run tmux ls to confirm that there are no tasks that still need to be retained.

Precisely specify sessions, windows and panes

The tmux command often uses -t to specify the target. The complete target format is:

1

session-name:window-index.pane-index

For example, work:1.2 represents window 1, pane 2 in the work session.

View current goals:

1

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

List all windows:

1

tmux list-windows -a

List all panes and their current commands:

1

tmux list-panes -a -F '#S:#I.#P #{pane_current_command}'

This writing method is suitable for troubleshooting task locations between multiple sessions, and is also suitable for scripts to only operate specified panes to avoid accidentally closing other terminals.

The target can omit some fields. Window 2 in the current session can be written as :2, and pane 1 in the current window can be written as .1. It is recommended to use the complete target in automation scripts to reduce ambiguity caused by changes in the current focus.

Create windows and split panes from the shell

In addition to keyboard shortcuts, tmux commands can also be called directly. Create a new window to the work session:

1

tmux new-window -t work -n logs

Create left and right split panes in the window:

1

tmux split-window -h -t work:logs

Create a top-bottom split pane:

1

tmux split-window -v -t work:logs

Run the command directly when creating the pane:

1

tmux split-window -h -t work:logs 'tail -f /var/log/syslog'

The pane with the command will close after the command ends. If you want to see the final output, you can tell the shell to persist after the command:

1

tmux split-window -h -t work:logs 'tail -n 100 /var/log/syslog; exec bash'

In a remote production environment, do not write commands that require passwords directly into the Shell history. Use existing authentication mechanisms and limit the log pane to read only necessary files.

Send commands to a background session

send-keys can simulate keyboard input to the specified pane:

1

tmux send-keys -t work:server.0 'npm run dev' Enter

Send Ctrl+c to the running foreground program:

1

tmux send-keys -t work:server.0 C-c

Before sending the command, confirm the program currently running on the pane:

1

tmux display-message -p -t work:server.0 '#{pane_current_command}'

If the output is an editor, database client, or other interactive program, sending text directly may cause data modification. When automating, prepare dedicated sessions and fixed window names for tasks, and do not rely on temporary numbers.

Create a background session and start the task:

1
2

tmux new-session -d -s backup
tmux send-keys -t backup:0 'bash ~/backup.sh 2>&1 | tee -a ~/backup.log' Enter

Check if the session exists:

1
2

tmux has-session -t backup
echo $?

A return code of 0 indicates that the target session exists. It only shows that the tmux session is still there, not that the script was successful. You should also check the exit status, log, or output file.

Capture pane output for troubleshooting

You can also read the pane history without entering a session:

1

tmux capture-pane -p -t work:server.0

Get only the last 100 rows:

1

tmux capture-pane -p -S -100 -t work:server.0

Save to file:

1

tmux capture-pane -p -S -500 -t work:server.0 > server-output.txt

capture-pane reads the screen and history content saved by tmux. If the program output exceeds history-limit, earlier content cannot be restored.

Tasks that require long-term auditing should have the program write its own logs, rather than relying solely on tmux history. If the logs contain tokens, connection strings, or user data, appropriate file permissions and retention periods must also be set.

Check if the session still has clients

The following command can check which terminals are still connected to tmux:

1

tmux list-clients -F '#{client_name} session=#{session_name} tty=#{client_tty}'

If an exclusive session is required before the maintenance window, notify other users first, and then decide whether to use attach -d to disconnect their clients.

An empty client list does not mean that the task has ended, it only means that no terminal is currently displaying the session.

FAQ

Will detach stop the program?

Won’t. Ctrl+b d only disconnects clients. Whether the program continues to run also depends on whether the server is shut down, restarted, or the process is terminated by another mechanism.

Why did Ctrl+b % enter a percent sign?

Usually there is no trigger prefix, or the keys are pressed in a simultaneous combination. Press Ctrl+b first and release it all before entering %; most keyboard layouts require Shift+5.

Why is it difficult to press double quotes?

Trigger the prefix first, and then use the double quote combination corresponding to the current keyboard layout, usually Shift+'. You can also rebind a more convenient split-screen key in the configuration.

How to confirm current session, window and pane?

1

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

The output is session name, window number, and pane number, in order.

Quick recap

The structure of tmux is divided into three layers: the session saves the entire working environment, the window distinguishes tasks, and the pane is responsible for splitting the screen. The daily process is to use tmux new -s name to create a session, organize tasks through windows and split panes, press Ctrl+b d to leave safely, and then use tmux attach -t name to resume. When you forget a shortcut, press Ctrl+b ? to see the real bindings in your current configuration, which is more reliable than memorizing the full list.