Setting Options in tmux

How to use tmux’s set and show commands to set and query tmux config settings (“options”).

TLDR

set foo bar sets an option for the current window or session.
set -g foo bar sets an option globally (for all windows and sessions that don’t have a local setting for that option). You always want set -g in your ~/.tmux.conf file because there’s no current window or session at the time when the file is read.
show -A foo shows the current window or session’s current setting for an option. The setting will be flagged with * if it’s being inherited from the global setting.
set -u foo unsets an option, reverting to the default. set -gu foo unsets a global option.

The set-option command (alias set) sets options, and show-option (alias show) shows what value an option is currently set to. See man tmux for a list of all the available options. There are three ways to enter a set or show command:

By running tmux set ... or tmux show ... in a shell inside tmux. For example:

$ tmux set status off  # Hide the status bar.
$ tmux show status
status off

By hitting Ctrl + b : then entering set ... or show ... into tmux’s command prompt
By adding a set ... line to your ~/.tmux.conf file to set an option at startup

There are four types of option:

Session options are set and shown using plain set and show commands, and apply to the current session. For example:
```
set status off  # Turn off the status bar, for this session only.
show status
```
Each session option also has a global value that each session inherits by default. Use -g to change the global default. When setting a session option in your ~/.tmux.conf file you always want -g because there is no current session. Example:
```
set -g status 2  # Show the two-line version of the status bar, for all sessions by default.
```
Server options are set and shown using the -s option to set and show and apply to the tmux server. The -s can be omitted and tmux will infer it from the option name.
Window options are set and shown using the -w option to set and show and apply to the current window. The -w can be omitted and tmux will infer it from the option name. For example:
```
tmux set -w window-status-separator '|'  # Change this window's status separator to "|"
```
or with the -w inferred:
```
tmux set window-status-separator '|'  # Change this window's status separator to "|"
```
Each window option also has a global value that each window inherits by default. Use -g to change the global default. When setting a window option in your ~/.tmux.conf you always want -g because there is no current window. Example:
```
tmux set -g window-status-separator '|'  # Change the status separator to "|" for all windows by default.
```
Pane options are set and shown using the -p option to set and show and apply to the current pane. The -p is necessary, otherwise tmux will assume the option is a window option. Pane options inherit from window options, so any pane option can be set as a window option instead and will apply to all panes in the window (or to all panes, if set as a global window option).

show <OPTION> will normally output nothing if the option is unset and is being inherited from a parent set. show -A <OPTION> will print the inherited value, flagging it with a * if it’s inherited.

Appending to an option

-a can be used to repeatedly append to an option’s value, useful for building up styles and strings. For example this:

set status-left foo
set -a status-left bar

is equivalent to:

set status-left foobar

Unsetting an option

Use -u to unset an option and revert to the default:

set -u status
set -gu status  # Unset the global `status` option.

Setting an option only if it isn’t already set

-o sets an option but only if it’s not already set, and fails if the option is already set:

set -o status off  # Turn off the status bar, but only if `status` isn't already set for this session.

Supressing errors

-q supresses errors, such as the error that -o gives when an option is already set, or the error that happens when an option name is unknown:

set -qo status off
set -q foo bar

User options

Options whose names begin with @ are user options. These can have any name and value, so while set foo bar will fail (because there is no option foo), set @foo bar will always succeed. Some plugins use user options. You do need the -w or -s when trying to set a user option as a server or window option, tmux can’t infer them because it doesn’t know what the option is.