Where apps hide your files

Finding and reloading tmux.conf

Updated 2026-10-28 · 6 min read

tmux looks for ~/.tmux.conf, then ~/.config/tmux/tmux.conf, and a system file under Homebrew. It reads them only when the server starts, so a reload command matters as much as the path.

The location

tmux has no config file until you make one. When it starts a server, it looks for a user file in one of these places, per its own manual page:

~/.tmux.conf
~/.config/tmux/tmux.conf

The manual words it as ~/.tmux.conf or $XDG_CONFIG_HOME/tmux/tmux.conf, and lists ~/.config/tmux/tmux.conf as another default. Use one of them, not both: tmux's source loads every one of these files that exists, in that order, so with two files, any setting in both takes its value from the later one. ~/.tmux.conf is the classic spot and what most guides assume. The second suits you if you keep your configuration under ~/.config in a dotfiles repository.

Before either, tmux loads a system-wide file if one exists. On the Mac used for this guide, tmux came from Homebrew on Apple silicon, so its manual names:

/opt/homebrew/etc/tmux.conf

An Intel Homebrew install uses /usr/local/etc/tmux.conf instead (Homebrew's tmux formula sets the system folder to its own etc). A stock Mac has no tmux at all, so if which tmux finds nothing, install it first (for example with brew install tmux).

Check whether you have one

These only list names and print the version, so they change nothing:

tmux -V
ls -la ~/.tmux.conf ~/.config/tmux/tmux.conf /opt/homebrew/etc/tmux.conf

"No such file" for all three is normal on a fresh install: tmux runs on defaults. To create one:

touch ~/.tmux.conf
open -t ~/.tmux.conf

touch does not change an existing file, and open -t opens it in your default text editor. The dot at the start hides the file from Finder; press ⇧⌘. to show hidden items, or use Go > Go to Folder (⇧⌘G).

Reload it without quitting

tmux's manual is explicit: it loads configuration files once, when the server process starts, and the source-file command loads a file later. So editing the file changes nothing in a running session until you reload. From a shell inside or outside tmux:

tmux source-file ~/.tmux.conf

Many people bind this to a key so reloading takes one press. The manual's own example is a binding that runs source-file and then shows a message. A line such as this in the file does it:

bind-key R source-file ~/.tmux.conf \; display-message "source-file done"

Then press your prefix (⌃B by default) followed by ⇧R. If your file is the XDG one, change the path to match.

If the file has errors, tmux's manual says it shows them (at start-up, in the first session created) and carries on with the rest of the file, so one bad line does not stop the others.

A reload runs the file's commands again on top of the current settings. It does not reset anything, so deleting a line does not undo what that line set until the server restarts. To start clean, close every tmux session, which lets the server exit, and start tmux again. Or use tmux kill-server, but only after saving whatever is running in your sessions, since it ends them all.

Order of steps for an edit

1. Copy the file: cp ~/.tmux.conf ~/.tmux.conf.bak.
2. Edit the file in any text editor.
3. Run tmux source-file ~/.tmux.conf and read any errors.
4. To undo, run cp ~/.tmux.conf.bak ~/.tmux.conf and reload.

Using a different file

The -f flag names an alternative configuration file. In tmux's source it replaces the whole default list, the system file included. It only matters when a new server starts: if one is already running, tmux attaches to it and the file is not read. To test a new config safely, give it a separate server with -L:

tmux -L test -f ~/dotfiles/tmux.conf

That session runs beside your normal ones without touching them.

Plugins

The usual plugin manager, TPM, installs under ~/.tmux/plugins/. Its README tells you to clone it with git clone https://github.com/tmux-plugins/tpm ~/.tmux/plugins/tpm, then add plugin lines and a final run '~/.tmux/plugins/tpm/tpm' line at the bottom of ~/.tmux.conf. Inside tmux, the prefix plus ⇧I installs listed plugins, the prefix plus ⇧U updates them, and the prefix plus ⌥U removes ones you took off the list. The ⌥ key only reaches tmux if your terminal sends Option as Meta; in Terminal that is the Use Option as Meta key setting. The README also says the XDG path works for the config, and TPM's own script then switches its plugin folder to ~/.config/tmux/plugins/.

Plugins are folders of scripts that run inside your sessions, so read what you install. To remove one, take its line out of the config first, then press the uninstall keys or move its folder out of the plugins folder yourself, which the README allows. If you delete the folder but leave the line, ⇧I simply installs it again.

The socket folder is not your config

tmux keeps a socket for its server in a folder named tmux- followed by your user ID, under /tmp, or under TMUX_TMPDIR if you set that variable. The manual says tmux creates it and that it must not be world readable, writable or executable. You do not need to touch it, and removing it while sessions run cuts you off from them. The manual notes that sending the server SIGUSR1 recreates an accidentally removed socket.

Moving to a new Mac

Copy ~/.tmux.conf (or ~/.config/tmux/) and, if you use TPM, only the plugin lines: the plugins themselves are cloned again. Install tmux on the new Mac, put the file in place, clone TPM, then press the prefix plus ⇧I. Running sessions are not carried over; a tmux session lives in a server process on one machine.

If your config is in a Git repository, copying it is just a clone. Time Machine also covers the dotfiles in your home folder.

One related surprise: tmux's manual says new windows start a login shell by default. On a Mac that makes zsh run /etc/zprofile again, which re-sorts PATH and can put system folders ahead of your own. PATH lines kept in ~/.zprofile run after it and stay in front.

Why a normal search misses it

.tmux.conf and .config begin with a dot, so Finder and Spotlight searches leave hidden files out, and the plugin folder ~/.tmux is a hidden folder too. The Homebrew copy sits in /opt/homebrew/etc, a system-side folder those searches leave out as well.

Finding the file next time

Typing tmux.conf into Everywhere lists every config candidate at once: the one in your home folder, one under ~/.config/tmux, the Homebrew one in /opt/homebrew/etc and any .bak copies, so you can see which exist. Typing tpm finds the plugin manager's folder. Hidden dot-folders and /opt/homebrew are part of the normal scan, and it matches file names only, not the lines inside the config. Press ⌘T on a result to open a Terminal in that folder.

Common questions

Where is tmux.conf on a Mac?

At ~/.tmux.conf or ~/.config/tmux/tmux.conf; neither exists until you create it. Homebrew's tmux also reads a system file at /opt/homebrew/etc/tmux.conf on Apple silicon.

How do I reload tmux.conf?

Run tmux source-file ~/.tmux.conf. tmux only reads its config when the server starts, so editing the file alone changes nothing in a running session.

Does tmux use ~/.config/tmux/tmux.conf?

Yes. tmux's manual lists $XDG_CONFIG_HOME/tmux/tmux.conf and ~/.config/tmux/tmux.conf as default configuration files, next to ~/.tmux.conf.

Where do tmux plugins install?

TPM, the common plugin manager, clones itself to ~/.tmux/plugins/tpm and installs plugins in ~/.tmux/plugins/. If your config is at ~/.config/tmux/tmux.conf, TPM uses ~/.config/tmux/plugins/ instead.