An active tmux session can keep running while you change its key bindings and other preferences. Reloading the tmux config applies saved settings to the existing server without restarting its shells or panes.
Tmux reads its configuration when the server starts, usually from ~/.tmux.conf, $XDG_CONFIG_HOME/tmux/tmux.conf, or ~/.config/tmux/tmux.conf. Editing the file alone does not change a live tmux environment because the running server keeps its current settings until the file is loaded again with source-file.
The reload command talks to an existing tmux server instead of starting one for you. Most option and key-binding changes take effect immediately after a successful reload, but settings such as default-shell and default-command are only used when tmux creates a new window or pane later.
Steps to reload the tmux config:
- Open the tmux configuration file that should be reloaded by the running server.
$ vi ~/.tmux.conf
Most setups use ~/.tmux.conf. If the server was started from an XDG config path, edit $XDG_CONFIG_HOME/tmux/tmux.conf or ~/.config/tmux/tmux.conf and reload that same file.
- Edit the setting or key binding that you want to apply.
set-option -g prefix C-a
A global prefix setting changes the key used for tmux shortcuts. If you want C-a, replace an existing global prefix line or add the line at the end of the file if it is absent. For other changes, edit the relevant option or binding instead.
- Save the configuration file.
Sourcing executes the file's commands; it does not reset the server to defaults. Removing a line does not undo its previously applied setting or binding. For example, deleting set-option -g prefix C-a leaves the live prefix at C-a. Replacing it with set-option -g prefix C-b explicitly restores the default prefix on the next reload.
- Reload the saved file into the intended running tmux server.
$ tmux source-file ~/.tmux.conf
A shell inside tmux normally selects its current server; a shell outside tmux uses the default socket. If the intended server uses a named socket, use tmux -L work source-file ~/.tmux.conf with its actual socket name instead of work. For a server using a full socket path, use tmux -S /tmp/tmux-work.sock source-file ~/.tmux.conf with its actual path. The option check must use the same socket selection.
A successful reload is usually silent. From the tmux command prompt (the current prefix followed by :), run source-file ~/.tmux.conf without the leading tmux shell command; this targets that client's server.
If no server is listening on the selected socket, check the socket name or path before starting or attaching to a session. A reload error is not a rollback guarantee: commands may already have changed live settings. If an error appears, inspect the affected live options with show-options before correcting the file, saving it, and reloading again.
- Query the changed setting to confirm the reload applied it.
$ tmux show-options -gv prefix C-a
For a named socket, use tmux -L work show-options -gv prefix; for a full socket path, use tmux -S /tmp/tmux-work.sock show-options -gv prefix. For another changed option, replace prefix with its name, such as status after changing the status bar or mouse after toggling mouse support. The -g flag checks the global value set by set-option -g; a session-specific override can still take precedence. Settings such as default-shell and default-command are only used when tmux creates a new window or pane, so open a new pane or window before judging those changes.