Cheatsheets

Tmux Cheatsheet for Linux

Operating Systems #cli#linux#shell#tmux Last updated
Library

A practical guide and daily quick reference for tmux, the terminal multiplexer, aimed at Linux beginners, developers, and system administrators.

How to read this document

  • All keyboard shortcuts use the default tmux key bindings unless they are explicitly marked (optional / custom).
  • Code blocks labelled bash are run in a regular shell.
  • Code blocks labelled tmux are run at the tmux command prompt (opened with Ctrl+b, then :) or placed in ~/.tmux.conf.
  • Names such as mysession, work, maintenance, web01, and admin are placeholders. Replace them with your own values.
  • Behaviour can differ slightly between tmux versions. Check yours with tmux -V.

Table of Contents#

  1. Introduction to tmux
  2. Installation and Version Check
  3. Essential Session Management
  4. Window Management
  5. Split Screen and Pane Management
  6. Broadcast Input to Multiple Panes
  7. Copy Mode, Scrolling, Search, and Clipboard
  8. Long-Running Commands and SSH Sessions
  9. Useful tmux Command-Line Operations
  10. Configuration with .tmux.conf
  11. Troubleshooting
  12. Recommended Workflows
  13. Best Practices and Common Mistakes
  14. Quick Reference

1. Introduction to tmux#

What tmux is#

tmux is a terminal multiplexer: it lets one terminal window host many independent shells, and it keeps those shells running in the background even when no one is looking at them.

It works as a client–server program:

  • The tmux server is a background process that owns all sessions, windows, panes, and the programs running inside them.
  • A tmux client is what you see in your terminal. It connects to the server, displays one session, and forwards your keystrokes.

Because the programs belong to the server rather than to your terminal, you can close the terminal (or lose your SSH connection), and the programs keep running. Later, a new client can reattach and pick up exactly where you left off.

Why it is useful#

Situation How tmux helps
Remote administration over SSH Work survives a dropped connection; reattach and continue.
Long-running commands (backups, upgrades, migrations, builds) Run them in a session, detach, and check back later.
Monitoring View logs, top, and a working shell side by side in one window.
Development Keep an editor, a test runner, and a server in one organized workspace.
Multiple servers Organize one SSH connection per pane or window, and optionally type into several at once.

Key terms#

Term Meaning
Terminal emulator The graphical program you use (GNOME Terminal, Konsole, Alacritty, Windows Terminal, iTerm2, PuTTY). It displays a tmux client.
tmux server Background process that holds all sessions. One per user per socket by default. Started automatically by the first tmux command.
Session A collection of windows representing a workspace (for example, one project or one server).
Window A terminal tab within a session. Only one window of a session is shown at a time.
Pane A section of a window created by splitting its screen. Each pane runs its own shell or program.

Hierarchy#

tmux server
└── Session
    ├── Window 1
    │   ├── Pane 1
    │   └── Pane 2
    └── Window 2
        └── Pane 1

Note that tmux numbers windows and panes from 0 by default, so the first window is window 0.

Detached sessions#

When you detach, the client disconnects from the session, but the server and everything running inside the session continue. This is what makes tmux so valuable over SSH:

Your laptop                         Remote server
┌──────────────┐   SSH    ┌──────────────────────────────┐
│ Terminal     │ ───────▶ │ tmux client ──▶ tmux server  │
│ emulator     │          │                 └─ session   │
└──────────────┘          │                    └─ backup │
                          └──────────────────────────────┘
SSH drops ✗  → the client on the server disappears,
               but the tmux server and the backup keep running.

Limitations#

tmux keeps terminal sessions alive. It is not a process supervisor or a high-availability tool:

  • A server reboot or power loss ends all tmux sessions and everything running in them.
  • A system failure (kernel panic, OOM killer, crashed container) can kill the tmux server or individual processes.
  • An explicit termination (tmux kill-session, tmux kill-server, kill, closing the shell) ends the affected work.
  • Some systems are configured to kill all of a user's processes at logout (for example, systemd-logind with KillUserProcesses=yes), which can also end tmux.
  • tmux does not restart failed commands and does not log their output to disk on its own.

The prefix key and shortcut notation#

Most tmux shortcuts start with the prefix key, which is Ctrl+b by default.

The notation Ctrl+b, then d means:

  1. Hold Ctrl and press b.
  2. Release both keys.
  3. Press d.

Do not hold Ctrl while pressing the second key unless the shortcut says so (for example, Ctrl+b, then Ctrl+↑). Symbols such as %, ", $, (, and ) require Shift on most keyboard layouts.

To see every active key binding, press Ctrl+b, then ? (press q to leave the list).

2. Installation and Version Check#

Installation requires administrator privileges (sudo). Many server images already include tmux.

Distribution Installation command
Ubuntu / Debian sudo apt install tmux
Fedora sudo dnf install tmux
Rocky Linux / AlmaLinux sudo dnf install tmux
Arch Linux sudo pacman -S tmux

Repository availability, package names, and the packaged tmux version vary by distribution and release. Long-term-support distributions often ship an older tmux, so a few newer features in this guide may be missing.

Verify the installation and check the version:

tmux -V

Example output:

tmux 3.4

Check whether you are already inside tmux:

echo "$TMUX"

If this prints a value (a socket path and IDs), the current shell is running inside tmux. If it prints an empty line, you are not.

3. Essential Session Management#

3.1 Create a session#

tmux                               # new unnamed session
tmux new                           # same as above (short for new-session)
tmux new -s mysession              # new session named "mysession"
tmux new-session -s mysession      # same as above (full command name)
  • tmux, tmux new, and tmux new-session are equivalent. They create a session, attach to it, and give it a numeric name (0, 1, 2, ...).
  • -s mysession gives the session a meaningful name. Always prefer named sessions: names are far easier to find, attach to, and clean up than 0 or 3.
  • tmux new -s mysession and tmux new-session -s mysession are identical; new is an alias.

