tpack - A Tmux Plugin Manager

Full Documentation - Mostly AI-generated

A modern tmux plugin manager written in Go. It accepts existing TPM configuration syntax and key bindings, while adding repository-aware plugin management.

Important

tpack stores plugins in repository-specific directories such as tmux-87a1216f1f68 (always ASCII and at most 64 bytes), so repositories with the same basename can coexist. On the first operational command, tpack identifies a legacy basename checkout by its Git origin and renames an exact match once. Automatic migration never guesses, deletes, or moves a mismatched or unreadable checkout, and concurrent tpack runs cannot overwrite a canonical directory. A later explicit tpack clean can remove an unmatched legacy directory under normal orphan-cleanup semantics. Explicit alias= values keep their configured directory instead.

This means switching back to TPM is not seamless. Running tpack and TPM against the same plugin root is unsupported, and scripts or configuration with hard-coded plugin paths may need updating.

Works on Linux, macOS, and FreeBSD.

Installation

Requirements: tmux version 1.9 (or higher), git, bash.

There are two ways to set up tpack, each with different installation methods and configuration. Pick whichever fits your workflow.

Option A: Standalone binary

Install tpack as a binary on your $PATH. This is the recommended approach for new setups.

Homebrew (macOS / Linux)

Custom tap repository (updated immediately after new release):

brew install tmuxpack/tpack/tpack

or official formula (updated less frequently):

brew install tpack

AUR (Arch Linux)

yay -S tpack-bin

DEB / RPM (Debian, Ubuntu, Fedora, etc.)

Download the latest .deb or .rpm package from the releases page and install it with your package manager:

# Debian / Ubuntu
sudo dpkg -i tpack_*.deb

# Fedora / RHEL
sudo rpm -i tpack_*.rpm

Go install

Requires Go 1.26 or later:

go install github.com/tmuxpack/tpack/cmd/tpack@latest

Make sure $GOPATH/bin (or $HOME/go/bin) is on your $PATH.

Build from source

git clone https://github.com/tmuxpack/tpack
cd tpack
make build
# Binary is at dist/tpack — move it somewhere on your $PATH
sudo cp dist/tpack /usr/local/bin/

Then add to ~/.tmux.conf (or $XDG_CONFIG_HOME/tmux/tmux.conf):

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

# Initialize tpack (keep this line at the very bottom of tmux.conf)
run 'tpack init'

Option B: Git clone (TPM-compatible setup)

Clone tpack into the TPM directory. Existing TPM declaration syntax remains valid, so no tmux.conf syntax changes are needed when switching from TPM. The plugin directory migration described above still applies.

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

Then add to ~/.tmux.conf (or $XDG_CONFIG_HOME/tmux/tmux.conf):

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

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

Load and install plugins

Reload tmux and press prefix + I to install plugins:

tmux source ~/.tmux.conf

See the Getting Started guide for full setup instructions.

Features

• TPM-compatible configuration — existing declarations and key bindings work
• Interactive TUI — browse, install, update, remove, and uninstall plugins visually (prefix + T)
• CLI — tpack install, tpack update, tpack clean, and more
• Automatic updates — optional background update checking for plugins and tpack itself
• Customizable — key bindings, colors, plugin directory, and update behavior
• Plugins browser — search, browse and install plugins from the TUI, the list being maintained on the plugins-registry

Not interested in a whole category of plugins (e.g. ai)? Hide it from the browser with @tpack-hidden-categories:

set -g @tpack-hidden-categories 'ai'

See the full documentation for details on configuration, usage, and the CLI reference.

Migrating from TPM

tpack accepts TPM configuration syntax. Two ways to switch:

• Git remote — if you git cloned TPM, just point the remote at tpack and pull. No tmux.conf changes needed:

  cd ~/.tmux/plugins/tpm
  git remote set-url origin https://github.com/tmuxpack/tpack
  git pull

• Package manager — install tpack via Homebrew, AUR, DEB/RPM, or go install (see installation guide), then replace the run line in your tmux.conf with run 'tpack init'.

See the full migration guide for details.

Acknowledgments

tpack is built on the foundations of TPM, the original Tmux Plugin Manager created by Bruno Sutic. Thanks to Bruno and the TPM contributors for establishing the plugin ecosystem that tpack is designed to be compatible with.

License

MIT