catppuccin/tmux: a pastel theme that rewrites your status line

The problem catppuccin/tmux solves for tmux users

A tmux status line is configured with format strings. Writing one that shows the session name, CPU, RAM and a clock in a consistent palette means hand-mixing hex codes across status-left, status-right and every window-status-format. That is tedious, and it breaks the moment you switch from a light terminal to a dark one.

catppuccin/tmux packages that work. It ships four flavors (Latte, Frappé, Macchiato, Mocha), each a full palette, and a set of status modules that render as ready-made format strings. The README's recommended configuration shows the shape: you set a flavor, pick a window status style, run the plugin, then append modules to status-right.

The audience is tmux users who care about their terminal's appearance and are willing to edit tmux.conf. It is not a standalone application. It is a configuration layer that assumes tmux is already part of your workflow.

How the plugin loads and where the colors come from

The repository is shell, not a compiled binary. The entry point is catppuccin.tmux at the repository root, and the installation instructions tell you to run it from tmux.conf. Alongside it sit catppuccin_options_tmux.conf, catppuccin_tmux.conf, a themes/ directory, a status/ directory, and a tmux.tera template. The .tera file suggests the theme files are generated from a template rather than edited by hand.

When tmux sources catppuccin.tmux, the script reads your @catppuccin_* options and applies them. The flavor option selects which palette is loaded; window_status_style selects the shape of the window indicators. Status modules are exposed as tmux format variables such as #{E:@catppuccin_status_application}, #{E:@catppuccin_status_cpu}, #{E:@catppuccin_status_ram} and #{E:@catppuccin_status_session}, which you place into status-right yourself.

That split matters. The plugin does not decide what your status line contains. It provides the pieces and the colors, and your tmux.conf decides the order. The README notes that the plugin uses features introduced in tmux 3.2, which is why older versions need the manual palette approach described below.

Installing catppuccin/tmux and getting a first status line

The README calls the manual method recommended, noting that TPM has some issues with name conflicts. It pins the clone to a release tag, v2.3.1 in the current instructions. Create the plugin directory, then clone into it.

mkdir -p ~/.config/tmux/plugins/catppuccin
git clone -b v2.3.1 https://github.com/catppuccin/tmux.git ~/.config/tmux/plugins/catppuccin/tmux

After the clone, the repository contents land under ~/.config/tmux/plugins/catppuccin/tmux. Next, add a run line to tmux.conf so tmux executes catppuccin.tmux at startup.

run ~/.config/tmux/plugins/catppuccin/tmux/catppuccin.tmux

Reload with tmux source ~/.tmux.conf, or restart tmux. The README also advises updating your Nerd Font, because the theme uses icons; if you do not have a patched font, the configuration reference documents how to override or remove them.

The recommended default configuration is the fastest way to see the plugin working. It sets the flavor, picks rounded window indicators, loads the plugin, then builds a right-hand status line from four modules.

set -g @catppuccin_flavor "mocha"
set -g @catppuccin_window_status_style "rounded"
run ~/.config/tmux/plugins/catppuccin/tmux/catppuccin.tmux
set -g status-right "#{E:@catppuccin_status_application}"
set -agF status-right "#{E:@catppuccin_status_cpu}"
set -agF status-right "#{E:@catppuccin_status_ram}"
set -ag status-right "#{E:@catppuccin_status_session}"

The README sets status-right-length and status-left-length to 100 in the same example, which is worth copying: the modules produce long strings, and the default length truncates them. The alternative TPM route adds set -g @plugin 'catppuccin/tmux#v2.3.1' and set -g @plugin 'tmux-plugins/tpm' to tmux.conf instead of the run line.

Window names, the status bar, and other things people search for

Most practical questions about this plugin are about the status bar and window labels. The window status style option controls the window indicators, and the README's example uses "rounded". The status modules control the right-hand side. If your status bar looks unchanged after installation, the usual cause is that the run line is missing or the file path is wrong; the README's TPM note points at a different path, ~/.tmux/plugins/tmux/catppuccin.tmux, and mixing the two paths is an easy mistake.

A returned 127 in a shell usually means a command was not found, which in this context points at the run line referencing a path that does not exist. The README does not document a diagnostic command for this, so the check is manual: confirm the cloned directory contains catppuccin.tmux.