If a session with that name already exists, tmux reports duplicate session: mysession. See 3.8.

3.2 Create a detached session#

tmux new-session -d -s mysession

-d creates the session in the background without attaching your terminal to it. This is useful in scripts or when preparing a workspace you will attach to later. You can also start a command directly:

tmux new-session -d -s mysession 'top'

When a command is given this way, the window closes when that command exits. For long-running work you usually want a normal shell instead (see Section 8).

3.3 List sessions#

tmux ls
tmux list-sessions                 # same command, full name

Example output:

maintenance: 1 windows (created Thu Oct 15 10:02:10 2026)
work: 3 windows (created Thu Oct 15 09:12:44 2026) (attached)
Part Meaning
work Session name
3 windows Number of windows in the session
(created ...) When the session was created
(attached) A client is currently displaying this session

The exact format varies between versions.

If no sessions exist, tmux reports something like:

no server running on /tmp/tmux-1000/default

This is not an error in your setup. It means no tmux server is running for your user, so there is nothing to attach to. Create a session with tmux new -s mysession.

3.4 Attach to an existing session#

tmux attach                        # attach to the most recently used session
tmux attach -t mysession           # attach to the session named "mysession"
tmux attach-session -t mysession   # same as above (full command name)
  • Use plain tmux attach when you have only one session, or you want the last one you used.
  • Use -t mysession when you have several sessions. Run tmux ls first if you are unsure of the name.
  • tmux a and tmux a -t mysession are common short forms.

Attaching from inside tmux nests sessions and triggers a warning. Inside tmux, switch sessions instead (see 3.6).

3.5 Detach without terminating the session#

Default shortcut: Ctrl+b, then d

Detaching disconnects the current client and returns you to your normal shell. The session and every program in it keep running, as long as the tmux server keeps running.

You can also detach from the shell inside tmux:

tmux detach

Closing the terminal window or losing the SSH connection has the same effect as detaching: the session continues.

3.6 Switch between sessions#

Action Shortcut
Choose a session interactively (tree view) Ctrl+b, then s
Switch to the previous session Ctrl+b, then (
Switch to the next session Ctrl+b, then )
Switch back to the last used session Ctrl+b, then L

In the Ctrl+b, then s tree view, use the arrow keys and Enter to select a session. Press the right arrow to expand a session and see its windows.

Command alternative (run inside an attached tmux client):

tmux switch-client -t mysession

3.7 Rename a session#

From a shell:

tmux rename-session -t oldname newname

Interactive shortcut for the current session: Ctrl+b, then $, type the new name, and press Enter.

3.8 Avoid duplicate sessions#

tmux new-session -A -s work

-A makes new-session behave like attach-session if a session named work already exists, and creates it otherwise. This is the safest "just get me into my workspace" command, and it is ideal for aliases:

alias tw='tmux new-session -A -s work'

3.9 Kill a session#

Always list sessions and confirm the exact name first:

tmux ls
tmux kill-session -t mysession

Warning: kill-session terminates the session immediately, along with every program running in its windows and panes. Unsaved work, running backups, and open editors in that session are lost. There is no confirmation prompt.

Understand the difference between these three actions:

Action How Effect
Detach Ctrl+b, then d Your client leaves. The session and its programs keep running.
Kill one session tmux kill-session -t name That session and all its programs end. Other sessions are unaffected.
Kill all sessions tmux kill-server The tmux server stops. Every session it manages, and every program in them, ends.

Warning – administrative operation: tmux kill-server terminates all sessions managed by that server, including sessions you may have forgotten about that are running important jobs. It is not a routine cleanup command. Prefer killing individual, verified sessions.

3.10 Session management quick reference#

Task Command or shortcut Explanation
Create a named session tmux new -s name Creates and attaches
Create in the background tmux new-session -d -s name Creates without attaching
Attach or create tmux new-session -A -s name Reuses an existing session if present
List sessions tmux ls Shows names, window counts, attached state
Attach to a session tmux attach -t name Connects your terminal to the session
Detach Ctrl+b, then d Leaves the session running
Choose a session Ctrl+b, then s Interactive tree
Previous / next session Ctrl+b, then ( / ) Cycles through sessions
Rename current session Ctrl+b, then $ Prompts for a new name
Rename from shell tmux rename-session -t old new
Kill a session tmux kill-session -t name Ends the session and its programs
Kill everything tmux kill-server Ends all sessions – administrative use only

4. Window Management#

Windows behave like tabs within a session. Each window fills the whole tmux screen and can be split into panes. The status bar at the bottom lists the windows; the current one is marked with *.

Default shortcuts#

Action Shortcut
Create a new window Ctrl+b, then c
Choose a window interactively Ctrl+b, then w
Switch to the next window Ctrl+b, then n
Switch to the previous window Ctrl+b, then p
Select a window by index Ctrl+b, then a number such as 0 or 1
Prompt for a window index (useful for 10+) Ctrl+b, then '
Switch to the last used window Ctrl+b, then l
Rename the current window Ctrl+b, then ,
Kill the current window (asks to confirm) Ctrl+b, then &

Window commands#

tmux list-windows                         # windows in the current session
tmux list-windows -t work                 # windows in session "work"
tmux new-window -n logs                   # new window named "logs" (inside tmux)
tmux new-window -t work -n logs           # new window in session "work"
tmux select-window -t work:logs           # switch to window "logs" in "work"
tmux select-window -t work:2              # switch to window index 2
tmux rename-window -t work:2 monitoring   # rename window 2

