Sessions
| Command | What it does |
|---|---|
| Start a new unnamed session | |
| Start a session named work | |
| Attach to work if it exists, otherwise create it | |
| Create a session detached (scripts) | |
| List sessions | |
| Attach to work | |
| Attach to the most recent session | |
| Attach and detach any other client (after a dropped connection) | |
| Rename a session | |
| Switch sessions from inside tmux | |
| Kill one session | |
| Kill every session except the current one | |
| Kill everything |
| Key | Action |
|---|---|
| Detach, leaving the session running | |
| Pick a session from a list | |
| Rename the current session | |
| and | Previous and next session |
| Choose which client to detach |
Windows
Windows are tabs. The status bar at the bottom lists them by number.
| Key | Action |
|---|---|
| New window | |
| Rename the current window | |
| and | Next and previous window |
| to | Jump to a window by number |
| Last used window | |
| Pick a window from a list | |
| Find a window by name | |
| Move the window to another number | |
| Kill the window (asks first) |
| Command | What it does |
|---|---|
| New window named logs | |
| Rename the current window | |
| Kill window 2 | |
| Swap windows 2 and 1 | |
| Renumber the current window to 0 | |
| Switch by name |
Panes
opens a command prompt inside tmux; the commands below go there.
| Key | Action |
|---|---|
| Split left and right | |
| Split top and bottom | |
| , , , | Move to the pane in that direction |
| Next pane | |
| Last used pane | |
| Show pane numbers; press one to jump | |
| Zoom the pane to fill the window; again to unzoom | |
| , , , | Resize by one cell (hold to repeat) |
| , , , | Resize by five cells |
| and | Swap the pane with the previous or next one |
| Cycle through the built-in layouts | |
| Break the pane out into its own window | |
| Rotate the panes in the window | |
| Kill the pane (asks first) |
| Command | What it does |
|---|---|
| Resize 10 cells left (, , for the others) | |
| Zoom, same as | |
| Equal columns (, , also exist) | |
| Move the pane from window 2 into window 1 | |
| Type into every pane at once ( to stop) | |
| Swap with the pane above | |
| Kill every pane except the current one |
Copy Mode and Scrolling
enters copy mode, which is also how you scroll back. Keys depend on : emacs by default, vi after .
| Action | emacs (default) | vi |
|---|---|---|
| Enter copy mode | ||
| Scroll | , , , | Same, plus , , , |
| Top and bottom of history | and | and |
| Start and end of line | and | and |
| Search backward | ||
| Search forward | ||
| Next and previous match | and | and |
| Start selecting | ||
| Toggle rectangle selection | ||
| Copy the selection and exit | ||
| Exit without copying | or |
| Command | What it does |
|---|---|
| Paste the last copied text | |
| Pick from earlier copies | |
| Print the last copy | |
| Write the last copy to a file | |
| Put text into the paste buffer from a script | |
| Wheel scrolls, drag selects, click switches panes (in ) | |
| Lines of scrollback per pane (default 2000; applies to new panes) |
Copies land in tmux's buffer, not the system clipboard. The config below pipes them to ; on Linux use or .
Prefix Key and Keybindings
| Key | Action |
|---|---|
| List every keybinding | |
| Command prompt | |
| Send a literal Ctrl+b to the program in the pane | |
| Big clock (any key dismisses it) | |
| Suspend the tmux client ( resumes) |
| Command | What it does |
|---|---|
| Remap the prefix to Ctrl+a (screen style) | |
| Free the old prefix | |
| Let reach the program in the pane | |
| Reload config with | |
| Bind without the prefix (), here Alt+Left moves left | |
| Remove a binding | |
| Show the vi copy-mode bindings | |
| Type into a session from outside (scripts) |
Config
The file is . tmux 3.1 and newer also read (or ), and a system-wide loads first when it exists. Changes apply to the running server after a reload.
| Command | What it does |
|---|---|
| Reload the config | |
| Same, from inside tmux | |
| Print the global options | |
| Show the current prefix | |
| Start with a different config file | |
| Version; binding syntax changed in 2.4, so check this when a snippet fails |
A minimal :
# Prefix on Ctrl+a, like screen
set -g prefix C-a
unbind C-b
bind C-a send-prefix
set -g mouse on
set -g history-limit 50000
set -g base-index 1
setw -g pane-base-index 1
setw -g mode-keys vi
set -g default-terminal "tmux-256color"
set -sg escape-time 10
# Splits that open in the current directory
bind | split-window -h -c "#{pane_current_path}"
bind - split-window -v -c "#{pane_current_path}"
bind r source-file ~/.tmux.conf \; display "Reloaded"
# vi-style select and copy to the system clipboard
bind -T copy-mode-vi v send -X begin-selection
bind -T copy-mode-vi y send -X copy-pipe-and-cancel "pbcopy"Swap for on X11 or on Wayland.
Status Bar
The bar at the bottom is configured with options, in or live from .
| Command | What it does |
|---|---|
| Show the bar ( hides it, toggles) | |
| Move the bar to the top of the screen | |
| Redraw every 5 seconds (default 15) | |
| Centre the window list (, ) | |
| Left side; is the session name | |
| Widen the left side (default 10, it truncates) | |
| Right side; formats work | |
| Colours for the bar itself | |
| Style for the active window | |
| Colours for the command prompt line | |
| Print one format variable, to test it |
Anything in is a format variable (, ); runs a shell command and shows its output. Colours accept names, to , or , and 256-colour styles only render once is set.
Plugins
Most tmux plugins are installed through TPM, the tmux Plugin Manager. Clone it once:
git clone https://github.com/tmux-plugins/tpm ~/.tmux/plugins/tpmThen list plugins in , keeping the line last:
set -g @plugin 'tmux-plugins/tpm'
set -g @plugin 'tmux-plugins/tmux-sensible'
set -g @plugin 'tmux-plugins/tmux-resurrect'
set -g @plugin 'tmux-plugins/tmux-continuum'
set -g @plugin 'tmux-plugins/tmux-yank'
run '~/.tmux/plugins/tpm/tpm'| Key or command | What it does |
|---|---|
| Install everything listed in the config (capital I) | |
| Update plugins, with a picker | |
| Remove plugins no longer listed in the config | |
| Add a plugin; any GitHub repo works | |
| tmux-resurrect: save the current layout to disk | |
| tmux-resurrect: restore the saved layout | |
| tmux-continuum: restore automatically when the server starts |
Plugins land in , or if your config lives under , in which case clone TPM there instead. does nothing until the config with the lines has been sourced at least once.
Install
tmux is not preinstalled on macOS and is missing from most minimal images and containers.
| Command | What it does |
|---|---|
| Debian, Ubuntu, Raspberry Pi OS | |
| Fedora, RHEL, Rocky, AlmaLinux ( on CentOS 7) | |
| Alpine | |
| Arch | |
| macOS | |
| then | Windows, inside a WSL distro |
| Confirm the version you ended up with | |
| Show which copy is first in |
Windows has no native tmux. Run it under WSL, or run it on the Linux host you connect to and let the client pass the keys through; the PuTTY cheat sheet covers that side. With no root on the remote box, check for screen first, since it is preinstalled more often, and fall back to building tmux from source with (it needs libevent and ncurses headers).
Gotchas
- The prefix is a sequence, not a chord. Press Ctrl+b, release, then the key. Holding Ctrl through the whole thing sends Ctrl+c, Ctrl+d, and friends instead.
- Copy mode copies to tmux's own buffer. Nothing reaches the system clipboard until you add a binding or turn on on a terminal that supports it.
- A dropped SSH connection does not kill tmux. Reconnect and run ; if it says the session is attached, . This is the reason to start every long job inside tmux; see ssh broken pipe for stopping the drops themselves.
- With , the terminal's native drag-select is taken over by tmux. Hold Shift (Option in iTerm2, Fn in Terminal.app) to select with the terminal instead.
- Inside tmux over SSH inside another tmux, press the prefix twice to reach the inner one, or give the remote a different prefix.
- Vim feels sluggish on Esc until is in the config.
- Snippets using are for tmux 2.3 and older. Modern tmux wants .
- A reboot kills the tmux server and every session in it. Dropped connections are survivable, power cycles are not; see the Plugins section for .
- Coming from screen: the prefix is Ctrl+b instead of Ctrl+a, and is . The screen cheat sheet has the rest of the key mapping.