Configuration¶

This page walks through first-time setup: declaring plugins and loading tpack.

1. Open your tmux config¶

Your tmux configuration file is typically at one of these paths:

~/.tmux.conf
$XDG_CONFIG_HOME/tmux/tmux.conf

When a tmux server is running, tpack automatically discovers every active configuration root from tmux's #{config_files} format. This includes custom files loaded by one or more tmux -f /path/to/config arguments. Without a running server, tpack falls back to the standard configuration paths.

For an unusual or detached setup, set @tpack-config in tmux to make one file the authoritative configuration root and writable target. The value must name an absolute, existing regular file:

set -g @tpack-config '/absolute/path/to/tmux.conf'

2. Declare plugins and initialize tpack¶

The configuration depends on how you installed tpack.

Standalone binaryGit clone (TPM-compatible)

If you installed tpack via Homebrew, AUR, DEB/RPM, or built from source (i.e. the tpack binary is on your $PATH):

# 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'

If you cloned tpack into ~/.tmux/plugins/tpm:

# 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'

tpack automatically updates itself when using the auto-downloaded binary (the default for git clone installs) — no self-referencing plugin line is needed. If you built from source with make build, use tpack self-update or rebuild manually.

3. Reload tmux¶

tmux source ~/.tmux.conf

4. Install plugins¶

Press ++prefix+shift+i++ to fetch and install all declared plugins.

Tip

After installation, tpack will display a message listing the plugins it installed.

Plugin declaration syntax¶

Format	Example	Description
`user/repo`	`tmux-plugins/tmux-sensible`	GitHub shorthand
`user/repo#ref`	`tmux-plugins/tmux-sensible#main`	Branch, tag, or commit SHA
`https://github.com/user/repo.git`	`https://github.com/user/tmux-sensible.git`	Full HTTPS URL
`git@github.com:user/plugin`	`git@github.com:tmux-plugins/tmux-sensible`	Full git SSH URL (GitHub)
`git@bitbucket.com:user/plugin`	`git@bitbucket.com:user/tmux-plugin`	Non-GitHub git hosts
`user/plugin alias=name`	`tmux-plugins/tmux-sensible alias=sensible`	Custom directory name

Branches track upstream and fast-forward on update. Tags and commit SHAs are pinned (detached HEAD; no automatic updates).

Plugin identity and CLI names are repository-qualified (for example, tmux-plugins/tmux-sensible). By default, tpack derives an ASCII canonical directory of at most 64 bytes from that identity, allowing repositories with the same basename to coexist. alias= overrides only this directory name; it does not change repository identity or the repository-qualified name used by commands. Aliases also preserve compatibility when a plugin or script requires a fixed directory:

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

For a list of compatible plugins, see the tmux-plugins list.

Next step¶

Already a TPM user? See Migrating from TPM. Otherwise, head to Usage to learn about key bindings, the TUI, and the CLI.