Targets use the form session:window.pane, for example work:logs or work:1.0.

Closing windows#

Typing exit or pressing Ctrl+d at a shell prompt closes that shell. When the last pane in a window closes, the window closes. When the last window in a session closes, the session ends, and when the last session ends, the tmux server exits.

Example: organize work into windows#

tmux new-session -d -s work -n monitoring        # window 0: system monitoring
tmux new-window  -t work -n logs                 # window 1: application logs
tmux new-window  -t work -n ssh-admin            # window 2: SSH administration
tmux attach -t work
Window Name Typical use
0 monitoring top, htop, df -h, free -h
1 logs journalctl -f, tail -f /var/log/...
2 ssh-admin SSH connections and administrative commands

Jump between them with Ctrl+b, then 0, 1, or 2.

5. Split Screen and Pane Management#

A window can be divided into multiple panes. Each pane is an independent terminal with its own shell, current directory, and running program.

5.1 Split the screen#

Action Default shortcut
Split into left and right panes Ctrl+b, then %
Split into top and bottom panes Ctrl+b, then "
Zoom or restore the active pane Ctrl+b, then z
Display pane numbers temporarily Ctrl+b, then q 
Ctrl+b, then %                Ctrl+b, then "
(left / right)                (top / bottom)
┌─────────┬─────────┐         ┌───────────────────┐
│         │         │         │      pane 0       │
│ pane 0  │ pane 1  │         ├───────────────────┤
│         │         │         │      pane 1       │
└─────────┴─────────┘         └───────────────────┘

Terminology trap: tmux's own flags are easy to mix up. % (split-window -h) creates a left/right split – the dividing line is vertical. " (split-window -v) creates a top/bottom split – the dividing line is horizontal.

Command equivalents:

tmux split-window -h      # left / right   (same as Ctrl+b, then %)
tmux split-window -v      # top / bottom   (same as Ctrl+b, then ")

Zoom (Ctrl+b, then z) temporarily expands the active pane to fill the window. Press it again to restore the layout. A Z flag appears next to the window name in the status bar while zoomed.

5.2 Navigate between panes#

Action Default shortcut
Move to the pane above Ctrl+b, then ↑
Move to the pane below Ctrl+b, then ↓
Move to the pane on the left Ctrl+b, then ←
Move to the pane on the right Ctrl+b, then →
Move to the next pane Ctrl+b, then o
Move to the previously active pane Ctrl+b, then ;
Select a pane by number Ctrl+b, then q, then the number while it is shown

Additional pane operations#

Action Default shortcut or command
Resize by 1 cell Ctrl+b, then Ctrl+↑ / Ctrl+↓ / Ctrl+← / Ctrl+→
Resize by 5 cells Ctrl+b, then Alt+↑ / Alt+↓ / Alt+← / Alt+→
Resize by command tmux resize-pane -D 5 (also -U, -L, -R)
Swap with previous / next pane Ctrl+b, then { / }
Rotate panes forward Ctrl+b, then Ctrl+o
Rotate panes backward Ctrl+b, then Alt+o
Cycle through built-in layouts Ctrl+b, then Space
Apply a preset layout Ctrl+b, then Alt+1 … Alt+5 (see below)
Move the pane into its own new window Ctrl+b, then !
Kill the current pane (asks to confirm) Ctrl+b, then x
Close a pane normally exit or Ctrl+d at the shell prompt
Select a pane by index (command) tmux select-pane -t 2

Preset layouts: Alt+1 even-horizontal, Alt+2 even-vertical, Alt+3 main-horizontal, Alt+4 main-vertical, Alt+5 tiled. Recent development versions add mirrored variants on further keys; check Ctrl+b, then ? for your version.

The resize keys are repeatable: after the first one, you can press the arrow combination again within a short time without repeating the prefix.

Version and terminal notes: Resize behaviour and some bindings vary by tmux version and configuration. Many terminal emulators, desktop environments, and SSH clients intercept Ctrl+arrow or Alt+arrow combinations, in which case the command form (resize-pane) always works. Alt is called Meta (M-) in tmux documentation.

5.3 Practical multi-pane examples#

Some example commands need elevated privileges (for example, reading all system logs with journalctl may require sudo or membership in the adm or systemd-journal group). Log paths and tools differ between distributions.

Example 1 – Two panes: application and logs#

  1. tmux new -s app

  2. In the first pane, start your application (for example ./run-server.sh).

  3. Press Ctrl+b, then " to split top/bottom.

  4. In the new bottom pane, follow its log:

    tail -f /var/log/myapp/app.log

  5. Switch between panes with Ctrl+b, then ↑ / ↓.

Example 2 – Three panes: monitoring, logs, administration#

┌───────────────┬───────────────┐
│               │  journalctl   │
│     top       │  (pane 1)     │
│   (pane 0)    ├───────────────┤
│               │  admin shell  │
│               │  (pane 2)     │
└───────────────┴───────────────┘

  1. tmux new -s monitor

  2. Run top in the first pane.

  3. Press Ctrl+b, then % to create a right pane, and run:

    journalctl -f

  4. While in the right pane, press Ctrl+b, then " to split it top/bottom. Use the new bottom-right pane as your administration shell.

Example 3 – Four panes: parallel monitoring or SSH sessions#

  1. tmux new -s servers

  2. Press Ctrl+b, then % (left/right).

  3. Press Ctrl+b, then " in the right pane, then Ctrl+b, then ← and Ctrl+b, then " in the left pane.

  4. Press Ctrl+b, then Alt+5 (or run tmux select-layout tiled) to make all four panes equal.

  5. Start a separate command or SSH connection in each pane, for example:

    ssh admin@web01.example.com

