Guide · Open source

How to use tpm: install and manage tmux plugins

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

tpm is the Tmux Plugin Manager, a small helper that installs and loads add-ons for tmux, the program that runs several terminal sessions inside one window. It is written for people who already use tmux and want plugins without fetching them by hand. This guide shows you how to install tpm, list plugins in your tmux config, and install, update and remove them.

TPMtmux-plugins/tpm · ★ 15.2k · MIT Install options & downloads

Quick start

1Check prerequisites. Confirm you have tmux 1.9 or higher, git and bash, on Linux, macOS or Cygwin.
2Clone tpm. Run git clone https://github.com/tmux-plugins/tpm ~/.tmux/plugins/tpm.
3List plugins in tmux.conf. Add set -g @plugin lines to ~/.tmux.conf and put the run line for tpm at the very bottom.
4Reload tmux. Run tmux source ~/.tmux.conf if tmux is already open.
5Install plugins. Press prefix followed by capital I to fetch the listed plugins.
6Update or remove plugins. Press prefix + U to update, or remove the line and press prefix + alt + u to uninstall.

What you need before you install tpm

tpm needs tmux version 1.9 or higher, git and bash. It only works as a tmux add-on, so it has no use outside tmux.

The project says it has been tested on Linux, OSX and Cygwin. The README does not mention native Windows support, so Windows users without Cygwin should not expect it to work.

tmux 1.9 or higher
git
bash
Linux, macOS, or Cygwin

Install tpm by cloning it into your plugins directory

Clone the tpm repository into ~/.tmux/plugins/tpm. This is the only install step the README gives.

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

Add tpm and your plugins to tmux.conf

Open ~/.tmux.conf and put the following at the bottom. The README notes that $XDG_CONFIG_HOME/tmux/tmux.conf also works. Each plugin is listed with set -g @plugin. The last line initializes tpm and should stay at the very bottom of the file.

Plugins can come from GitHub as username/plugin_name, from a specific branch with #branch, or from other git hosts using a git@ address.

Add one set -g @plugin line for each plugin you want.
Use github_username/plugin_name for GitHub plugins.
Add #branch after the name to use a specific branch.
Keep the run line at the very bottom of tmux.conf.

# List of plugins
set -g @plugin 'tmux-plugins/tpm'
set -g @plugin 'tmux-plugins/tmux-sensible'

# Initialize TMUX plugin manager (keep this line at the very bottom of tmux.conf)
run '~/.tmux/plugins/tpm/tpm'

Reload tmux so tpm loads

If tmux is already running, reload the config from a terminal so tpm is sourced. The README says that is all it takes to finish setup.

tmux source ~/.tmux.conf

Install, update and remove plugins

To install a plugin, add its set -g @plugin line to your config, then press prefix followed by capital I (as in Install). The plugin is cloned into ~/.tmux/plugins/ and sourced.

To update plugins, press prefix followed by capital U. To remove a plugin, delete or comment out its line, then press prefix, alt and lowercase u. You can also delete its folder in ~/.tmux/plugins/ by hand.

prefix + I: install new plugins and refresh the tmux environment
prefix + U: update plugins
prefix + alt + u: remove plugins no longer on the list

Where to find help and advanced options

The README links to a troubleshooting page for when tpm is not working. Advanced topics include creating your own plugin, managing plugins from the command line, changing the plugins install directory, and automatic tpm installation on a new machine. The README says most regular users will not need these.

The README also lists tpack as a drop-in replacement for tpm that adds a TUI, auto-updates and a plugin browser. Pick it if you want a graphical browser.

Help page: docs/tpm_not_working.md
Command-line plugin management: docs/managing_plugins_via_cmd_line.md
Changing install directory: docs/changing_plugins_install_dir.md

What people use it for

Adding the tmux-sensible plugin to a shared set of tmux settings across machines
Keeping a written list of tmux plugins in tmux.conf so the setup is easy to review
Updating installed tmux plugins with a single key combination
Installing a plugin from a specific git branch for testing

Frequently asked questions

Is tpm free to use?

tpm is released under the MIT licence, as stated in the README and repository. The licence file is linked from the project page.

What do I need to run tpm?

The README lists tmux 1.9 or higher, git and bash. It says the project has been tested on Linux, OSX and Cygwin.

Does tpm work on Windows?

The README only lists Linux, OSX and Cygwin as tested. It does not mention native Windows support, so Windows users without Cygwin should look at other options.

How do I install a tmux plugin with tpm?

Add a set -g @plugin line for the plugin to ~/.tmux.conf, then press prefix followed by capital I. The plugin is cloned into ~/.tmux/plugins/ and sourced.

Why is tpm not working?

The README links to a troubleshooting page at docs/tpm_not_working.md. Check that the run line is at the very bottom of tmux.conf and that tmux has been reloaded.

Is there an alternative to tpm?

The README names tpack as a drop-in replacement for tpm with a TUI, auto-updates and a plugin browser. Choose it if you want a graphical interface.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

tpm is a good choice if you already use tmux and want plugins managed from a list in your config file with a few key presses. Skip it if you do not use tmux, use native Windows without Cygwin, or want a graphical plugin browser, in which case the README points to tpack.

Install options & downloads