🪟 tmux Quick Reference

tmux [command] [flags]
tmux new -A -s main

tmux is a terminal multiplexer. It lets you run several terminals inside ONE terminal window, split the screen into panes, and (the big one) DETACH
from a session and come back later, with everything still running. Start a long job over SSH, close your laptop, reconnect tomorrow, and it is still
there. That is why sysadmins live in it. It also gives you tabs (windows), scrollback, copy and paste, and scripted layouts. This sheet covers the
essentials, a good ~/.tmux.conf, scripting, plugins and troubleshooting. Screen is the older equivalent: see the comparison near the end.
The default "prefix" key is Ctrl+b. Almost every tmux key is: press Ctrl+b, release it, THEN press the key. Written below as  Prefix + key.

Server      One background process per user that owns everything. It keeps running after you close your terminal. (tmux kill-server stops it)
Session     A workspace: a set of windows. You attach to it and detach from it. Give each project its own named session
Window      Like a browser tab inside a session. It fills the whole screen
Pane        A rectangle inside a window. You split windows into panes to see several shells at once
Hierarchy:  server > sessions > windows > panes.  Names show in the status bar at the bottom: [session] 0:bash* 1:vim  (the * marks the current window)

sudo apt install tmux                            # Debian/Ubuntu         sudo dnf install tmux    Fedora/RHEL family        brew install tmux    macOS
tmux -V                                          # version (3.x is current). Behavior and option names vary between versions, so check yours
tmux new -A -s main                              # the one command to remember: attach to session "main", creating it if needed

tmux                                             # start a new unnamed session (named 0, 1, 2...)
tmux new -s work                                 # new session named "work"          tmux new -s work -n editor    also name the first window
tmux new -s work -d                              # create it DETACHED (in the background, do not attach)
tmux new -A -s main                              # attach if it exists, otherwise create it (great in ~/.bashrc or SSH commands)
tmux ls                                          # list sessions        tmux list-sessions
tmux attach -t work                              # attach to "work"     (tmux a -t work,  tmux a  attaches to the most recent session)
tmux attach -t work -d                           # attach and kick off other clients (useful when the terminal size is stuck small)
tmux attach -t work -r                           # attach READ-ONLY (a safe way to watch)
tmux switch-client -t other                      # from inside tmux, jump to another session
tmux rename-session -t 0 work                    # rename          tmux kill-session -t work    end a session
tmux kill-session -a                             # kill all sessions except the current one          tmux kill-server    stop everything
tmux has-session -t work && echo exists          # test in scripts
Prefix + d        Detach (leave the session running, return to your normal shell)          Prefix + D    Choose a client to detach
Prefix + s        Pick a session from a list (arrow keys, Enter)           Prefix + (   Prefix + )    Previous / next session          Prefix + L    Last session
Prefix + $        Rename the current session                               Prefix + w    Pick any window in any session (a tree)
Over SSH:  ssh user@server -t 'tmux new -A -s main'      # log in and land straight in your session (the -t gives tmux a terminal)
If the connection drops, tmux keeps everything running. Just SSH back in and run  tmux attach  (or the same command).

Prefix + c        Create a new window                Prefix + ,      Rename the window           Prefix + &     Kill the window (asks first)
Prefix + n / p    Next / previous window             Prefix + l      Last (previously used) window
Prefix + 0..9     Jump to window by number           Prefix + w      Choose from a tree of sessions and windows
Prefix + f        Find a window by name or text      Prefix + .      Move the window (to another number)          Prefix + '    Prompt for a window index
tmux new-window -n logs -c '#{pane_current_path}'     # new window in the same directory
tmux rename-window -t 2 build       tmux select-window -t work:2      tmux move-window -t work:5      tmux swap-window -s 1 -t 3      tmux kill-window -t 2
tmux link-window -s other:1 -t 4                       # show one window in two sessions
Window numbers start at 0 by default. Many people set  base-index 1  (see the config) so the keys match the keyboard layout.

