tmux options control behavior and appearance at different scopes. Options are organized into server, session, window, and pane levels.
Option Commands
set-option
Set an option value:
set-option [-aFgopqsuw] [-t target] option [value]
Aliases: set
Flags:
-g: Set global option (server-level)
-w: Set window option
-s: Set server option
-p: Set pane option
-a: Append to string options (array options)
-u: Unset option (revert to default)
-F: Expand formats in value
-q: Suppress errors
Examples:
# Set server option
set -s default-terminal "tmux-256color"
# Set global session option
set -g status-position top
# Set window option
set -w monitor-activity on
# Append to array option
set -ga terminal-overrides ",xterm-256color:Tc"
show-options
Display option values:
show-options [-AgHpqsvw] [-t target] [option]
Aliases: show
Flags:
-g: Show global options
-w: Show window options
-s: Show server options
-A: Show all options (including defaults)
-v: Show only the value
-H: Show option type and metadata
Option Scopes
From options-table.c:25-32, tmux organizes options by scope:
Server Options
Server options affect the entire tmux server. Set with set -s or set-option -s.
Key server options:
# Backspace key code (default: 127)
set -s backspace ^?
# Maximum number of paste buffers
set -s buffer-limit 50
# Default terminal type
set -s default-terminal "tmux-256color"
# Editor for editing files
set -s editor vim
# Time to wait for escape key (milliseconds)
set -s escape-time 10
# Whether to exit when no sessions
set -s exit-empty on
# Whether to exit when no attached clients
set -s exit-unattached off
# Request extended keys from terminal
set -s extended-keys on
# Send focus events to applications
set -s focus-events on
# Command prompt history file
set -s history-file ~/.tmux_history
# Maximum server messages to keep
set -s message-limit 1000
# Set clipboard behavior
set -s set-clipboard on
# Terminal feature overrides
set -sa terminal-overrides ",xterm*:RGB"
# Terminal features (auto-detect supplements)
set -sa terminal-features "xterm*:clipboard:ccolour:cstyle:focus:title"
From options-table.c:277-554, these are the master server option definitions.
Session Options
Session options affect individual sessions. Set with set -g for global or set -t session: for specific sessions.
Key session options:
# Action on activity alert (none/any/current/other)
set -g activity-action other
# Time to assume paste vs typing (milliseconds)
set -g assume-paste-time 1
# First window index
set -g base-index 0
# Action on bell (none/any/current/other)
set -g bell-action any
# Default command for new panes
set -g default-command ""
# Default shell
set -g default-shell /bin/bash
# Initial size of new sessions (WIDTHxHEIGHT)
set -g default-size 80x24
# Destroy unattached sessions
set -g destroy-unattached off
# What to do when session destroyed
set -g detach-on-destroy on
# Display panes time (milliseconds)
set -g display-panes-time 1000
# Display panes colors
set -g display-panes-active-colour red
set -g display-panes-colour blue
# Status message display time (milliseconds)
set -g display-time 750
# Pane scrollback history limit (lines)
set -g history-limit 2000
# Default key table
set -g key-table root
# Lock after time (seconds, 0=never)
set -g lock-after-time 0
# Lock command
set -g lock-command "lock -np"
# Status line position (top/bottom)
set -g status-position bottom
# Status line visibility (off/on/2/3/4/5)
set -g status on
# Status update interval (seconds)
set -g status-interval 15
# Window list position (left/centre/right/absolute-centre)
set -g status-justify left
# Status line styling
set -g status-style "bg=green,fg=black"
set -g status-left "[#{session_name}] "
set -g status-left-length 10
set -g status-left-style default
set -g status-right '"#{=21:pane_title}" %H:%M %d-%b-%y'
set -g status-right-length 40
set -g status-right-style default
# Mouse support
set -g mouse off
# Prefix key
set -g prefix C-b
set -g prefix2 None
# Renumber windows when one is closed
set -g renumber-windows off
# Repeat time for repeatable bindings (milliseconds)
set -g repeat-time 500
# Set terminal title
set -g set-titles off
set -g set-titles-string "#S:#I:#W - \"#T\" #{session_alerts}"
# Visual bell/activity/silence alerts
set -g visual-activity off
set -g visual-bell off
set -g visual-silence off
From options-table.c:556-1054, these are the session option definitions.
Window Options
Window options affect individual windows. Set with set -w or setw.
Key window options:
# Aggressive resize behavior
set -w aggressive-resize off
# Allow applications to use passthrough sequences
set -w allow-passthrough off
# Allow window renaming by applications
set -w allow-rename off
# Allow pane title setting by applications
set -w allow-set-title on
# Allow alternate screen
set -w alternate-screen on
# Automatic window renaming
set -w automatic-rename on
set -w automatic-rename-format "#{?pane_in_mode,[tmux],#{pane_current_command}}#{?pane_dead,[dead],}"
# Clock mode
set -w clock-mode-colour blue
set -w clock-mode-style 24
# Copy mode colors
set -w copy-mode-match-style "bg=cyan,fg=black"
set -w copy-mode-current-match-style "bg=magenta,fg=black"
set -w copy-mode-mark-style "bg=red,fg=black"
# Fill character for unused space
set -w fill-character ""
# Main pane size in main layouts
set -w main-pane-height 24
set -w main-pane-width 80
# Other pane size in main layouts
set -w other-pane-height 0
set -w other-pane-width 0
# Copy mode key bindings (emacs/vi)
set -w mode-keys emacs
# Mode style (copy mode, etc)
set -w mode-style "bg=yellow,fg=black"
# Monitor window for activity
set -w monitor-activity off
# Monitor window for bell
set -w monitor-bell on
# Monitor window for silence (seconds)
set -w monitor-silence 0
# Pane borders
set -w pane-active-border-style "fg=green"
set -w pane-border-style "default"
set -w pane-border-format "#{pane_index} \"#{pane_title}\""
set -w pane-border-indicators colour
set -w pane-border-lines single
set -w pane-border-status off
# Pane colors (256 color palette override)
set -w pane-colours ""
# Remain on exit behavior
set -w remain-on-exit off
# Synchronize input to all panes
set -w synchronize-panes off
# Window size calculation (largest/smallest/manual/latest)
set -w window-size latest
# Window status formats
set -w window-status-format "#I:#W#{?window_flags,#{window_flags}, }"
set -w window-status-current-format "#I:#W#{?window_flags,#{window_flags}, }"
set -w window-status-separator " "
# Window status styles
set -w window-status-style default
set -w window-status-current-style default
set -w window-status-last-style default
set -w window-status-activity-style reverse
set -w window-status-bell-style reverse
From options-table.c:1056-1550, these are the window option definitions.
Pane Options
Some options can be set at the pane level (per-pane basis):
# Set option for specific pane
set -p -t:.1 allow-passthrough on
# Pane-specific options include:
set -w -p remain-on-exit on
set -w -p window-style "bg=colour234"
set -w -p window-active-style "bg=colour232"
Option Types
From options-table.c:34-111, tmux options have different types:
String Options
set -g status-left "[#{session_name}]"
set -s default-terminal "screen-256color"
Number Options
set -g history-limit 10000
set -s escape-time 0
Flag Options (Boolean)
set -g mouse on
set -w monitor-activity off
Choice Options
# One of: emacs, vi
set -w mode-keys vi
# One of: left, centre, right, absolute-centre
set -g status-justify centre
# One of: top, bottom
set -g status-position top
Color Options
# Named colors
set -g status-bg green
set -g status-fg black
# 256 colors
set -g status-bg colour235
# RGB colors
set -g status-bg "#1a1a1a"
Style Options
Style options combine multiple attributes:
set -g status-style "bg=green,fg=black,bold"
set -w window-status-current-style "bg=red,fg=white,underscore"
Array Options
Array options can have multiple values:
# Append to array
set -ga terminal-overrides ",xterm*:RGB"
set -ga terminal-features "screen*:title"
# Set entire array
set -g command-alias[0] "split-pane=split-window"
set -g command-alias[1] "splitp=split-window"
Many options support format variables that are expanded at runtime:
# Session info
set -g status-left "[#{session_name}] "
# Window info
set -w window-status-format "#I:#W#{?window_flags,#{window_flags}, }"
# Pane info
set -w pane-border-format "#{pane_index} #{pane_title}"
# Conditional formats
set -w automatic-rename-format "#{?pane_in_mode,[tmux],#{pane_current_command}}"
Common format variables:
#{session_name} - Session name
#{window_index} - Window index
#{window_name} - Window name
#{pane_index} - Pane index
#{pane_title} - Pane title
#{pane_current_command} - Current command in pane
Command Aliases
From options-table.c:294-306, command aliases allow shorthand for common commands:
set -s command-alias[0] "split-pane=split-window"
set -s command-alias[1] "splitp=split-window"
set -s command-alias[2] "server-info=show-messages -JT"
set -s command-alias[3] "info=show-messages -JT"
Option Inheritance
Options inherit from broader scopes:
- Pane options inherit from window options
- Window options inherit from session options
- Session options inherit from global options
- Global options use built-in defaults
You can override at any level:
# Set globally
set -g status-position bottom
# Override for specific session
set -t mysession status-position top
Viewing Options
# Show all server options
show -s
# Show all global session options
show -g
# Show all window options
show -w
# Show specific option
show -g status-position
# Show only the value
show -gv status-position
# Show all options with defaults
show -A
Unsetting Options
Revert an option to its default value:
# Unset option (revert to default)
set -u status-position
# Unset for specific target
set -u -t mysession status-position
Common Configuration Patterns
Status Line Configuration
set -g status on
set -g status-position top
set -g status-justify centre
set -g status-style "bg=colour235,fg=colour15"
set -g status-left "[#S] "
set -g status-left-length 20
set -g status-right "%H:%M %d-%b-%y"
set -g status-right-length 40
set -g status-interval 60
Window Status Configuration
set -w window-status-format " #I:#W "
set -w window-status-current-format " #I:#W "
set -w window-status-style "fg=colour240"
set -w window-status-current-style "bg=colour235,fg=colour15,bold"
set -w window-status-activity-style "bg=colour235,fg=colour208"
set -w window-status-bell-style "bg=colour235,fg=colour196"
Terminal Configuration
set -s default-terminal "tmux-256color"
set -sa terminal-features ",xterm-256color:RGB"
set -sa terminal-overrides ",xterm-256color:Tc"
set -s escape-time 10
set -s focus-events on
Mouse Configuration
set -g mouse on
# Disable drag to resize panes
unbind -n MouseDrag1Border
Some options only take effect for new sessions, windows, or panes. Changes to default-terminal, for example, only affect newly created sessions.