How to use tmux’s
show commands to set and query tmux config settings (“options”).
set foo barsets an option for the current window or session.
set -g foo barsets an option globally (for all windows and sessions that don’t have a local setting for that option). You always want
set -gin your
~/.tmux.conffile because there’s no current window or session at the time when the file is read.
show -A fooshows 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 foounsets an option, reverting to the default.
set -gu foounsets a global option.
set-option command (alias
set) sets options, and
show) shows what value an option is currently set to.
man tmux for a list of all the available options.
There are three ways to enter a
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
show ...into tmux’s command prompt
By adding a
set ...line to your
~/.tmux.conffile to set an option at startup
There are four types of option:
Session options are set and shown using plain
showcommands, 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
-gto change the global default. When setting a session option in your
~/.tmux.conffile you always want
-gbecause 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
showand apply to the tmux server. The
-scan be omitted and tmux will infer it from the option name.
Window options are set and shown using the
showand apply to the current window. The
-wcan 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
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
-gto change the global default. When setting a window option in your
~/.tmux.confyou always want
-gbecause 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
showand apply to the current pane. The
-pis 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
-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.
-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
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
set @foo bar will always succeed. Some plugins use user options. You do need the
-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.