Configuration

tmux works fine with no configuration at all, but a few lines make it far more pleasant: mouse support, more scrollback, easier split keys, and a status bar you can read at a glance. This guide explains where the file lives, how its settings work, and walks through a complete starter config line by line.

Where the config file lives

When the tmux server starts, it reads the first of these that exists:

• ~/.tmux.conf, the traditional location.
• $XDG_CONFIG_HOME/tmux/tmux.conf, or ~/.config/tmux/tmux.conf if that variable is not set.

Before your own file, tmux also reads a system-wide config if one is installed, for example /etc/tmux.conf (or /opt/homebrew/etc/tmux.conf with Homebrew on Apple silicon). Most people only ever need ~/.tmux.conf.

The config is only read when the server starts. Opening a new terminal and attaching to an existing session does not reload it. See reloading and testing below.

How settings work

A config file is just a list of tmux commands, one per line, run from top to bottom. Lines that start with # are comments. Three commands do most of the work:

• set (short for set-option) changes an option, such as set -g mouse on.
• bind (short for bind-key) connects a key to a command, such as bind r source-file ~/.tmux.conf.
• unbind removes a key binding, such as unbind C-b.

Options live at different levels. -g sets the global value that every session and window uses unless it is changed for one of them, and almost every set in a config file should use it. setw (or set -w) is for window options and set -s for server options, although for built-in options tmux works out the level from the name. The set-option reference covers every flag.

Reloading and testing

After editing the file, apply it to the running server:

tmux source-file ~/.tmux.conf

You can also press Ctrl+b : and type source-file ~/.tmux.conf. Two more commands help when something goes wrong:

# Check for syntax errors without applying anything
tmux source-file -n ~/.tmux.conf
 
# Try a config on a separate test server, leaving your real sessions alone
tmux -L test -f ~/new.tmux.conf new -s trial
tmux -L test kill-server

Reloading only runs the lines that are in the file. If you delete a line, its old setting stays active until you restart tmux with tmux kill-server, which also ends every session.

Essential configuration

A modern, production-ready ~/.tmux.conf to start from. Drop it in your home directory and reload.

# ~/.tmux.conf
 
# ============================================
# ESSENTIAL SETTINGS
# ============================================
 
# Fix Vim ESC delay (tmux 3.5+ already defaults to 10ms)
set -sg escape-time 0
 
# Increase scrollback buffer
set -g history-limit 50000
 
# Start windows and panes at 1, not 0
set -g base-index 1
setw -g pane-base-index 1
 
# Enable mouse support
set -g mouse on
 
# Enable focus events for vim autoread
set -g focus-events on
 
# Set terminal with proper colors
set -g default-terminal "tmux-256color"
set -as terminal-features ",xterm-256color:RGB"
 
# Aggressive resize for multi-client
setw -g aggressive-resize on
 
# ============================================
# KEY BINDINGS
# ============================================
 
# Change prefix to Ctrl+a (more ergonomic)
unbind C-b
set -g prefix C-a
bind C-a send-prefix
 
# Reload config
bind r source-file ~/.tmux.conf \; display "Config reloaded!"
 
# Better pane splitting (and keep current path)
bind | split-window -h -c "#{pane_current_path}"
bind - split-window -v -c "#{pane_current_path}"
bind c new-window -c "#{pane_current_path}"
 
# Vim-style pane navigation
bind h select-pane -L
bind j select-pane -D
bind k select-pane -U
bind l select-pane -R
 
# Vim-style pane resizing
bind -r H resize-pane -L 5
bind -r J resize-pane -D 5
bind -r K resize-pane -U 5
bind -r L resize-pane -R 5
 
# ============================================
# APPEARANCE
# ============================================
 
# Status bar position
set -g status-position top
 
# Status bar colors
set -g status-style 'bg=#13161d fg=#8b949e'
set -g status-left-length 20
set -g status-right-length 50
 
# Status bar content
set -g status-left '#[fg=#00e68a,bold] #S #[fg=#30363d]│ '
set -g status-right '#[fg=#30363d]│#[fg=#8b949e] %H:%M #[fg=#30363d]│#[fg=#8b949e] %d-%b-%y '
 
# Window status
setw -g window-status-format ' #I:#W '
setw -g window-status-current-format '#[fg=#00e68a,bold] #I:#W '
 
# Pane border colors
set -g pane-border-style 'fg=#30363d'
set -g pane-active-border-style 'fg=#00e68a'
 
# Pane scrollbars — show scrollback position (tmux 3.6+)
set -g pane-scrollbars on
set -g pane-scrollbars-position right
 
# Message styling
set -g message-style 'bg=#00e68a fg=#000000 bold'
 
# ============================================
# COPY MODE
# ============================================
 
# Use vi keys
setw -g mode-keys vi
 
# Vi-style copy bindings
bind -T copy-mode-vi v send -X begin-selection
bind -T copy-mode-vi y send -X copy-pipe-and-cancel "pbcopy"  # macOS
# bind -T copy-mode-vi y send -X copy-pipe-and-cancel "xclip -selection clipboard -i"  # Linux
 
