Customize your tmux configuration with interactive controls. Real-time syntax highlighting, custom prefix binding, mouse mode, Vi key navigation, status bar styling, and 1-click download.
Deploy your generated configuration file in 3 simple steps.
Move the downloaded file to your home directory (or to ~/.config/tmux/tmux.conf if you keep dotfiles in XDG folders):
mv ~/Downloads/.tmux.conf ~/.tmux.conf
If you enabled Dracula, Nord, or Gruvbox themes, clone the Tmux Plugin Manager:
git clone https://github.com/tmux-plugins/tpm ~/.tmux/plugins/tpm
Apply changes without ending your sessions. If you chose a theme, then press Prefix + I (capital i) so TPM downloads it:
tmux source-file ~/.tmux.conf
Understanding the trade-offs between default, screen-legacy, and modern ergonomic prefixes.
The out-of-the-box default everywhere tmux is installed, so it works on any server without a config. It leaves Ctrl+a (jump to line start in Bash/readline) alone, but it does shadow readline's rarely used "back one character" (Ctrl+b) and Vim's page-up. Reaching Ctrl and b together is a stretch for the left hand on QWERTY keyboards.
Extremely popular because A sits directly on the home row under the left pinky. When Caps Lock is remapped to Control at the OS level, triggering tmux commands becomes instantaneous. To still jump to the beginning of the line in Bash, add bind C-a send-prefix.
The modern favorite among software engineers. Left pinky holds Ctrl (or remapped Caps Lock) while the right thumb taps Space. This splits the work across both hands, which many people find more comfortable for long sessions. Note that some terminals and IMEs (input method switchers on macOS and Linux) already claim Ctrl+Space, so test it before committing.
How tmux discovers, evaluates, and applies configuration directives across operating systems.
When the tmux server starts, it searches for configuration files in a strict lookup order. Understanding this hierarchy ensures your dotfiles remain portable across macOS, Ubuntu, Arch Linux, and Windows WSL:
| Priority | Configuration Path | Description & Best Practice |
|---|---|---|
| Always | /etc/tmux.conf |
System-wide file, loaded first if it exists (on Homebrew: $(brew --prefix)/etc/tmux.conf). |
| 1st found | ~/.tmux.conf |
Traditional user config. If this exists, tmux stops looking. |
| 2nd | $XDG_CONFIG_HOME/tmux/tmux.conf |
XDG location, used only when ~/.tmux.conf does not exist. |
| 3rd | ~/.config/tmux/tmux.conf |
XDG fallback (tmux 3.1+) when $XDG_CONFIG_HOME is unset. Ideal for dotfile repositories. |
| Override | tmux -f /path/to/custom.conf |
Replaces all of the above, including /etc/tmux.conf. Handy for testing a config in isolation. |
Note: Only one user file is loaded. If both ~/.tmux.conf and ~/.config/tmux/tmux.conf exist, tmux uses ~/.tmux.conf and ignores the XDG file unless you source-file it yourself.
Iterate on keybindings and status bar designs without killing background jobs.
Instead of typing tmux source-file ~/.tmux.conf into your shell, map a dedicated hotkey directly in your config:
bind r source-file ~/.tmux.conf \; display-message "Config reloaded!"
Pressing Prefix + r immediately re-evaluates the config file and flashes a confirmation message in the status bar.
Sourcing your config applies new settings to existing windows and panes while your programs keep running. Note that it only adds: deleting a line does not undo it. To get back to a clean state, restart the server with tmux kill-server.
bind-key already replaces any existing binding for that key. Use unbind-key to free a key you no longer want, such as the old prefix (unbind C-b), and Prefix + / to check what a key currently does.
Diagnose and resolve configuration parsing failures quickly.
Usually caused by version mismatches between tmux 2.x and 3.x. For example, the old mode-mouse, mouse-select-pane, mouse-resize-pane and mouse-select-window options were replaced by a single set -g mouse on in tmux 2.1. Run tmux -V to check your version.
Always ensure run '~/.tmux/plugins/tpm/tpm' is placed at the very bottom of your .tmux.conf. Plugin settings must be declared above the TPM initialization line.
Check a config without applying it. This reports unknown commands and syntax errors with line numbers (misspelled option names only show up when the file is really loaded):
tmux source-file -nv ~/.tmux.conf
For deeper problems, start a fresh server with logging (tmux -vv new) and read the tmux-server-*.log file written to the current directory.
Answers to common questions about configuring, customizing, and maintaining tmux dotfiles.
While ~/.tmux.conf remains universally supported across all versions, modern tmux (v3.1+) fully supports the XDG Base Directory specification at ~/.config/tmux/tmux.conf. Storing your configuration inside ~/.config/tmux/ allows you to manage tmux alongside Neovim, Alacritty, and Git in a clean, version-controlled dotfiles repository.
With set -g mouse on enabled, scrolling your mouse wheel inside a pane automatically enters copy mode and scrolls up through your terminal history. To prevent the viewport from immediately jumping back to the bottom when selecting text with the mouse, add unbind -T copy-mode-vi MouseDragEnd1Pane to your configuration.
By default, tmux may fall back to 8-color or 16-color mode if your terminal emulator does not declare 24-bit True Color support. To guarantee accurate color rendering, add set -g default-terminal "tmux-256color" and tell tmux your terminal supports 24-bit colour with set -as terminal-features ",xterm-256color:RGB" (tmux 3.2+).
When running tmux inside a remote SSH session from a local tmux client, both servers listen for the same prefix key. You can pass commands to the inner session by pressing the prefix key twice (e.g., Ctrl+b Ctrl+b c) or by binding a toggle key to temporarily disable local keybindings.
Explore our complete documentation on options, status bar format specifiers, hooks, and advanced keybindings.