Catppuccin for Tmux: Four Flavors, One Manual Install Away

You've probably spent more time than you'd like to admit tweaking your terminal colors. Maybe you've got your editor looking just right, but then you open tmux and it's a jarring mismatch. The Catppuccin theme family has been solving that problem across a growing list of applications, and their tmux port brings the same palette to your status line, windows, and panes.

What It Does

Catppuccin for tmux is a theme plugin that applies the Catppuccin color palette to your tmux configuration. It ships with four flavors—Latte, Frappé, Macchiato, and Mocha—so you can pick the mood that suits your setup, whether that's a light theme for daytime work or something darker for late-night sessions.

Under the hood, the plugin leverages tmux features introduced in version 3.2, which is worth knowing if you're running an older tmux build. It supports icon rendering, and the README recommends using a patched nerd font to get those icons displaying correctly. If you don't have one installed, you can override or remove any icon through the plugin's configuration options. The project also maintains documentation on those options if you want to go beyond the defaults.

Why It's Cool

Here's what stands out about this particular implementation:

• The manual install is the recommended path. That's unusual—most plugins push you toward a plugin manager. The README is upfront about why: TPM has some issues with name conflicts when it comes to this theme. Rather than pretend everything's fine, the maintainers steer you toward the method that actually works reliably. That kind of honesty is refreshing.

• Four flavors means it adapts to your environment, not the other way around. You're not locked into a single dark theme. Latte gives you something light and readable, while Mocha is the deepest and most saturated option. The default is Mocha if you don't specify, but switching is as simple as setting a variable.

• There's a fallback for older tmux versions. If you're stuck on something prior to 3.2, the README doesn't just tell you to upgrade. It walks you through manually setting color variables in your tmux.conf so you can still get the Catppuccin look. It's more work, but it's there.

• Icons are handled thoughtfully. The plugin uses nerd font icons, but it doesn't assume you have a patched font. You can override or remove any icon you don't want, which means you're not forced into installing a font just to get the colors working.

• The configuration is straightforward. Setting your flavor is one line. That's it. You don't have to dig through layers of options unless you want to customize further.

How to Try It

The recommended installation is manual. Here's the process:

1. Clone the repository to your desired location. The README suggests ~/.config/tmux/plugins/catppuccin:

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

1. Add this line to your tmux.conf:

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

1. Reload tmux by restarting it or running tmux source ~/.tmux.conf.

If you prefer TPM despite the caveats, you can add the plugin with set -g @plugin 'catppuccin/tmux#v2.3.1' alongside your TPM plugin line. You can optionally set your flavor with set -g @catppuccin_flavor 'mocha'—the options are latte, frappe, macchiato, or mocha. Just be aware that if you're upgrading from an earlier version (especially v0.3.0), you might need to run the TPM clean_plugins script to avoid conflicts.

For tmux versions before 3.2, you'll need to manually set color variables in your tmux.conf. The README provides an example using Mocha colors, and you can check the themes directory for other options.

The repository is at github.com/catppuccin/tmux, and there's a getting started guide linked in the README if you want to go further.

Final Thoughts

If you're already invested in the Catppuccin ecosystem, this is an obvious addition. It keeps your tmux session visually consistent with the rest of your setup, and the four flavors give you flexibility without complexity. The manual install recommendation might feel like a step backward if you're used to TPM handling everything, but it's a practical trade-off for reliability. This is best for developers who care about their terminal environment and don't mind a few extra lines in their config. If you're on tmux 3.2 or later and want a theme that just works once it's set up, this is worth the five minutes.