The date and time in the status bar are not a catppuccin module. They are tmux's own format strings, and the README does not cover them. If you want a clock next to the catppuccin modules, you add it to status-right yourself.

The limitation that matters: tmux 3.2 and the status line takeover

The clearest constraint is the tmux version. The README states the plugin uses features only introduced in tmux 3.2, and earlier versions cannot run it. For those users the README offers a fallback that is not really the plugin: you copy hex values such as @ctp_bg "#24273a" and @ctp_mauve "#c6a0f6" into tmux.conf and write your own status-style and window-status-format lines. That gives you the palette, not the modules, and you maintain the format strings yourself.

The second constraint is ownership of the status line. Because the modules are appended to status-right, adopting the plugin means restructuring that option. If you already have a carefully built status-right, you are merging two systems, and the README's own note about resetting flags hints at how fiddly that gets: when switching flavors at runtime, it warns that you may need to set more @catppuccin_* variables to fully reset everything, and to test by switching themes and watching for parts that do not return to the expected color.

The third is the font. Icons are part of the default look. Without a Nerd Font the status line renders with missing glyphs, and the fix is configuration work in docs/reference/configuration.md.

Finally, upgrading from v0.3 is a breaking change. The README points at pinned issue #487 for migration, and the TPM section warns that you may have to run ~/.config/tmux/plugins/tpm/bin/clean_plugins when upgrading from an earlier version.

How it compares to a hand-written tmux.conf or a plain colorscheme

The obvious alternative is writing the colors yourself. That is exactly what the pre-3.2 fallback does, and it is a legitimate choice: five @ctp_* variables and two format lines give you the Mocha palette with no dependency, no clone, and nothing to upgrade. The difference is scope. A hand-written status line gives you exactly what you wrote and nothing else; catppuccin/tmux gives you four flavors, a window status style option, and modules for application, CPU, RAM and session that you can reorder.

Another alternative is a general tmux plugin manager setup with a theme plugin that only sets colors. Those tend to leave your status line alone. catppuccin/tmux is more opinionated: it exposes format variables that expect to be placed in status-right, and its recommended configuration shows a specific arrangement. If you want colors only, the pre-3.2 snippet in the README is closer to that model than the plugin itself.

On tmux 3.6 and later there is a third path the README documents: dark and light theme hooks. You can bind client-dark-theme and client-light-theme to switch @catppuccin_flavor between frappe and latte and rerun catppuccin.tmux, so the theme follows the terminal. Before 3.6, the README says you must trigger the reload yourself, and links to a Nix example from a maintainer that reloads Catppuccin on demand without hooks.

Maintenance, licence and upgrade cost

The repository is not archived, and the last push was on 2026-09-21, the same day as the v2.3.1 release. The release history shows v2.3.0 and v2.2.2 in April 2026 and v2.3.1 in September 2026, so releases arrive in occasional batches rather than continuously. The plugin is also pinned by tag in the installation instructions, which means an upgrade is a deliberate act: you change the tag in the clone command or in the TPM plugin line.

The upgrade path has friction. The README documents breaking changes between v0.3 and later versions and links to a pinned migration issue. The TPM section warns about running clean_plugins when upgrading from an earlier version. Because the plugin writes tmux options, an upgrade can change how your existing status-right renders even when your own configuration has not changed.

The licence is MIT, which permits reuse and modification with the licence and copyright notice preserved. That is a permissive arrangement, and it is worth noting only because theme files are often copied into dotfiles: if you copy theme values out of the themes/ directory into your own configuration, the MIT notice still applies to that copied material. This is a description of the licence text, not legal advice.

Editorial conclusion

Adopt catppuccin/tmux if you run tmux 3.2 or later, already use a Nerd Font, and want a status line assembled from modules rather than written by hand. Skip it if you are pinned to an older tmux and unwilling to hand-write the palette, or if your status line is heavily customized, because the plugin owns those options. Before committing, check your tmux version with tmux -V, confirm a patched font is installed, and read docs/reference/configuration.md for the full list of @catppuccin_* variables.

Frequently asked questions

Official sources

1. catppuccin/tmux on GitHub
2. Issues
3. License: MIT
4. README
5. Releases