Prefix + %        Split into LEFT and RIGHT panes (a vertical dividing line)             tmux split-window -h
Prefix + "        Split into TOP and BOTTOM panes (a horizontal dividing line)           tmux split-window -v
Prefix + arrow    Move to the pane in that direction                       Prefix + o    Cycle to the next pane         Prefix + ;    Last pane
Prefix + q        Flash the pane numbers, then press a number to jump there
Prefix + x        Close the pane (asks first)                              Prefix + z    ZOOM: make the pane full screen. Press again to restore (great for reading output)
Prefix + {  }     Swap the pane with the previous / next one               Prefix + Ctrl+o    Rotate panes         Prefix + Space    Cycle through layouts
Prefix + !        Break the pane out into its own window                   tmux join-pane -s :2      Pull window 2 into this window as a pane
Prefix + Ctrl+arrow   Resize by 1 cell        Prefix + Alt+arrow    Resize by 5 cells         tmux resize-pane -L 10  (also -R -U -D)       tmux resize-pane -Z    zoom
Prefix + Alt+1..5     Layouts: even-horizontal, even-vertical, main-horizontal, main-vertical, tiled          tmux select-layout tiled
Prefix + m / M    Mark / unmark a pane (then  swap-pane -s '{marked}'  swaps the current pane with it)
Prefix + t        Show a clock          Prefix + i    Show window info         Prefix + q    Pane numbers
tmux split-window -h -c '#{pane_current_path}'        # split and stay in the same directory
tmux split-window -h 'htop'                           # open a pane running a command (it closes when the command ends)
tmux split-window -v -p 30                            # bottom pane taking 30% (tmux 3.x uses  -l 30%  )
tmux swap-pane -U / -D        tmux select-pane -T "logs"      # give the pane a title       tmux select-pane -P 'bg=colour235'    a background color
Synchronize panes (type once, send to ALL panes in the window: great for the same command on many servers):
Prefix + :   then   setw synchronize-panes on      (off to stop).  Or bind a key (see the config). The status bar shows SYNC in some themes: be careful, it is easy to forget it is on.

Prefix + [        Enter copy mode (you can now scroll and select).  Prefix + PageUp    enters and scrolls up
Keys in copy mode (default is EMACS style. With  mode-keys vi  they are vi-style):
                      emacs                     vi
Move                  arrow keys, PageUp/Down   h j k l, Ctrl+u / Ctrl+d (half page), Ctrl+b / Ctrl+f (page), g (top), G (bottom)
Start selection       Ctrl+Space                Space  (or v with the config below)
Copy and leave        Alt+w  or  Enter          Enter  (or y with the config below)
Search down / up      Ctrl+s / Ctrl+r           /  and  ?     then  n / N  for next / previous match
Quit copy mode        q  or  Esc                q  or  Esc
Prefix + ]        Paste the most recent buffer          Prefix + =    Choose a paste buffer from a list          Prefix + #    List buffers
tmux list-buffers        tmux show-buffer        tmux save-buffer ~/copied.txt        tmux load-buffer file.txt        tmux paste-buffer -b 0        tmux delete-buffer -b 0
tmux capture-pane -p -S -3000 > ~/pane.txt        # save the last 3000 lines of the pane's scrollback to a file (-p prints, -S start line, negative = history)
tmux capture-pane -pJ -S - -E -                   # the WHOLE history (joined lines)
With the mouse on (see the config) you can scroll with the wheel and select with the mouse. To use the terminal's own selection instead, hold Shift while dragging.
System clipboard: tmux buffers are separate from your desktop clipboard. Options:
   set -g set-clipboard on                        # tmux asks the terminal to set the clipboard using an escape sequence (OSC 52). Works in many modern terminals, even over SSH
   bind -T copy-mode-vi y send -X copy-pipe-and-cancel "xclip -selection clipboard -i"      # Linux with xclip     (wl-copy on Wayland,  pbcopy on macOS)
The tmux-yank plugin does this for you on most systems.

Prefix + :        Open the tmux command prompt. Type any tmux command without the word "tmux", for example  new-window -n logs  or  setw synchronize-panes
Prefix + ?        List all key bindings (search with / , quit with q)                tmux list-keys | grep copy-mode-vi        tmux list-commands
Prefix + ~        Show recent tmux messages         tmux show-messages         tmux info        tmux show-options -g     global options       tmux show-window-options -g
Prefix + r        (only if you add the reload binding below)                 man tmux    is excellent. Search with /   (for example /copy-mode)
Every key binding is just a tmux command, so anything you can type in the shell as  tmux <command>  you can also bind or run from the prompt.

