Skip to main content

Tmux.conf Basics

The ~/.tmux.conf file is the main configuration file for tmux. It runs a list of tmux commands on startup and defines your personal workspace behavior.

Learning Focus

Start with a minimal, well-understood config file. Add complexity only when you know what each line does.

Where the Config Lives​

# Personal config (per user)
~/.tmux.conf

# System-wide config
/etc/tmux.conf

# Verify where tmux looks
tmux show-options -g | head

Reloading Config​

# from inside tmux prompt
:source-file ~/.tmux.conf

# or from shell
tmux source-file ~/.tmux.conf

If you bind a reload key, you will not need to restart tmux after changes:

~/.tmux.conf
bind r source-file ~/.tmux.conf \; display "Config reloaded!"

Starter Configuration​

This is a production-ready baseline ~/.tmux.conf:

~/.tmux.conf
# ===========================
# General
# ===========================

# Change prefix to Ctrl+a (like GNU Screen)
unbind C-b
set -g prefix C-a
bind C-a send-prefix

# Reload config
bind r source-file ~/.tmux.conf \; display "Config reloaded!"

# Start windows and panes at index 1 (easier keyboard reach)
set -g base-index 1
setw -g pane-base-index 1

# Renumber windows when one is closed
set -g renumber-windows on

# Enable mouse
set -g mouse on

# Increase scrollback history
set -g history-limit 50000

# ===========================
# Display
# ===========================

# Use 256-color terminal
set -g default-terminal "screen-256color"

# Status bar refresh interval
set -g status-interval 5

# Status bar appearance
set -g status-bg colour235
set -g status-fg colour136

# ===========================
# Windows and Panes
# ===========================

# Intuitive split keys (remember current path)
bind | split-window -h -c "#{pane_current_path}"
bind - split-window -v -c "#{pane_current_path}"
unbind '"'
unbind %

# Vim-style pane navigation
bind h select-pane -L
bind j select-pane -D
bind k select-pane -U
bind l select-pane -R

# Repeatable pane resize
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

# ===========================
# Copy Mode
# ===========================

# Use vi key bindings in copy mode
setw -g mode-keys vi

# Enter copy mode with Ctrl+a [
bind [ copy-mode

# Vi-style selection and copy
bind-key -T copy-mode-vi v send-keys -X begin-selection
bind-key -T copy-mode-vi y send-keys -X copy-selection-and-cancel

Configuration Option Categories​

Global Options (set -g)​

set -g history-limit 50000      # scrollback lines
set -g base-index 1             # window numbering start
set -g mouse on                 # enable mouse
set -g status-interval 5        # status refresh (seconds)
set -g escape-time 0            # no delay for escape (important for vim)
set -g default-terminal "screen-256color"

Window Options (setw -g)​

setw -g mode-keys vi            # vi mode in copy mode
setw -g pane-base-index 1       # pane numbering start
setw -g automatic-rename off    # disable auto window renaming

Key Bindings (bind and unbind)​

bind key command              # prefix + key → command
bind -r key command           # repeatable binding
unbind key                    # remove existing binding
bind -n key command           # binding WITHOUT prefix (use with care)
warning

Bindings without prefix (bind -n) bypass the prefix entirely. Use sparingly — they can conflict with applications inside panes.

Checking Current Options​

# show all global options
tmux show-options -g

# show specific option
tmux show-option -g history-limit

# show window options
tmux show-window-options -g

Common Pitfalls​

PitfallSymptomFix
Config syntax errorTmux ignores rest of configCheck with tmux source-file ~/.tmux.conf for error messages
Forgetting to reloadChanges not appliedRun :source-file ~/.tmux.conf
Wrong setw vs setOption does not applyWindow options use setw, global use set
Escaping special charsBinding fails silentlyQuote keys like '"' for literal double-quote

What's Next​