Option Commands

Commands for setting, showing, and managing tmux options and environment variables

Overview

tmux has numerous options that control its behavior and appearance. Options can be set at different scopes: server (global), session, window, or pane.

Option Scopes

• Server (global) options: Apply to the entire tmux server
• Session options: Apply to a specific session
• Window options: Apply to a specific window
• Pane options: Apply to a specific pane

set-option

Alias: set

set-option [-aFgopqsuUw] [-t target-pane] option [value]

Set a window option, session option, or server option.

-a · flag

Append to a string option. For array options, append to the list.

-F · flag

Expand formats in the option value.

-g · flag

Set a global session or window option. This sets the default for all sessions or windows.

-o · flag

Prevent setting an option that is already set.

-p · flag

Set a pane option. Pane options are inherited from the window options.

-q · flag

Suppress errors about unknown or ambiguous options.

-s · flag

Set a server option.

-u · flag

Unset an option. For inherited options (window or pane), inherit the value from the parent scope.

-U · flag

Unset an option without inheriting (removes the option completely).

-w · flag

Set a window option. This is the default for set-option (can be omitted).

-t · string

For session options: target session For window options: target window For pane options: target pane

option · string · required

The option name.

value · string

The value to set. If omitted, the option is unset.

Examples

# Set global status bar color
set-option -g status-style bg=blue

# Set option for specific session
set-option -t mysession status-position top

# Append to an option
set-option -ga status-left " [#S]"

# Set window option
set-option -w automatic-rename on

# Set pane option
set-option -p -t 0 remain-on-exit on

# Unset option (inherit from parent)
set-option -u -t mywindow mode-keys

# Set with format expansion
set-option -F message-command-style "fg=#{@my-color}"

show-options

Alias: show

show-options [-AgHpqsvw] [-t target-pane] [option]

Show options.

-A · flag

Include options inherited from a parent scope.

-g · flag

Show global session or window options.

-H · flag

Include hooks (omitted by default).

-p · flag

Show pane options.

-q · flag

Suppress errors about unknown or ambiguous options.

-s · flag

Show server options.

-v · flag

Show only the option value, not the name.

-w · flag

Show window options. This is the default.

-t · string

Target pane, window, or session.

option · string

The option to show. If omitted, all options are shown.

Examples

# Show all window options
show-options

# Show global session options
show-options -g

# Show specific option value
show-options -gv status-position

# Show server options
show-options -s

# Show pane options
show-options -p -t 0

# Show option including inherited values
show-options -A mode-keys

set-environment

Alias: setenv

set-environment [-Fgru] [-t target-session] name [value]

Set or unset an environment variable.

-F · flag

Expand formats in the value.

-g · flag

Set in the global environment. This is the default if no target session is specified.

-r · flag

Mark the variable as removed. It will be removed from the environment when the session is created.

-u · flag

Unset the variable.

-t · string

Set the variable in the session environment for the target session.

name · string · required

The environment variable name.

value · string

The value to set. Required unless -u is specified.

Examples

# Set global environment variable
set-environment MYVAR myvalue

# Set for specific session
set-environment -t mysession DISPLAY :0

# Unset variable
set-environment -u MYVAR

# Set with format expansion
set-environment -F CURRENT_WINDOW "#{window_name}"

# Mark as removed
set-environment -r OLDVAR

show-environment

Alias: showenv

show-environment [-gs] [-t target-session] [name]

Show environment variables.

-g · flag

Show the global environment. This is the default if no target session is specified.

-s · flag

Output in a format suitable for sourcing in a shell.

-t · string

Show the session environment for the target session.

name · string

The environment variable to show. If omitted, all variables are shown.

Examples

# Show all global environment variables
show-environment

# Show session environment
show-environment -t mysession

# Show specific variable
show-environment DISPLAY

# Output in shell-sourceable format
show-environment -s

Common Options

Server Options

Set with set-option -s, shown with show-options -s:

• buffer-limit: Maximum number of automatic paste buffers (default 50)
• command-alias: List of command aliases
• default-terminal: Default terminal type (default “screen”)
• escape-time: Time in milliseconds tmux waits after escape key (default 500)
• exit-empty: Exit when there are no active sessions (default on)
• exit-unattached: Exit when no clients are attached (default off)
• history-file: Path to command history file

Session Options

Set with set-option, shown with show-options:

• base-index: Start window numbering at this value (default 0)
• default-command: Default command for new windows
• default-shell: Default shell (default $SHELL or /bin/sh)
• default-size: Default size of windows (default 80x24)
• display-time: Duration of display-message in milliseconds (default 750)
• history-limit: Maximum lines per window history (default 2000)
• key-table: Default key table (default “root”)
• lock-after-time: Lock session after seconds of inactivity (default 0, disabled)
• message-style: Style for command prompt messages
• prefix: Prefix key (default C-b)
• renumber-windows: Renumber windows when one is closed (default off)
• repeat-time: Time for repeating key bindings in milliseconds (default 500)
• status: Show or hide status bar (default on)
• status-interval: Update status bar every interval seconds (default 15)
• status-position: Status bar position: top or bottom (default bottom)
• status-style: Style for status bar

Window Options

Set with set-option -w, shown with show-options -w:

• aggressive-resize: Resize window to smallest or largest client (default on)
• automatic-rename: Automatically rename windows (default on)
• automatic-rename-format: Format for automatic window names
• clock-mode-colour: Color of clock
• clock-mode-style: Clock format: 12 or 24 (default 24)
• mode-keys: Key bindings in copy mode: vi or emacs (default emacs)
• mode-style: Style for indicators and highlighting in modes
• monitor-activity: Monitor for activity in windows (default off)
• monitor-bell: Monitor for bell in windows (default on)
• monitor-silence: Monitor for silence (seconds) in windows (default 0, disabled)
• pane-base-index: Start pane numbering at this value (default 0)
• remain-on-exit: Keep window after program exits (default off)
• synchronize-panes: Send input to all panes in the window (default off)
• window-status-format: Format for window status in status bar
• window-status-current-format: Format for current window status
• window-status-style: Style for window status

Pane Options

Set with set-option -p, shown with show-options -p:

• allow-passthrough: Allow passthrough sequences (default off)
• allow-rename: Allow applications to rename windows (default on)
• alternate-screen: Use alternate screen feature (default on)
• remain-on-exit: Keep pane after program exits (default off)
• window-active-style: Style for active pane
• window-style: Style for inactive panes

Option Value Types

Boolean

Values: on, off, yes, no, 1, 0, true, false

Number

Integer values

String

Text values, may include format variables

Style

Style specifications: fg=color, bg=color, bold, dim, underscore, blink, reverse, italics, strikethrough, etc.

Array

Comma-separated list of values. Use -a to append.

Color

Color names: black, red, green, yellow, blue, magenta, cyan, white, default

Or: colour0 to colour255, #rrggbb hex values