tmux reads ~/.tmux.conf (and ~/.config/tmux/tmux.conf in newer versions) when the SERVER starts. Reload later without restarting:
tmux source-file ~/.tmux.conf              or, in tmux:   Prefix + :   source-file ~/.tmux.conf
A solid starter file (tmux 3.x). Lines starting with # are comments:
# ---- General ----
set -g default-terminal "tmux-256color"            # proper colors (needs the tmux-256color terminfo entry; use "screen-256color" if it is missing)
set -ga terminal-overrides ",*256col*:Tc"          # enable true (24-bit) color in terminals that support it
set -g history-limit 50000                         # a big scrollback
set -g escape-time 10                              # no half-second delay after Esc (helps vim users a lot)
set -g focus-events on                             # let editors know when the window gains/loses focus
set -g mouse on                                    # scroll, click panes, drag borders, select text
set -g set-clipboard on                            # try to copy to the system clipboard
set -g base-index 1                                # windows start at 1
setw -g pane-base-index 1                          # panes start at 1
set -g renumber-windows on                         # no gaps in window numbers after closing one
set -g automatic-rename on                         # window name follows the running program
set -g aggressive-resize on                        # size windows by the smallest client that VIEWS them (multiple people/screens)
set -g display-time 2000                           # messages stay 2 seconds
# ---- Keys ----
unbind C-b                                         # optional: use Ctrl+a as the prefix (like GNU screen)
set -g prefix C-a
bind C-a send-prefix                               # press Ctrl+a twice to send a real Ctrl+a to the program (also useful for nested tmux)
bind r source-file ~/.tmux.conf \; display-message "Config reloaded"
bind | split-window -h -c "#{pane_current_path}"   # easy-to-remember splits that keep the current folder
bind - split-window -v -c "#{pane_current_path}"
bind c new-window -c "#{pane_current_path}"
unbind '"'
unbind %
bind h select-pane -L                              # vim-style pane movement with the prefix
bind j select-pane -D
bind k select-pane -U
bind l select-pane -R
bind -n M-Left  select-pane -L                     # Alt+arrows move between panes WITHOUT the prefix
bind -n M-Right select-pane -R
bind -n M-Up    select-pane -U
bind -n M-Down  select-pane -D
bind -r H resize-pane -L 5                         # -r lets you press the key repeatedly
bind -r J resize-pane -D 5
bind -r K resize-pane -U 5
bind -r L resize-pane -R 5
bind S setw synchronize-panes \; display-message "sync #{?synchronize-panes,ON,OFF}"       # toggle typing in all panes at once
# ---- Copy mode (vi keys) ----
setw -g mode-keys vi
bind -T copy-mode-vi v send -X begin-selection
bind -T copy-mode-vi C-v send -X rectangle-toggle
bind -T copy-mode-vi y send -X copy-pipe-and-cancel "xclip -selection clipboard -i"       # macOS: pbcopy    Wayland: wl-copy
# ---- Look ----
set -g status-position bottom
set -g status-interval 5
set -g status-style "bg=colour235,fg=colour250"
set -g status-left "#[bold]#S #[nobold]| "
set -g status-left-length 30
set -g status-right "#H | %Y-%m-%d %H:%M"
setw -g window-status-current-style "bg=colour33,fg=colour231,bold"
set -g pane-border-style "fg=colour238"
set -g pane-active-border-style "fg=colour33"
set -g message-style "bg=colour33,fg=colour231"
setw -g monitor-activity on                        # highlight windows with new output
set -g visual-activity off
Options are set with set (session options) and setw / set -w (window options). -g means global. Check the value of anything:  tmux show -g escape-time
Conditional settings (tmux versions differ):  if-shell "[ $(tmux -V | cut -d' ' -f2 | cut -c1) -ge 3 ]" "set -g mouse on" "set -g mouse-select-pane on"
Names with colors: colour0 to colour255, or names (red, blue) or hex (#ff8800).

#S session name   #I window index   #W window name   #F window flags (* current, - last, # activity)   #P pane index   #T pane title   #H hostname   #h short hostname
#(command)   output of a shell command (refreshed every status-interval seconds), e.g.  #(uptime | cut -d, -f3)       %H:%M   time in strftime format      #{pane_current_path}   #{session_windows}
#[fg=red,bold]  color and style inside a status string          #{?condition,yes,no}   conditional text

Put this in a script such as ~/bin/dev. It builds a session with an editor, a shell and a log window, and only creates it if it does not exist:
#!/usr/bin/env bash
SESSION=dev
tmux has-session -t "$SESSION" 2>/dev/null || {
  tmux new-session -d -s "$SESSION" -n editor -c ~/project
  tmux send-keys -t "$SESSION:editor" 'vim .' C-m
  tmux split-window -h -t "$SESSION:editor" -c ~/project
  tmux split-window -v -t "$SESSION:editor.2" -c ~/project
  tmux send-keys -t "$SESSION:editor.3" 'git status' C-m
  tmux new-window -t "$SESSION" -n logs
  tmux send-keys -t "$SESSION:logs" 'tail -f /var/log/syslog' C-m
  tmux select-window -t "$SESSION:editor"
  tmux select-pane -t "$SESSION:editor.1"
}
tmux attach -t "$SESSION"
Targets look like  session:window.pane  for example  dev:editor.2 . send-keys types text into a pane (C-m is Enter). Use -l to send text literally.
More scripting:
tmux send-keys -t work:1.2 'systemctl status nginx' Enter          # run a command in another pane, from anywhere
tmux list-sessions -F '#{session_name}: #{session_windows} windows'   # formats print any tmux data. list-panes -a -F '#{session_name}:#{window_index}.#{pane_index} #{pane_current_command}'
tmux display-message -p '#S'                                       # the current session name           display-message -p '#{pane_current_path}'
tmux pipe-pane -o 'cat >> ~/tmux-#S-#I.log'                         # LOG everything a pane prints to a file (run it again to stop)
tmux wait-for -S done                                              # signal / wait: in one pane  tmux wait-for done  then in another  tmux wait-for -S done
tmux run-shell "notify-send 'build finished'"                      # run a shell command from tmux         tmux run-shell -b   in the background
Ready-made session managers: tmuxinator and tmuxp (YAML files describing your layout), and smug. Handy for repeatable project workspaces.

tmux new -d -s backup 'rsync -a /data /mnt/backup'        # run a job in a detached session, then  tmux attach -t backup  to look at it (the session ends when the command finishes)
tmux new -d -s job 'my-long-script.sh; echo DONE; read'    # keep the window open at the end so you can read the output
Compare with nohup: tmux gives you a live terminal you can re-attach to, with scrollback and the ability to type into it. Use systemd services or cron for things that must survive reboots:
tmux does NOT survive a reboot. (Plugins like tmux-resurrect can restore the layout, not the running processes.)

Same user, different terminals:   tmux attach -t work     Both people see and control the same panes. Use  attach -r  for watch-only
Different users on one machine (with a shared socket):
   User A:   tmux -S /tmp/pair new -s pair          then    chmod 770 /tmp/pair     (and put both users in a common group, chgrp thatgroup /tmp/pair)
   User B:   tmux -S /tmp/pair attach -t pair       (use  attach -r  for read-only)
Independent windows on the same session ("grouped sessions"): tmux new -t work -s work2    each client can look at a different window while sharing the same set of windows.
Only share sessions with people you trust: they can run commands as you. Do not put a shared socket in a world-writable location without controlling who can use it.

git clone https://github.com/tmux-plugins/tpm ~/.tmux/plugins/tpm
Add to the END of ~/.tmux.conf:
set -g @plugin 'tmux-plugins/tpm'
set -g @plugin 'tmux-plugins/tmux-sensible'            # sensible defaults
set -g @plugin 'tmux-plugins/tmux-resurrect'           # save and restore sessions:  Prefix + Ctrl+s  save    Prefix + Ctrl+r  restore
set -g @plugin 'tmux-plugins/tmux-continuum'           # automatic saving and restoring     set -g @continuum-restore 'on'
set -g @plugin 'tmux-plugins/tmux-yank'                # copy to the system clipboard
set -g @plugin 'tmux-plugins/tmux-pain-control'        # nicer pane keys
run '~/.tmux/plugins/tpm/tpm'
Then reload the config and press  Prefix + I  (capital i) to install.    Prefix + U    update       Prefix + Alt+u    remove unlisted plugins
Other popular plugins: tmux-fzf, tmux-thumbs / tmux-fingers (copy things on screen with hints), tmux-open, vim-tmux-navigator (Ctrl+h/j/k/l between vim and tmux panes), catppuccin and dracula themes.
Plugins run code inside your session. Install only ones you trust.

If you run tmux locally and again on the server, Prefix goes to the OUTER tmux. Send it to the INNER one by pressing the prefix twice (with  bind C-a send-prefix  from the config).
A cleaner way: use a different prefix on the server (for example C-a there and C-b locally), or turn the outer tmux off temporarily (Prefix + : then  set prefix None ).
Check where you are:  echo $TMUX   (set when inside tmux). tmux refuses to start inside tmux ("sessions should be nested with care"). To override:  TMUX= tmux   or   unset TMUX.
Status bars: give the two tmux instances different colors so you can tell them apart at a glance (for example a red status bar on production servers).

tmux compared with screen and terminal tabs
tmux            Active development, splits and panes, scriptable, plugins, good defaults. The usual choice today
screen          Older and very widely installed. Works with serial lines. Fewer features: panes are clumsier and scripting is limited. Prefix Ctrl+a
terminal tabs   Great for local work, but they die when the connection or the window does. Combine: use tmux INSIDE any terminal
Zellij          A newer multiplexer with friendlier defaults and floating panes. Not the same commands
Screen cheat: screen -S name (new)  screen -ls  screen -r name (reattach)  Ctrl+a d (detach)  Ctrl+a c (new window)  Ctrl+a n / p (next / previous)  Ctrl+a " (window list)

# The safe way to run something long on a server
ssh server; tmux new -A -s upgrade; sudo apt upgrade   # then Prefix + d to leave, and  tmux attach -t upgrade  to return

# A monitoring wall in one window
tmux new -s mon 'htop' \; split-window -h 'watch -n1 df -h' \; split-window -v 'journalctl -f' \; select-pane -t 0

# Type the same command on several servers at once
for h in web1 web2 web3; do tmux split-window "ssh $h"; tmux select-layout tiled; done ; tmux setw synchronize-panes on

# Save the whole scrollback of the current pane
tmux capture-pane -pJ -S - > ~/session-$(date +%F).txt

# Kill every session except the current one
tmux kill-session -a

# Reattach to the session that was used last, or start one
tmux attach || tmux new

# Log a pane's output to a file for the record
tmux pipe-pane -o 'cat >> ~/tmux-#S.log'

# Rename all windows by their current folder (a nice status line)
set -g automatic-rename-format '#{b:pane_current_path}'        # put this in ~/.tmux.conf

# Start tmux automatically for SSH logins (add to ~/.bashrc, careful: test with a second session open)
if [[ -z "$TMUX" && -n "$SSH_CONNECTION" && $- == *i* ]]; then tmux new -A -s main; fi

# Show a message when a long command finishes (run in a pane)
long-command; tmux display-message "long-command finished"

# See who is attached to which session
tmux list-clients -F '#{client_tty} attached to #{session_name}'

# Kill the server when things are badly wedged (ends ALL sessions)
tmux kill-server

Colors look wrong, or vim/ls colors are dull        Set  default-terminal "tmux-256color"  and enable true color:  set -ga terminal-overrides ",*256col*:Tc"  Outside tmux, make sure $TERM is xterm-256color
"open terminal failed: missing or unsuitable terminal: tmux-256color"    The terminfo is missing on that machine. Use  screen-256color  in ~/.tmux.conf, or install ncurses-term
Delay after pressing Esc in vim                     Add  set -g escape-time 10  (the default 500 ms is what you feel)
The mouse wheel scrolls the terminal, not tmux       Turn on  set -g mouse on . To copy with the terminal's own selection hold Shift (or Alt on some terminals) while dragging
Text I copy in tmux is not in my clipboard          tmux buffers are separate. Use set-clipboard on (OSC 52), tmux-yank, or a copy-pipe binding with xclip / wl-copy / pbcopy
"no server running on /tmp/tmux-1000/default"       No sessions exist (the server exited). Start one with  tmux new -s main . Also happens if you run tmux as a different user or with a different socket (-L or -S)
"sessions should be nested with care, unset $TMUX to force"    You are already inside tmux. Detach first, or use  switch-client , or  TMUX= tmux  to nest on purpose
"protocol version mismatch" after upgrading          The old server is still running with the old version. Run  tmux kill-server  (this ends running sessions: detach and save work first) or restart the machine
Sessions vanished after a reboot                    tmux does not survive reboots. Use tmux-resurrect and tmux-continuum to restore layouts, and systemd for services
My prefix does not work                              You may be in a nested tmux, or the terminal captured the keys (some GUI terminals use Ctrl+b). Try  Prefix + :  or check  tmux show -g prefix
Ctrl+Left / Ctrl+Right or Home/End do not work      Key sequences differ by terminal. Use  set -g xterm-keys on  (older versions), or bind the sequences seen with  cat -v
New panes open in the home directory                Use  -c "#{pane_current_path}"  in the split and new-window bindings (tmux 1.9+)
Window names keep changing (bash, vim...)           automatic-rename. Turn off with  setw -g automatic-rename off  or  set -g allow-rename off  and rename by hand
Config change has no effect                         Reload with source-file. Some settings (like terminal options) only apply to NEW sessions or after  kill-server . Check errors printed on reload
"unknown option" / "unknown command" errors         Your tmux is older than the config. Check  tmux -V , or wrap settings in if-shell version checks
Bindings from a tutorial do not work                Syntax changed in 2.4 (copy-mode-vi table) and 3.x (-l 30% instead of -p 30). Search the tutorial's tmux version
Copy mode selection keys differ                     mode-keys is emacs by default (even if your EDITOR is vim). Set  setw -g mode-keys vi  to get v / y
Pane output freezes or looks garbled                Press Prefix + r if bound, or  Ctrl+l , or  tmux refresh-client -S . Check the terminal size with  stty size
Everything is tiny after attaching from a second device   The smallest attached client sets the size. Use  tmux attach -d  (detach others), or  set -g aggressive-resize on
Slow with large output                              Reduce history-limit, avoid programs that redraw constantly, and do not run  cat hugefile  in a pane you need
Unicode or box-drawing characters look wrong        Start with  tmux -u  or set the locale (LANG=en_US.UTF-8 or C.UTF-8) on the server too
Nested SSH: keys go to the wrong tmux               Press the prefix twice, or use different prefixes locally and remotely

    Memorize the essentials first: tmux new -A -s main, Prefix + d (detach), Prefix + c (new window), Prefix + % and " (split), Prefix + z (zoom), Prefix + [ (scroll and copy).

    Use tmux for every long job over SSH so a dropped connection cannot kill it. Name sessions by project and re-attach with tmux new -A -s NAME.

    Put a small ~/.tmux.conf in place: mouse on, 50,000 lines of history, escape-time 10, base-index 1, vi keys in copy mode, and splits that keep the current directory.

    Rebinding the prefix to Ctrl+a is popular, but Ctrl+b works everywhere without any config. Know both if you use shared servers.

    Zoom a pane (Prefix + z) to read long output, and capture-pane -p to save it. Use pipe-pane to log an important session.

    Be careful with synchronize-panes. Turn it off as soon as you are done so you do not run a command on every server by accident.

    Script your standard workspace with new-session -d, split-window and send-keys, or use tmuxinator or tmuxp.

    tmux does not survive a reboot. Use systemd services for anything that must, and tmux-resurrect for restoring your layout.

    Check tmux -V. Syntax and options changed between 1.x, 2.x and 3.x, so match tutorials to your version.

    Share sessions only with people you trust: an attached user can run commands as you.