Documentation · Manual Page Reference

tmux(1)
General Commands Manual

Full interactive web reference for tmux terminal multiplexer. Use the search bar to filter commands, flags, options, format specifiers, and environment variables.

NAME & SYNOPSIS

tmux — terminal multiplexer

tmux [-2uUV] [-C] [-c shell-command] [-f file] [-L socket-name] [-S socket-path] [command [flags]]

DESCRIPTION

tmux is a terminal multiplexer: it enables a number of terminals to be created, accessed, and controlled from a single screen. tmux may be detached from a screen and continue running in the background, then later reattached.

When tmux is executed, it creates a new session with a single window and displays it on screen. A status line at the bottom of the screen shows information on the current session and is used to enter interactive commands.

COMMAND LINE FLAGS

Global command line flags accepted when launching the tmux binary:

  • -2 — Force tmux to assume the terminal supports 256 colors
  • -u — Explicitly force UTF-8 support
  • -C — Start in Control Mode protocol client (iTerm2 Integration)
  • -f file — Specify an alternate configuration file (default: ~/.tmux.conf)
  • -L socket-name — Specify socket name under /tmp/tmux-UID/ for server isolation
  • -S socket-path — Specify exact socket path for multi-user session sharing
  • -V — Display tmux version string

QUICK START & COMMON COMMANDS

  • tmux new-session -s name — Create a named session (Session Guide)
  • tmux attach-session -t name — Attach to an existing session
  • tmux list-sessions (or tmux ls) — List active server sessions
  • tmux kill-session -t name — Terminate a specific session
  • tmux source-file ~/.tmux.conf — Reload config file (Config Reference)

KEY BINDINGS

tmux may be controlled from an attached client by using a key combination of a prefix key (by default Ctrl+b) followed by a command key.

  • Prefix + c — Create a new window
  • Prefix + % — Split current pane vertically into two
  • Prefix + " — Split current pane horizontally into two
  • Prefix + d — Detach the current client
  • Prefix + z — Toggle pane zoom mode
  • Prefix + [ — Enter copy mode (View All Keybindings)

OPTIONS & GLOBAL VARIABLES

Options may be set globally or per-session using the set-option (or set) command in ~/.tmux.conf.

Core Global Options

  • set -g default-terminal "tmux-256color" — Set terminal emulator color mode
  • set -g history-limit 50000 — Increase scrollback buffer lines
  • set -g mouse on — Enable mouse pane selection and scrolling
  • set -g base-index 1 — Start window numbering at 1 instead of 0
  • set -g renumber-windows on — Automatically renumber windows when one is closed

FORMAT SPECIFIERS

Format specifiers allow dynamic content customization in the status line, window titles, and commands using #{variable} syntax.

Specifier Description Example Value
#{session_name} (or #S) Name of the active tmux session dev-workspace
#{window_index} (or #I) Index number of the active window 1
#{window_name} (or #W) Name of the active window zsh / vim
#{pane_current_path} Current working directory of active pane /var/www/html
#{pane_pid} PID of the process running in active pane 40921
#{host} (or #H) Hostname of the server running tmux daemon prod-web-01

HOOKS & EVENT TRIGGERS

tmux hooks allow executing custom commands automatically when internal server events trigger (e.g. session creation, client attach, pane focus):

~/.tmux.conf (Hooks)

# Auto-notify when a new client attaches

set-hook -g client-attached 'display-message "Client attached!"'


# Set active pane border color dynamically on pane focus

set-hook -g pane-focus-in 'set -g pane-active-border-style fg=blue'

BUFFERS & PASTE MANAGEMENT

tmux maintains an internal stack of paste buffers populated whenever text is copied in copy-mode:

  • tmux list-buffers (or tmux ls-b) — List all saved copy buffers
  • tmux show-buffer — Display text contents of the most recent buffer
  • tmux paste-buffer (or Prefix + ]) — Paste most recent buffer into pane
  • tmux choose-buffer — Interactive buffer selector menu

FILES & ENVIRONMENT

  • ~/.tmux.conf — Default user configuration file
  • /etc/tmux.conf — System-wide default configuration file
  • /tmp/tmux-UID/default — Default UNIX domain socket path

FREQUENTLY ASKED QUESTIONS

What is the difference between tmux -L and -S?

-L specifies a socket name under /tmp/tmux-UID/ for local server isolation. -S specifies an exact file path for socket-based pair programming collaboration.

How do format variables work in tmux?

Format variables use #{variable} syntax to dynamically expand session names, PIDs, current working directories, or hostnames into status bars and scripts.