# ============================================
# PLUGINS (via TPM)
# ============================================
 
# Install TPM first:
# git clone https://github.com/tmux-plugins/tpm ~/.tmux/plugins/tpm
 
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'
 
# Plugin settings
set -g @resurrect-strategy-vim 'session'
set -g @continuum-restore 'on'
 
# Initialize TPM (keep at bottom)
run '~/.tmux/plugins/tpm/tpm'

What this config does

You don't have to take the whole file. Here is what each part changes, so you can keep only the parts you want.

Essential settings

• escape-time 0 removes the short pause tmux adds after the Escape key, which otherwise makes leaving insert mode in Vim feel laggy. Recent tmux already defaults to 10 milliseconds.
• history-limit 50000 keeps 50,000 lines of scrollback per pane instead of 2,000. It only affects panes opened after the change.
• base-index 1 and pane-base-index 1 number windows and panes from 1, so the first window is Ctrl+a 1, right next to the prefix, instead of 0 at the far end of the keyboard.
• mouse on lets you click panes and windows, drag borders, and scroll with the wheel.
• focus-events on tells programs like Vim when their pane gains or loses focus, which some editor features rely on.
• default-terminal and terminal-features turn on 256 colors and true (24-bit) color, so editor themes look right inside tmux.
• aggressive-resize on sizes each window to the client that is actually looking at it, which helps when the same session is open on screens of different sizes.

Key bindings

• The prefix moves from Ctrl+b to Ctrl+a, which many people find easier to reach. bind C-a send-prefix means pressing Ctrl+a twice sends a real Ctrl+a to the program, which shells use to jump to the start of the line.
• r reloads the config and shows a short message. This replaces the default r binding, which redraws the screen.
• | and - split the pane side by side or top and bottom, and like c they open in the current pane's folder instead of the session's starting folder.
• h, j, k, l move between panes Vim-style, and H, J, K, L resize by five cells. The -r flag lets you keep pressing the resize key without the prefix for half a second.

Appearance

The status bar moves to the top and gets muted colors, with the session name on the left and the time and date on the right. The current window is highlighted in green, as is the border of the active pane. pane-scrollbars (tmux 3.6 and later) shows where you are in each pane's scrollback. Older tmux versions report an unknown option for it; delete those two lines if you see that error.

Copy mode

mode-keys vi switches copy mode to Vim-style keys. The two bindings make v start a selection and y copy it straight to the macOS clipboard with pbcopy. On Linux, use the commented xclip line instead, or wl-copy on Wayland. The copy and paste guide covers clipboards in depth, including over SSH.

Plugins

The last block uses TPM, the tmux plugin manager. Install it once with the git clone command in the comment, reload the config, then press Ctrl+a I (capital i) to download the plugins. tmux-sensible adds widely agreed defaults, and tmux-resurrect with tmux-continuum save your sessions so they can be restored after a restart. The run line must stay at the very bottom. Browse more in the plugin directory.

Status line customization

Personalize your status bar with session info, system stats, and custom indicators. The status line is built from three options: status-left, the window list in the middle, and status-right. Inside them, #{...} inserts a value, #[...] changes the style, #(...) runs a shell command, and %H:%M-style codes show the time. status-interval (15 seconds by default) controls how often it refreshes.

# Format variables
#{session_name}       # Current session
#{window_index}       # Window number
#{window_name}        # Window name
#{pane_current_path}  # Current directory
#{host}               # Hostname
#{?window_zoomed_flag,🔍,}  # Conditional
 
# Shell commands
#(uptime | cut -d "," -f 3)  # Load average
#(date +%H:%M)               # Custom time

Advanced key bindings

Create powerful custom bindings for your workflow.

# No prefix needed (-n flag)
bind -n C-t new-window
 
# Repeatable binding (-r flag)
bind -r C-Up resize-pane -U
 
# Conditional logic
if-shell 'test -n "$SSH_CLIENT"' \
  'set -g status-bg blue'

Feature availability varies by tmux version — for example, OSC 52 clipboard (set-clipboard) Since 3.2 and per-pane scrollbars (pane-scrollbars) Since 3.6. Use the version switcher in the sidebar to see what applies to your version.

Common mistakes

• Forgetting -g. Without it, set changes only the current session, so new sessions don't get the setting. In a config file, use set -g.
• Changing the prefix without send-prefix. If you move the prefix to Ctrl+a, add bind C-a send-prefix, or you lose the ability to send Ctrl+a to programs.
• Expecting a reload to undo deleted lines. Reloading only applies what is in the file. Use tmux kill-server for a truly fresh start.
• Putting plugin settings after the TPM run line. Settings and @plugin lines below it are read too late. Keep run '~/.tmux/plugins/tpm/tpm' last.
• Copying options from old guides. Options such as utf8, status-utf8, and mode-mouse were removed years ago and now cause errors. Paste your file into the config validator to spot them.
• Testing on your real sessions. Use tmux -L test -f new.conf to try big changes on a separate server first.