tmux docs: the tmux user guide and reference

What is tmux?

tmux is a free, open-source terminal multiplexer for Linux, macOS, the BSDs and Windows (through WSL). It lets one terminal hold many shells, and keeps them running when you disconnect. It is released under the ISC license and was created by Nicholas Marriott in 2007.

tmux has a client-server design. The first tmux command starts a background server that owns everything; your terminal is a client attached to it. Inside the server are sessions, each session has windows (shown like tabs in the status line), and each window is split into panes, each running its own program. Because the server does not depend on the client, closing the terminal or losing SSH only ends the client: you reattach and everything is still there. More on what tmux is and why people use it.

The learning path

The sections below follow this order. Click a step to jump to it.

1. Install tmux -V
2. First session tmux new -s work
3. Prefix key prefix ?
4. Sessions tmux ls
5. Windows and panes prefix %
6. Copy mode prefix [
7. Configure ~/.tmux.conf
8. Automate send-keys

What's new in tmux 3.8

tmux 3.8, tagged on 8 October 2026, is the current release. The changes you will notice first:

• Floating panes grow up. Move and resize them from the keyboard (Ctrl+b g), float or tile any pane with Ctrl+b @, swap them, and create modal panes with new-pane -O. Floating panes guide.
• The mouse is on by default, and the status line is yellow-green on 256-color terminals thanks to a new theme option with built-in light and dark themes.
• Fuzzy switchers: Ctrl+b Tab finds a window and Ctrl+b Shift+Tab finds a session.
• Event hooks and monitors for scripts (set-hook -B, wait-for -E), auto-hiding scrollbars, copy mode that refreshes live, and Ctrl+b T to set a pane title.

Earlier releases added floating panes (3.7), pane scrollbars (3.6), and a 10 ms Escape delay instead of 500 ms plus the mirrored layouts (3.5). Ubuntu 24.04 still ships 3.4, so check with tmux -V. Full release notes, version history and how to upgrade.

Install and update tmux

tmux is in every major package manager. The one-line installs:

# macOS (Homebrew)
$ brew install tmux
# Ubuntu / Debian
$ sudo apt update && sudo apt install tmux
# Fedora / RHEL
$ sudo dnf install tmux
# Arch Linux
$ sudo pacman -S tmux
# Alpine
$ apk add tmux
# Check what you got
$ tmux -V
tmux 3.8

Homebrew, Arch, Alpine edge and Fedora 44 have 3.8. LTS distributions are older: Ubuntu 24.04 ships 3.4, Ubuntu 22.04 3.2a and Debian 13 3.5a, so build from source if you need 3.8 features. On Windows, install WSL2 and then tmux inside Linux. Full guides: macOS, Ubuntu and other Linux, Windows (WSL2, psmux, MSYS2).

To update tmux, upgrade the package (brew upgrade tmux, sudo apt upgrade tmux) and then restart the server with tmux kill-server: a running server keeps its old version until it exits. How to upgrade, step by step.

Getting started: your first tmux session

Every key binding starts with the prefix: press Ctrl+b, let go, then press the key. In the list below, "prefix %" means Ctrl+b then %.

$ tmux new -s work          # start a session called "work"
# prefix %                  split left / right
# prefix "                  split top / bottom
# prefix ←↑→↓               move between panes (or click: the mouse is on in 3.8)
# prefix c                  new window;  prefix n / p  next / previous
# prefix d                  detach: everything keeps running
$ tmux ls                   # list sessions
work: 1 windows (created Wed Oct 28 09:14:02 2026)
$ tmux attach -t work       # come back

Try these keys without installing anything in the tmux playground, or follow the five-minute tutorial on the homepage.

The prefix key

tmux listens for one key combination, the prefix (Ctrl+b by default), and treats the next key as a command. Everything else goes to the program in the pane. Ctrl+b ? lists all bindings, and pressing the prefix twice sends the prefix key itself to the program. Many people move the prefix to Ctrl+a, which is easier to reach and matches GNU Screen:

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

Pick your prefix here and every key on this site follows it:

Changing the prefix, and every default key

Sessions

A session is a named workspace of windows that lives in the server until you kill it. Detach from it and it keeps running; attach from any terminal or SSH login.

$ tmux new -s api              # create and attach
$ tmux new -d -s logs          # create in the background
$ tmux new -A -s api           # attach if it exists, create if not
$ tmux ls                      # list sessions
$ tmux attach -t api           # attach (tmux a -t api)
$ tmux rename-session -t api backend
$ tmux kill-session -t logs    # close one session
$ tmux kill-server             # close every session

Inside tmux, Ctrl+b d detaches, Ctrl+b s shows a session tree, Ctrl+b $ renames, and in 3.8 Ctrl+b Shift+Tab opens a fuzzy session switcher. Name your sessions: unnamed ones are numbered 0, 1, 2 and are hard to tell apart.

Sessions guide: create, switch, rename, kill, nesting, save and restore

Sharing a session

Two terminals attached to the same session see and control the same screen, which is how pair programming in tmux works. For two accounts on one machine, share the server socket and grant access:

# You: start a server on a shared socket, readable by your team's group
$ tmux -S /tmp/pair new -d -s pair
$ chgrp devteam /tmp/pair && chmod g+rw /tmp/pair
$ tmux -S /tmp/pair server-access -a alice      # tmux 3.3+: allow alice
# Alice:
$ tmux -S /tmp/pair attach -t pair

Never chmod 777 a socket: anyone who can attach can run commands as you. Sharing sessions · remote pair programming guide.

Windows

Windows are the tabs of a session, listed in the status line as 0:editor* (the * marks the current one). Each has its own panes.

# prefix c          new window          prefix ,      rename window
# prefix n / p      next / previous     prefix 0-9    go to window 0-9
# prefix w          window tree         prefix Tab    fuzzy window switcher (3.8)
# prefix &          close window        prefix .      move to another index
$ tmux new-window -n logs -c ~/app
$ tmux move-window -t 3
$ tmux swap-window -t 0

Windows guide: create, rename, reorder, close

Panes

Panes split one window into several terminals. Split with Ctrl+b % (left/right) and Ctrl+b " (top/bottom), move with Ctrl+b ← and the other arrows, zoom one to full size with Ctrl+b z, and close it with Ctrl+b x.

# prefix q          show pane numbers   prefix o      next pane
# prefix C-arrow    resize by 1 cell    prefix M-arrow  resize by 5
# prefix { / }      swap with previous / next pane
# prefix !          break pane into its own window
$ tmux split-window -h -l 30%       # new pane on the right, 30% wide
$ tmux resize-pane -L 10
$ tmux join-pane -s :2              # bring window 2's pane into this window

Floating panes (3.7+) sit on top of the split layout instead of taking space: Ctrl+b * creates one, and in 3.8 Ctrl+b @ floats or tiles the current pane. Floating panes guide.

Panes guide: split, resize, zoom, swap, join and close

Synchronize panes

To type the same thing into every pane of a window, for example to run a command on several servers at once, turn on synchronize-panes:

setw synchronize-panes on
setw synchronize-panes off
# toggle it with prefix e
bind e setw synchronize-panes

More in synchronize panes.

Layouts

tmux has seven preset layouts. Ctrl+b Space cycles through them, Ctrl+b Alt+1 to Ctrl+b Alt+7 pick one, and Ctrl+b E spreads the panes out evenly.

The key numbers above are the real 3.8 bindings (checked with tmux list-keys); the order in the man page's key list differs. From a script: tmux select-layout main-vertical; size the main pane with set -w main-pane-width 60%. Layouts in depth.

Copy mode and scrollback

A pane does not scroll like a normal terminal: to see earlier output, enter copy mode with Ctrl+b [ (or scroll the mouse wheel, since the mouse is on in 3.8), move around, search and copy, then press q to leave. tmux keeps 2,000 lines per pane by default (history-limit).

tmux uses vi keys automatically when $VISUAL or $EDITOR contains "vi"; force them with setw -g mode-keys vi. Copy mode guide: scroll, search, select, paste, buffers.

Copy to the system clipboard

By default tmux copies into its own paste buffers and also sends the text to your terminal with the OSC 52 escape sequence (set-clipboard external), which puts it on the system clipboard in terminals that allow it, even over SSH. If yours does not, pipe the copy to a clipboard tool:

# macOS
bind -T copy-mode-vi y send-keys -X copy-pipe-and-cancel "pbcopy"
# Linux, X11
bind -T copy-mode-vi y send-keys -X copy-pipe-and-cancel "xclip -in -selection clipboard"
# Linux, Wayland
bind -T copy-mode-vi y send-keys -X copy-pipe-and-cancel "wl-copy"
# Windows (WSL)
bind -T copy-mode-vi y send-keys -X copy-pipe-and-cancel "clip.exe"

Clipboard setup for every terminal · clipboard not working?

The configuration file

tmux reads /etc/tmux.conf and then each of ~/.tmux.conf, $XDG_CONFIG_HOME/tmux/tmux.conf and ~/.config/tmux/tmux.conf that exists. Changes apply when the server starts; to apply them to a running server, run tmux source ~/.tmux.confCopy.

tmux 3.8's defaults are already sensible: the mouse is on, the Escape delay is 10 ms and the terminal type is tmux-256color. These are the settings people still change most:

set -g history-limit 50000          # scrollback per pane (default 2000)
set -g base-index 1                 # number windows from 1
setw -g pane-base-index 1           # and panes
set -g renumber-windows on          # no gaps after closing a window
set -g mouse on                     # default since 3.8; needed on older versions
set -s escape-time 10               # default since 3.5; was 500 ms
set -as terminal-features ',xterm-256color:RGB'   # true color in xterm-like terminals

Config reference: every option and its 3.8 default

Prefer to click? The config generator builds a commented file with a live preview, and Oh my tmux! is a popular ready-made configuration.

Key bindings

# prefix r reloads the config
bind r source-file ~/.tmux.conf \; display "Reloaded"
# Alt+arrow moves between panes without the prefix (-n = no prefix)
bind -n M-Left select-pane -L
bind -n M-Right select-pane -R
# remove a default binding
unbind '"'
# split in the current directory
bind | split-window -h -c "#{pane_current_path}"

tmux list-keys shows every binding and tmux list-keys -N the ones with notes. bind and unbind in depth.

Status bar

The status line shows the session, the window list and, on the right, the pane title and time. tmux 3.8 colors it from the new theme option, which follows your terminal's light or dark mode; set theme terminal for the old colors.

set -g status-position top
set -g status-interval 5
set -g status-left " #S | "
set -g status-right " %H:%M %d %b  #h "
set -g status-style "bg=#1e1e2e,fg=#cdd6f4"
setw -g window-status-current-style "fg=#89b4fa,bold"

Status bar options · 3.8 themes · true color.

Plugins and TPM

The tmux plugin manager (TPM) installs plugins from GitHub with one line each in your config.

$ git clone https://github.com/tmux-plugins/tpm ~/.tmux/plugins/tpm
# in ~/.tmux.conf:
#   set -g @plugin 'tmux-plugins/tpm'
#   set -g @plugin 'tmux-plugins/tmux-resurrect'
#   run '~/.tmux/plugins/tpm/tpm'          (keep this line at the very bottom)
$ tmux source ~/.tmux.conf
# then: prefix I installs, prefix U updates, prefix M-u removes unlisted plugins

Plugins worth knowing

Plugins guide: TPM, the best plugins and themes, troubleshooting

Scripting and automation

Every tmux action is a command you can run from a shell, so a script can build a whole workspace. Formats (-F '#{pane_id}') return state as text and control mode (tmux -C) gives programs a live connection.

#!/usr/bin/env bash
# create the session once, then just attach
if ! tmux has-session -t =dev 2>/dev/null; then
  tmux new-session -d -s dev -n editor -c ~/projects/app
  tmux send-keys -t =dev:editor 'nvim .' Enter
  pane=$(tmux split-window -h -t =dev:editor -c ~/projects/app -P -F '#{pane_id}')
  tmux send-keys -t "$pane" 'npm run dev' Enter
  tmux new-window -t =dev: -n git -c ~/projects/app
fi
tmux attach -t =dev

The commands scripts use most: send-keys (type into a pane), capture-pane -p (read it), has-session (exit code 0 if it exists), display -p '#{…}' (ask for any value), wait-for (wait for a signal) and if-shell / run-shell (run shell commands from tmux).

tmux scripting and API: send-keys, capture-pane, hooks, control mode, libtmux

Session managers

If you would rather describe a workspace in YAML than write a script, use a session manager: tmuxinator (Ruby), tmuxp (Python, can also freeze a running session) or smug (Go). They are compared, with the same workspace in each, in tmuxinator vs tmuxp vs smug. Integrations with editors and tools have their own guides: Neovim, Claude Code, iTerm2, Ghostty.

tmux over SSH

Start tmux on the remote machine, not on your laptop: then a dropped connection only kills the client, and your programs keep running on the server.

# connect and attach to "work", creating it if needed (-t gives tmux a terminal)
$ ssh -t user@server tmux new -A -s work
# after a disconnect
$ ssh user@server
$ tmux attach -t work

To attach automatically on every SSH login, add this line to ~/.bashrc on the server:

[ -n "$SSH_CONNECTION" ] && [ -z "$TMUX" ] && tmux new -A -s main

Sessions over SSH · SSH problems and fixes.

Remote pair programming

Two people can work in one tmux session over SSH: both log in to the same machine and attach to a shared socket. tmux 3.3 and later also need each guest allowed with server-access, and can make a guest read-only.

# host
$ tmux -S /tmp/pair new -d -s pair
$ chgrp devteam /tmp/pair && chmod g+rw /tmp/pair
$ tmux -S /tmp/pair server-access -a guest       # read-write
$ tmux -S /tmp/pair server-access -a -r viewer   # read-only
$ tmux -S /tmp/pair attach -t pair
# guest (over SSH)
$ tmux -S /tmp/pair attach -t pair               # add -r to attach read-only

Remote pair programming guide

Default key bindings

The 20 bindings you will use most. All 93 are on the cheat sheet, with a printable PDF.

Environment variables

Check whether a script runs inside tmux with [ -n "$TMUX" ] && echo inside. tmux also keeps its own environment per session: tmux show-environment and set-environment.

Format strings

Formats are #{…} expressions that expand to live values. The status line, -F options and display -p all use them.

$ tmux display -p '#S:#I.#P #{pane_current_command}'
work:0.0 bash
$ tmux display -a | head -3        # every format and its value

More than 250 formats are documented in man tmux: formats; using them in scripts is covered in tmux scripting.

Getting help

• Inside tmux: Ctrl+b ? lists key bindings, Ctrl+b : then list-commands lists commands, and Ctrl+b ~ shows recent tmux messages.
• The manual: man tmux is the complete reference; man tmux explained maps it.
• Something broken? Troubleshooting covers no server running, sessions should be nested with care, wrong colors, a slow Escape key, a clipboard that does not copy and more.
• Every command: the commands reference lists all 92 with flags and the target syntax (-t session:window.pane).

Guides and integrations

Frequently asked questions

Something wrong or out of date on this page? Email hello@tmux.app and we will fix it.