┌──────────────┬──────────────┐
│ web01        │ web02        │
├──────────────┼──────────────┤
│ db01         │ local shell  │
└──────────────┴──────────────┘

6. Broadcast Input to Multiple Panes#

tmux can send the same keystrokes to several panes at once through the synchronize-panes window option. This is powerful for multi-server work, and equally powerful at causing mistakes, so read the safety notes in 6.9 before using it.

6.1 What broadcast input does#

  • When synchronize-panes is on, input typed in the active pane is duplicated to the other panes in the same window.
  • Each pane receives the keystrokes separately, and the command executes independently in each pane's own shell.
  • It is useful for running identical commands across several SSH connections or several local terminal environments.
  • tmux does not connect to servers for you. You open each SSH connection yourself, one per pane.
  • Synchronization is scoped to one window. It does not automatically apply to other windows or other sessions.
  • Panes can differ in user, privileges, current directory, environment variables, shell, distribution, and installed commands. The same keystrokes can produce different results – or fail – in different panes.
  • Panes that are in copy mode (or another tmux mode) do not receive the duplicated input.
Window "fleet"  (synchronize-panes on)
┌────────────────┬────────────────┐
│ web01          │ web02 (active) │   You type in web02.
│ $ hostname     │ $ hostname     │   The keystrokes are
├────────────────┼────────────────┤   copied to every pane
│ web03          │ web04          │   in THIS window only.
│ $ hostname     │ $ hostname     │
└────────────────┴────────────────┘
Other windows and sessions: not affected

6.2 Enable broadcast input#

  1. Open the tmux command prompt: Ctrl+b, then :
  2. Type the following and press Enter:
setw synchronize-panes on

Synchronization is now enabled for the current window. (setw is short for set-window-option.)

6.3 Disable broadcast input#

Open the command prompt again (Ctrl+b, then :) and run:

setw synchronize-panes off

Disable synchronization immediately after the shared operation is complete, before you return to normal per-pane work.

6.4 Toggle synchronization#

setw synchronize-panes

Without on or off, the option toggles between enabled and disabled. Toggling is convenient but makes it easy to lose track of the current state – check the state (6.5) when in doubt, or use explicit on/off.

6.5 Check synchronization status#

show-window-options synchronize-panes

This displays the option's value for the current window:

Output Meaning
synchronize-panes on Broadcasting is active in this window.
synchronize-panes off Explicitly disabled in this window.
(no output) Not set on this window, so the default (off) applies.

For an unambiguous answer about the current pane in recent tmux versions, run this from a shell inside that pane (it prints 1 when synchronized, 0 otherwise):

tmux display-message -p '#{pane_synchronized}'

6.6 Optional keyboard shortcut (custom)#

This is not a default tmux shortcut. Add it to ~/.tmux.conf only if you want it:

bind-key S set-window-option synchronize-panes

After reloading the configuration (see Section 10), press Ctrl+b, then uppercase S (Shift+s) to toggle synchronization. Check first that S is not already bound to something else in your configuration.

Optionally, show the state in the status bar so you can always see when broadcasting is on (also custom):

set -g status-right '#{?pane_synchronized,#[reverse] SYNC ON #[noreverse] ,}%H:%M'

