Ahiru-TPM 🦆
A drop-in replacement for the famous Tmux Plugin Manager, written in Rust.
Ahiru-TPM installs, loads and manages tmux plugins.
Plugins are loaded in parallel for maximum tmux startup speed (see Benchmark).
A curated list of plugins can be found here. (Thanks to Bruno Sutic for maintaining the list)
Installation
To let Ahiru-TPM manage your tmux plugins, add the following at the end of
your tmux config (either in ~/.tmux.conf or
${XDG_CONFIG_HOME}/tmux/tmux.conf):
[!Tip]
If you want tmux to start up even faster, change the last line to
tmux run -b 'ahiru-tpm init'The
-bruns the init command in the background. This means thattmuxwill not wait untilahiru-tpmhas initialized but it might cause a bit of flickering until all plugins (e.g. themes) are loaded.
# List of plugins (install by running `ahiru-tpm install`)
set -g @plugin 'tmux-plugins/tmux-sensible'
set -g @plugin 'x3rAx/tmux-yank#yank-action-mouse'
set -g @plugin 'catppuccin/tmux'
# Other examples:
# set -g @plugin 'github_username/plugin_name'
# set -g @plugin 'github_username/plugin_name#branch'
# Initialize TMUX plugin manager (keep this line at the very bottom of tmux.conf)
run 'ahiru-tpm init'
Then proceed with one of the following install methods to get Ahiru-TPM installed on your system:
Nix Flakes
(Thanks to Yazi for the flake template below.)
Below is a basic flake.nix showcasing how to add Ahiru-TPM to system packages
and through home-manager:
{
inputs = {
nixpkgs.url = "github:NixOS/nixpkgs/nixos-25.05";
home-manager = {
url = "github:nix-community/home-manager/release-25.05";
inputs.nixpkgs.follows = "nixpkgs";
};
ahiru-tpm = {
url = "gitlab:x3ro/ahiru-tpm";
inputs.nixpkgs.follows = "nixpkgs";
};
};
outputs = {
nixpkgs,
home-manager,
ahiru-tpm,
...
}: {
# To install ahiru-tpm system-wide:
nixosConfigurations = {
"nixos" = nixpkgs.lib.nixosSystem {
modules = [
({pkgs, ...}: {
environment.systemPackages = [ahiru-tpm.packages.${pkgs.system}.default];
})
];
};
};
# To install it for a specific user using home-manager:
homeConfigurations = {
"alice@nixos" = home-manager.lib.homeManagerConfiguration {
pkgs = nixpkgs.legacyPackages.x86_64-linux;
modules = [
({pkgs, ...}: {
home.packages = [ahiru-tpm.packages.${pkgs.system}.default];
})
];
};
};
};
}
In essence, add gitlab:x3ro/ahiru-tpm to your inputs:
{
inputs = {
ahiru-tpm = {
url = "gitlab:x3ro/ahiru-tpm";
inputs.nixpkgs.follows = "nixpkgs";
};
};
// ...
}
Then add the following to your packages list:
ahiru-tpm.packages.${pkgs.system}.default
Build from source
Setup the latest stable Rust toolchain via rustup:
|
Clone the repository:
Then build ahiru-tpm:
Or install it for the current user:
Usage
Installing Plugins
Plugins can be installed by adding them to to the tmux config and running
No need to reload tmux config first.
To add a plugin, add the following line to your tmux config:
set -g @plugin '<plugin-spec>'
Where <plugin-spec> is described below:
Plugin Spec
Currently plugins can only be installed from GitHub repositories. The
following format is used for the <plugin-spec>:
github_username/plugin_name
github_username/plugin_name#branch
Updating Plugins
To update plugins run:
Uninstalling Plugins
To uninstall plugins, first remove them from your tmux config. Then, to clean up downloaded plugins, run:
Settings
Disable Parallel Mode
Sometimes you might want to disable parallel mode, for example to debug a problem with a plugin or if parallel loading leads to problems for whatever reason.
This can be done by setting the following in the tmux config:
set -g @tpm-parallel 'false'
Key Bindings
Although the default keybindings from the original TPM work here as well, it is discouraged and we recommend to use these more mnemonic key bindings:
| Key bindings | Description |
|---|---|
prefix + alt + I |
Install and reload plugins |
prefix + alt + U |
Update and reload plugins |
prefix + alt + C |
Clean plugins |
To change the key bindings add the following to your tmux config:
set -g @tpm-bind-install 'M-I'
set -g @tpm-bind-update 'M-U'
set -g @tpm-bind-clean 'M-C'
[!Note] As soon as one of the keymaps is changed, the respective "tpm-legacy" binding will be disabled and only the one defined by
@tpm-bind-*will be used.
Benchmark
In this section we compare the perforemance of the original TPM written in bash with the one of Ahiru-TPM which uses parallel processing and is written in rust.
Of course, the loading speed is heavily dependent on the plugins you have, other processes running on the system and the hardware you are running on. Therefore the times in the benchmarks are not hard facts but they instead show a trend.
I closed most of my user apps during benchmarks so that the benchmark runs without any interruptions and the CPU is not temporarily overloaded by other programs.
As hardware didn't change between benchmark runs, it's less important but
here's my inxi output for completeness:
❯ inxi
CPU: 14-core (6-mt/8-st) 13th Gen Intel Core i5-13600KF (-MST AMCP-)
speed/min/max: 1100/800/5100:3900 MHz Kernel: 6.12.31 x86_64 Up: 6d 6h 35m
Mem: 7.23/31.17 GiB (23.2%) Storage: 5.97 TiB (59.9% used) Procs: 547
Shell: nu inxi: 3.3.38
To make it a bit more reproducible, here's the list of plugins the benchmarks were run with:
set -g @plugin 'tmux-plugins/tpm'
set -g @plugin 'tmux-plugins/tmux-sensible'
set -g @plugin 'christoomey/vim-tmux-navigator'
set -g @plugin 'catppuccin/tmux'
set -g @plugin 'noscript/tmux-mighty-scroll'
2x Faster Plugins Installation
Note: The screenshot shows Ahiru-TPM as tpm-rs, which was the prototype name.
5x Faster Plugins Loading
Note: The screenshot shows Ahiru-TPM as tpm-rs, which was the prototype name.