Plugins: TPM and the Short List Worth Installing | tmux Tutorial

Discipline First

tmux works well out of the box. A good plugin list is small: three to five, chosen deliberately. Before adding a plugin, ask what real problem it solves. If the answer is vague, skip it.

You'll see people recommend plugin lists of twenty items. Those lists are aspirational. Start with none, add as you feel the need, review every few months.

TPM: tmux plugin manager

tpm is the usual plugin manager for tmux. It clones plugins into ~/.tmux/plugins/ and sources them automatically.

Install TPM

git clone https://github.com/tmux-plugins/tpm ~/.tmux/plugins/tpm

Add to ~/.tmux.conf (at the bottom):

set -g @plugin 'tmux-plugins/tpm'
set -g @plugin 'tmux-plugins/tmux-sensible'

# Keep this line at the very bottom of tmux.conf
run '~/.tmux/plugins/tpm/tpm'

Managing plugins

Inside a tmux session, after editing .tmux.conf:

<prefix> I                   install new plugins listed in the config
<prefix> U                   update plugins
<prefix> alt-u               uninstall plugins no longer in the config

Those bindings are part of TPM itself. The capital letter after prefix is the idiom.

The Short List Worth Installing

tmux-sensible

set -g @plugin 'tmux-plugins/tmux-sensible'

Sets a batch of sensible defaults most configs want anyway: faster escape time, modern 256-colour support, reasonable history limit, and a handful of bindings. Read the source once; it's short.

If you already set those options in your config, sensible is redundant. If you're starting fresh, include it and save yourself boilerplate.

tmux-yank

set -g @plugin 'tmux-plugins/tmux-yank'

Bridges tmux's copy mode to the system clipboard. On macOS, uses pbcopy. On Linux, uses xclip, xsel, or wl-copy depending on what's installed.

In copy mode, y yanks the selection and puts it in the system clipboard. Cross-platform, reliable. If set-clipboard (chapter 5) works for your terminal, you don't strictly need it, but tmux-yank is a solid belt-and-braces install.

tmux-resurrect

set -g @plugin 'tmux-plugins/tmux-resurrect'

Saves and restores tmux sessions across reboots. <prefix> Ctrl-s saves, <prefix> Ctrl-r restores. It saves window layouts, working directories, and (optionally) the programs that were running.

For shell commands and editors, it can re-launch them on restore, though restoration of interactive state (a debugger mid-session, for instance) is not realistic.

If you reboot more than once a week, tmux-resurrect is worth the two-line install.

tmux-continuum

set -g @plugin 'tmux-plugins/tmux-continuum'
set -g @continuum-restore 'on'

Companion to tmux-resurrect. Automatically saves sessions every 15 minutes and restores on tmux start. Combine the two and your environment survives reboots without you thinking about it.

tmux-pain-control

set -g @plugin 'tmux-plugins/tmux-pain-control'

A collection of bindings that fix tmux's default pane ergonomics: | and - for splits, hjkl for navigation, HJKL for resize, and more. If your .tmux.conf already has these, skip this plugin. If not, it's a useful starter pack.

vim-tmux-navigator

set -g @plugin 'christoomey/vim-tmux-navigator'

Matches up with the vim plugin of the same name. With both installed, Ctrl-h/j/k/l navigates between vim splits and tmux panes transparently. If you use vim inside tmux (most people do), this is life-changing. One of the few plugins I'd call near-essential.

Note: install the vim plugin on the vim side too (Plug 'christoomey/vim-tmux-navigator').

Optional but often recommended

extrakto: fuzzy-select any text on the screen with <prefix> Tab. Great for grabbing URLs, file paths, or UUIDs from output
tmux-fzf: fuzzy picker for sessions, windows, panes, bindings. Install if you already live in fzf
tmux-online-status: a connectivity indicator on the status line. Useful if you bounce between networks
tmux-battery: battery indicator on laptops

Install one at a time. Use it for two weeks. If you can't remember using it, remove it.

Where Plugins Go Wrong

Too many

Every plugin you add costs you startup time (a moment) and complexity (forever). A config with 15 plugins is a config whose owner doesn't remember what half of them do.

Run ls ~/.tmux/plugins/ every few months. Anything unfamiliar gets the boot.

Status-line plugins

Plugins that render fancy status lines (tmux-powerline, various theme collections) are beautiful and slow. They run shell commands on every status refresh. If your status feels laggy, check here first.

A plain, hand-written status line (chapter 8) loads instantly and looks fine.

Key-binding conflicts

A plugin may claim a binding you already use. Check its README before installing. After installing, <prefix> ? lists every binding and flags duplicates.

Installing Without TPM

TPM is convenient, not essential. You can source plugin files directly:

run-shell ~/.tmux/plugins/tmux-yank/yank.tmux

Check the plugin's README; most say which file to source. For three or four plugins this manual approach works fine and keeps the dependency list short.

Discovering Plugins

tmux-plugins organization
awesome-tmux
Search GitHub for tmux plugin

Read the README of anything you install. Check the last-commit date. Something that hasn't been touched in four years might work fine, or might break on the next tmux release.

A Reasonable Plugin Section

Taking the above together:

# plugins
set -g @plugin 'tmux-plugins/tpm'
set -g @plugin 'tmux-plugins/tmux-sensible'
set -g @plugin 'tmux-plugins/tmux-yank'
set -g @plugin 'tmux-plugins/tmux-resurrect'
set -g @plugin 'tmux-plugins/tmux-continuum'
set -g @plugin 'christoomey/vim-tmux-navigator'

set -g @continuum-restore 'on'

run '~/.tmux/plugins/tpm/tpm'

Six lines (plus TPM itself). That's a full setup most tmux users would be happy with.

Common Pitfalls

"<prefix> I does nothing." TPM isn't sourced. Check the last line of your config is run '~/.tmux/plugins/tpm/tpm', with the right path, and that TPM itself is cloned to ~/.tmux/plugins/tpm.

"Plugin installed but its features don't work." Reload the config: <prefix> :source-file ~/.tmux.conf. Or kill the server (tmux kill-server) and start a new session.

"Updates broke a plugin." <prefix> U updates all of them. Roll back by cd ~/.tmux/plugins/<name> && git checkout <old-sha>.

"tmux-resurrect didn't restore my programs." By default it restores the command line, not what was running. Opt in to process restoration:

set -g @resurrect-capture-pane-contents 'on'
set -g @resurrect-processes 'vim nvim less tail'

"vim-tmux-navigator only works inside vim." You need both halves. Install the plugin in tmux (with TPM) and in vim (with your vim plugin manager).

Next Steps

Continue to 11-workflows.md for the patterns that make tmux part of a daily routine.