6.7 Example: broadcast to multiple SSH servers#

  1. Create a named session:

    tmux new -s fleet

  2. Split the window into two or more panes (Ctrl+b, then % and/or ").

  3. In each pane, open a separate SSH connection:

    ssh admin@web01.example.com      # pane 0
ssh admin@web02.example.com      # pane 1

  4. Look at every pane and verify the hostname and shell prompt. Confirm you are the expected user, and not unexpectedly root.

  5. Enable synchronization: Ctrl+b, then :, then setw synchronize-panes on.

  6. Test with a harmless command:

    hostname

  7. Confirm that each pane printed its own hostname. This proves the command ran independently on each server.

  8. Run your intended shared command and check the output in every pane.

  9. Disable synchronization before continuing: Ctrl+b, then :, then setw synchronize-panes off.

Commands execute independently on each remote system. A successful result on one server does not mean it succeeded on the others – one server might be missing a package, have a full disk, or prompt for a password.

6.8 Scope and limitations#

Scope Receives broadcast input?
Other panes in the current window (with sync on) Yes
Panes in other windows of the same session No
Panes in other sessions No
Other remote hosts not open in a pane of this window No
A pane that is in copy mode No

synchronize-panes is not a global broadcast feature. To send a command to a pane in a different window or session, target it explicitly, for example from a shell:

tmux send-keys -t fleet:1.0 'uptime' Enter      # session fleet, window 1, pane 0

Treat send-keys with the same care as typing the command yourself. For regular, repeatable multi-server operations, a dedicated orchestration or configuration-management tool (with inventories, error handling, and logs) is more appropriate than tmux.

6.9 Safety warning#

⚠ Warning: When synchronize-panes is enabled, typing a command in the active pane may send it to every synchronized pane in the current window. Destructive commands, database operations, service restarts, and privileged commands can affect multiple systems simultaneously. Even a typo, a password, or an accidental Ctrl+c is broadcast.

Before enabling broadcast input:

  • Verify the hostname in each pane.
  • Verify the user identity and permissions in each pane (whoami, id).
  • Ensure every target system should receive the same command.
  • Test with a harmless command such as hostname.
  • Disable synchronization as soon as the task is finished.

If panes seem to be receiving input unexpectedly, disable synchronization in that window:

setw synchronize-panes off

7. Copy Mode, Scrolling, Search, and Clipboard#

Inside tmux, your terminal emulator's scrollbar usually cannot show output that scrolled off a pane. tmux keeps its own per-pane history, which you browse in copy mode.

Enter and exit copy mode#

Action Shortcut
Enter copy mode Ctrl+b, then [
Enter copy mode and scroll up one page Ctrl+b, then Page Up
Exit copy mode q (both styles); Esc in the default Emacs style

A position indicator such as [0/1532] appears in the top-right corner while in copy mode.

Emacs-style vs vi-style keys#

tmux uses Emacs-style copy-mode keys by default, unless your VISUAL or EDITOR environment variable contains vi, in which case it uses vi-style keys. You can set the style explicitly (optional):

set -g mode-keys vi
Action Emacs style (default) vi style
Move Arrow keys Arrow keys or h j k l
Page up / down Page Up / Page Down Page Up / Page Down, or Ctrl+b / Ctrl+f
Half page up / down Alt+↑ / Alt+↓ Ctrl+u / Ctrl+d
Top / bottom of history Alt+< / Alt+> g / G
Search backward (up) Ctrl+r (incremental) ?
Search forward (down) Ctrl+s (incremental) /
Next / previous match n / N n / N
Start selection Ctrl+Space Space
Copy selection and exit Alt+w (or Ctrl+w) Enter
Clear selection Ctrl+g Esc
Exit copy mode q or Esc q

In vi style, Esc clears the selection but does not leave copy mode – use q. Also note that v in vi style toggles rectangle selection rather than starting a selection.

Copy and paste with tmux buffers#

  1. Ctrl+b, then [ to enter copy mode.
  2. Move to the start of the text, and start a selection (Ctrl+Space or Space).
  3. Move to the end of the text, and copy (Alt+w or Enter).
  4. In the destination pane, press Ctrl+b, then ] to paste.
Action Shortcut
Paste most recent buffer Ctrl+b, then ]
List paste buffers Ctrl+b, then #
Choose a buffer to paste Ctrl+b, then =

tmux buffers vs the system clipboard#

  • tmux copies into its own paste buffers, stored in the tmux server. They are available in any pane of that server, but not automatically in your desktop applications.
  • Getting text into the system clipboard depends on your environment:
    • OSC 52: tmux's set-clipboard option can ask the outer terminal emulator to set the clipboard. This works over SSH, but only if the terminal emulator supports OSC 52 and allows it.
    • Clipboard utilities: on a local desktop, tools such as xclip/xsel (X11) or wl-copy (Wayland) can receive copied text, configured with tmux's copy-command option (tmux 3.2 and later). On a remote server, these tools write to the remote machine's clipboard, not your laptop's.
  • With mouse support enabled, many terminals let you bypass tmux and use the terminal's native selection by holding Shift while dragging. This is terminal-dependent.

Do not assume system clipboard integration works automatically on every Linux desktop or SSH setup; test it in your environment.

Scrollback size#

The default history is 2000 lines per pane. Increase it in ~/.tmux.conf (see Section 10). The new limit applies to panes created after the change.

8. Long-Running Commands and SSH Sessions#

Workflow#

Connect and start a named session on the server:

ssh admin@server.example.com
tmux new -s maintenance

Inside the session, run the long-lived command, ideally with logging:

sudo apt full-upgrade 2>&1 | tee ~/upgrade-$(date +%F).log

Detach: Ctrl+b, then d. You can now log out, or your connection can drop.

Later, reconnect and reattach:

ssh admin@server.example.com
tmux ls
tmux attach -t maintenance

Shortcut for "reattach if it exists, otherwise create":

ssh -t admin@server.example.com tmux new-session -A -s maintenance

(-t forces SSH to allocate a terminal, which tmux requires.)

What to understand#

  • The tmux server and session live on the machine where tmux was started. Starting tmux on your laptop and then SSH-ing out does not protect the remote command – if your laptop sleeps, the SSH connection inside tmux still drops. For remote resilience, start tmux on the remote server.
  • A detached session normally survives an SSH client disconnect.
  • A server reboot, system failure, explicit session termination, or the process itself crashing can still interrupt the work.
  • tmux does not restart failed commands and does not tell you whether a command succeeded.
  • Long-running operations still need logging, exit-status checks, and monitoring.

Check the exit status of the last command when you reattach:

echo $?

When a command is piped (as with tee above), $? reports the status of the last command in the pipeline. In Bash, use echo "${PIPESTATUS[@]}" immediately afterwards to see every exit status.

Monitoring advice#

  • Run the long job in its own window (for example, job), and monitoring in another (for example, monitor), so you never type into the job's pane by accident.
  • Use dedicated panes for top/htop, df -h, free -h, or journalctl -f next to the job.
  • Use tail -f on the job's log file from a separate pane instead of scrolling the job's own output.
  • For critical jobs, consider a systemd unit or a job scheduler instead, which offer restarts, logging, and status reporting that tmux does not.

9. Useful tmux Command-Line Operations#

Commands run in a regular shell#

These work from any shell, inside or outside tmux (unless noted):

Command Purpose
tmux new -s work Create and attach to session work.
tmux new-session -d -s work Create session work in the background.
tmux ls List sessions.
tmux attach -t work Attach to session work (from outside tmux).
tmux new-session -A -s work Attach to work, or create it if missing.
tmux switch-client -t work Switch the current client to work. Inside tmux only – fails outside with "no current client".
tmux rename-session -t work production Rename session work to production.
tmux kill-session -t work Terminate session work and all its programs. ⚠
tmux list-windows -t work List windows in session work.
tmux list-panes -t work List panes in the current window of work. Add -s (tmux list-panes -s -t work) for every pane in the session.
tmux display-message -p '#S' Print the current session name. Run it from a pane inside tmux.

Other practical commands:

tmux list-panes -a                         # every pane in every session
tmux capture-pane -p -S -1000 -t work:0.0 > pane.txt   # save last 1000 lines of a pane to a file
tmux display-message -p '#S:#I.#P'         # current session:window.pane
tmux list-keys                             # all key bindings
tmux show-options -g                       # global session options
tmux show-window-options -g                # global window options

capture-pane is a handy way to save a pane's output without copy mode.

Commands run at the tmux command prompt#

Open the prompt with Ctrl+b, then :. Commands are typed without the leading tmux:

new-window -n logs
split-window -h
select-layout tiled
setw synchronize-panes on
source-file ~/.tmux.conf

Almost any tmux <command> from the shell can be typed at the prompt the same way, and it applies to the current session, window, and pane by default.

Keyboard shortcuts#

Shortcuts (such as Ctrl+b, then d) only work inside an attached tmux client. They are listed throughout this document and in Section 14.

10. Configuration with .tmux.conf#

Everything in this cheatsheet works without any configuration. This section is optional.

Configuration file location#

~/.tmux.conf

tmux reads this file when the server starts. Recent versions (3.1 and later) also look for ~/.config/tmux/tmux.conf (or $XDG_CONFIG_HOME/tmux/tmux.conf). Use only one location to avoid confusion.

If the file does not exist, create it with your editor:

nano ~/.tmux.conf

Back up an existing file before editing it:

cp ~/.tmux.conf ~/.tmux.conf.bak

Small optional example#

# Enable mouse support (click to select panes/windows, drag borders to resize,
# scroll wheel enters copy mode)
set -g mouse on

# Increase scrollback history (default: 2000 lines per pane)
set -g history-limit 10000

Optional broadcast-input toggle (custom binding, see 6.6):

# Ctrl+b, then S toggles synchronize-panes in the current window
bind-key S set-window-option synchronize-panes

This binding is a customization. It may conflict with an existing binding in your configuration or in a plugin; check with tmux list-keys | grep ' S '.

Reload the configuration#

From a shell:

tmux source-file ~/.tmux.conf

Or from the tmux command prompt (Ctrl+b, then :):

source-file ~/.tmux.conf

Reloading applies new settings to the running server. It does not undo settings you deleted from the file; those remain until you change them explicitly or the server restarts. Some settings (such as history-limit) only affect panes created afterwards.

Default vs customized behaviour#

Default tmux Optional customization
Prefix Ctrl+b Often changed (e.g. to Ctrl+a) – shortcuts in this guide then use your prefix
Mouse Off set -g mouse on
Scrollback 2000 lines set -g history-limit 10000
Copy-mode keys Emacs (vi if VISUAL/EDITOR contains vi) set -g mode-keys vi
Sync toggle :setw synchronize-panes bind-key S ...

If shortcuts in this guide do not behave as described, your system or user configuration may have changed them. Check Ctrl+b, then ?, or tmux list-keys.

11. Troubleshooting#

Diagnose first, then fix. None of the steps below requires killing sessions unless stated.

No tmux server running / no sessions found#

Symptom: no server running on /tmp/tmux-1000/default or error connecting to /tmp/tmux-1000/default (No such file or directory).

Diagnose:

tmux ls
whoami
  • Sessions belong to the user who started them. If you created the session as admin, you will not see it as root (and vice versa). sudo tmux ls looks at root's sessions.
  • Make sure you are on the correct machine (hostname).

Fix: switch to the right user or host. If there really are no sessions (for example, after a reboot), start a new one with tmux new -s name.

A session name cannot be found#

Symptom: can't find session: mysession.

Diagnose: tmux ls and compare names exactly (names are case-sensitive). Names containing . or : are altered by tmux, because those characters are used in targets.

Fix: use the exact name shown by tmux ls, or rename the session to something simple.

Unexpectedly creating duplicate sessions#

Symptom: tmux ls shows 0, 1, 2, work, ... because you ran plain tmux repeatedly.

Diagnose: tmux ls, then attach to each unknown session and check what is running before removing anything.

Fix: use tmux new-session -A -s work (or tmux attach -t work) instead of plain tmux. Clean up only sessions you have verified are unused (see Workflow F).

A session is not available after reconnecting to SSH#

Diagnose:

hostname          # same server? load-balanced hostnames may land you elsewhere
whoami            # same user?
uptime            # did the server reboot?
tmux ls
  • If uptime shows a recent boot, the session ended with the reboot.
  • If the user or host differs, connect to the right one.
  • If tmux ran with a custom socket (tmux -L name or -S path), you must use the same option: tmux -L name ls.
  • Some systems kill user processes at logout (systemd-logind KillUserProcesses). Check with your system administrator before changing login policies.

Nested tmux sessions#

Symptom: sessions should be nested with care, unset $TMUX to force.

Why it happens: you ran tmux or tmux attach from a shell that is already inside tmux ($TMUX is set). Nesting puts one tmux inside another, so the outer tmux captures Ctrl+b first, which is confusing.

Recommended approach:

  • To change sessions on the same server, do not nest – switch instead: Ctrl+b, then s, or tmux switch-client -t name.
  • To use tmux on a remote server from inside a local tmux, it is a deliberate nest. Press Ctrl+b twice (Ctrl+b, then Ctrl+b) to send the prefix to the inner tmux, for example Ctrl+b, Ctrl+b, d to detach the inner session.
  • Only force nesting on the same machine (TMUX= tmux new -s inner) when you understand that keys go to the outer session first and that the inner session is still managed by the same tmux server. Unsetting $TMUX does not "exit" the outer tmux; it just bypasses the safety check.

Scrollback not working as expected#

Diagnose: the mouse wheel or your terminal's scrollbar shows the terminal's own buffer, not tmux's pane history.

Fix: use copy mode (Ctrl+b, then [ or Page Up). If history is too short, increase history-limit (affects new panes only). Full-screen programs such as vim, less, or top use the alternate screen and do not add their screens to scrollback.

Mouse support disabled#

Diagnose: at the command prompt, run show-options -g mouse.

Fix: enable it for the running server with set -g mouse on, and add it to ~/.tmux.conf to make it permanent. Mouse support (mouse option) requires tmux 2.1 or later.

Clipboard copying not working#

Diagnose:

  • Paste inside tmux with Ctrl+b, then ]. If that works, tmux copy is fine and the issue is system clipboard integration.
  • Check show-options -s set-clipboard and whether your terminal emulator supports OSC 52 (some disable it by default).
  • On a local desktop, check whether xclip, xsel, or wl-copy is installed.

Fix: enable OSC 52 in your terminal emulator, or configure copy-command (tmux 3.2+) for your clipboard tool. Over SSH, remote clipboard tools cannot reach your local clipboard; rely on OSC 52 or your terminal's native Shift+drag selection.

Incorrect colors or unexpected key bindings#

Diagnose:

echo $TERM                   # inside tmux: usually tmux-256color or screen-256color
tmux show-options -g default-terminal
tmux list-keys | less
  • Colors: the default value of default-terminal depends on your tmux build and version. If colors look wrong, check that the terminal type is supported on the system (infocmp tmux-256color); a common fix is set -g default-terminal "tmux-256color" (or "screen-256color" on older systems).
  • Keys: a system-wide /etc/tmux.conf, your ~/.tmux.conf, or plugins may rebind keys or change the prefix. Your desktop or terminal emulator may also intercept combinations such as Ctrl+arrow or Alt+arrow.

A session still exists after its foreground process exited#

Diagnose: attach and look. Usually the program ended but the shell that launched it is still running, so the pane remains – this is normal. If the pane shows Pane is dead, the remain-on-exit option is on.

Fix: type exit in the shell to close the pane, or kill the pane with Ctrl+b, then x after confirming it is no longer needed. Use respawn-pane to restart a dead pane's command.

Permission or tmux socket errors#

Symptom: error connecting to /tmp/tmux-1000/default (Permission denied) or similar.

Diagnose:

id -u
ls -ld /tmp/tmux-$(id -u)
echo "$TMUX_TMPDIR"
  • The socket directory must be owned by your user and not accessible to others.
  • Running tmux with sudo can create root-owned sockets or files in the wrong place.
  • Cleaning tools that empty /tmp can remove sockets of running servers.

Fix: run tmux as your normal user, and avoid mixing sudo tmux with plain tmux.

If the socket was deleted (for example by a /tmp cleaner) while the server is still running, tmux can recreate it when the server process receives SIGUSR1. Identify the server first – it is the tmux process with no terminal (? in the TT column) – and signal only that PID:

ps -u "$USER" -o pid,tty,args | grep '[t]mux'
kill -USR1 <server-pid>

Broadcast input unexpectedly affecting multiple panes#

Diagnose and fix immediately (Ctrl+b, then :):

show-window-options synchronize-panes
setw synchronize-panes off

Then review every pane in the window to see what was executed where. If your configuration has a custom toggle (for example Ctrl+b, then S), it may have been pressed accidentally; consider the optional status-bar indicator in 6.6.

Broadcast input not reaching panes as expected#

Diagnose:

  • Are all target panes in the same window? Use Ctrl+b, then q to see the panes in the current window.
  • Is any target pane in copy mode (position indicator in its top-right corner)? Panes in a mode do not receive synchronized input. Press q in that pane.
  • Is the option on? show-window-options synchronize-panes.
  • In recent tmux versions, synchronize-panes can also be set per pane. A pane with its own off setting will not take part; check with show-options -p synchronize-panes in that pane.
  • Did a pane's program (password prompt, less, an editor) interpret the keys differently from a shell?

Expecting synchronize-panes to work across windows or sessions#

It does not. Synchronization is limited to panes in the current window. Move the panes into one window, or target others explicitly with tmux send-keys -t session:window.pane '...' Enter, or use an orchestration tool designed for multi-server operations.

Workflow A: Create and resume a named session#

tmux new -s work              # 1. create and attach
make test                     # 2. run something
# 3. detach: Ctrl+b, then d
tmux ls                       # 4. later: list sessions
tmux attach -t work           # 5. reattach

Workflow B: Avoid duplicate sessions#

tmux new-session -A -s work

The first run creates work; every later run attaches to the existing work session instead of creating 0, 1, 2, ...

Workflow C: Monitor a Linux server#

tmux new-session -d -s monitor -n main
tmux send-keys    -t monitor:main 'top' Enter
tmux split-window -h -t monitor:main
tmux send-keys    -t monitor:main.1 'journalctl -f' Enter
tmux split-window -v -t monitor:main.1
tmux attach -t monitor

Result: top on the left, live logs on the top right, and a free administration shell on the bottom right. (journalctl -f may need sudo or journal group membership to show all logs.)

Workflow D: Manage multiple servers#

tmux new-session -d -s servers -n web
tmux send-keys    -t servers:web 'ssh admin@web01.example.com' Enter
tmux split-window -h -t servers:web
tmux send-keys    -t servers:web.1 'ssh admin@web02.example.com' Enter
tmux new-window   -t servers -n db
tmux send-keys    -t servers:db 'ssh admin@db01.example.com' Enter
tmux attach -t servers
  • Group related hosts in one window (web), so you can broadcast to them if needed.
  • Put different roles in different windows (db), so a broadcast in web never reaches them.

tmux only organizes these terminal connections. It does not monitor, inventory, or orchestrate the servers.

Workflow E: Broadcast commands safely#

  1. Open the target servers in panes of one window (as in Workflow D).

  2. Check every pane: hostname, user, current directory.

  3. Ctrl+b, then :, then setw synchronize-panes on.

  4. Run hostname and confirm each pane prints a different, expected name.

  5. Run a shared, non-destructive command, for example:

    uptime; df -h /

  6. Review the output in every pane.

  7. Ctrl+b, then :, then setw synchronize-panes off.

Workflow F: Clean up sessions safely#

tmux ls                                    # 1. list everything
tmux list-windows -t old-project           # 2. inspect the candidate
tmux attach -t old-project                 # 3. (optional) look inside, then Ctrl+b, then d
tmux kill-session -t old-project           # 4. kill only the verified session
tmux ls                                    # 5. confirm the result

Never use tmux kill-server as routine cleanup.

13. Best Practices and Common Mistakes#

Best practices#

  • Name everything. Use sessions named after projects, servers, or tasks (web-deploy, db-migration), and name windows by purpose (logs, monitor).
  • One session per workspace. Use sessions for projects, servers, or administrative tasks.
  • Windows for unrelated tasks, panes for related ones. Separate unrelated tasks into different windows; split panes when tasks benefit from simultaneous visibility (an app and its log).
  • Detach, don't kill, when work should continue.
  • Start tmux on the remote server for long-running remote jobs, not on your laptop.
  • Log important output (tee, log files) – tmux scrollback is limited and lost when the session ends.
  • Keep .tmux.conf simple, documented, and backed up; keep sufficient scrollback history.
  • Keep synchronization off during normal interactive work, and check it before entering sensitive commands.

Common mistakes#

Mistake Consequence Better approach
Typing exit to "leave" tmux Closes the shell – and the pane/window/session if it was the last one Detach with Ctrl+b, then d
Running plain tmux every time Many unnamed duplicate sessions tmux new-session -A -s work
Killing a session without checking it Lost work or interrupted jobs tmux ls, inspect, then kill by exact name
Using kill-server for cleanup Every session ends Kill individual verified sessions
Running a command without checking the host Changes applied to the wrong server Check the prompt/hostname first
Leaving synchronize-panes on Later commands silently go to all panes Turn it off right after use
Expecting tmux to survive a reboot Work is lost Use logs, checkpoints, and proper services
Mixing sudo tmux and tmux "Missing" sessions, socket permission errors Run tmux as your normal user

Remember: tmux preserves terminal sessions. It does not guarantee machine or process reliability.

14. Quick Reference#

Session commands#

Task Command
New named session tmux new -s name
New session in background tmux new-session -d -s name
Attach or create tmux new-session -A -s name
List sessions tmux ls
Attach tmux attach -t name
Detach Ctrl+b, then d
Rename tmux rename-session -t old new
Kill one session ⚠ tmux kill-session -t name

Keyboard shortcuts (default)#

Area Action Shortcut
Sessions Detach Ctrl+b, then d
Sessions Choose session Ctrl+b, then s
Sessions Previous / next session Ctrl+b, then ( / )
Sessions Rename session Ctrl+b, then $
Windows New window Ctrl+b, then c
Windows Choose window Ctrl+b, then w
Windows Next / previous window Ctrl+b, then n / p
Windows Go to window by number Ctrl+b, then 0–9
Windows Rename window Ctrl+b, then ,
Panes Split left/right Ctrl+b, then %
Panes Split top/bottom Ctrl+b, then "
Panes Move between panes Ctrl+b, then an arrow key
Panes Show pane numbers Ctrl+b, then q
Panes Cycle layouts Ctrl+b, then Space
Panes Zoom / restore pane Ctrl+b, then z
Panes Kill pane (confirm) Ctrl+b, then x
Copy mode Enter copy mode / scroll Ctrl+b, then [ (or Page Up)
Copy mode Exit copy mode q
Copy mode Paste Ctrl+b, then ]
General Command prompt Ctrl+b, then :
General List all key bindings Ctrl+b, then ?

Broadcast-input commands#

Task Shortcut or Command
Split left/right Ctrl+b, then %
Split top/bottom Ctrl+b, then "
Move between panes Ctrl+b, then an arrow key
Zoom or restore a pane Ctrl+b, then z
Choose a window Ctrl+b, then w
Enable broadcast input Ctrl+b, then :, then setw synchronize-panes on
Disable broadcast input Ctrl+b, then :, then setw synchronize-panes off
Toggle broadcast input Ctrl+b, then :, then setw synchronize-panes
Check synchronization Ctrl+b, then :, then show-window-options synchronize-panes

Core concepts#

Session Window Pane
Is like A workspace A tab A split section of a tab
Contains Windows Panes One shell or program
Survives detach Yes Yes Yes
Create tmux new -s name Ctrl+b, then c Ctrl+b, then % or "
Navigate Ctrl+b, then s Ctrl+b, then w / n / p Ctrl+b, then arrow keys
Broadcast scope – synchronize-panes applies here Panes in that window receive input

Five everyday commands for Linux server administration#

tmux new-session -A -s work        # 1. get into your workspace (attach or create)
tmux ls                            # 2. see what is running
tmux attach -t maintenance         # 3. resume a specific job after reconnecting
# Ctrl+b, then d                   # 4. detach and leave work running
tmux kill-session -t old-project   # 5. remove one verified, unused session

Back to library

Keyboard shortcuts

/
Focus search
Esc
Close dialogs, menus and messages
?
Show this help
Ctrl S
Save in the admin editor