Catppuccin for Tmux

Content

1. Themes
2. Installation
3. Overview
4. Configuration options
   1. Window
   2. Pane
   3. Status Line
   4. Using the theme's built-in status modules
5. Configuration Examples
   1. Config 1
   2. Config 2
   3. Config 3

Themes

• 🌻 Latte
• 🪴 Frappé
• 🌺 Macchiato
• 🌿 Mocha

Installation

Important

The plugin was re-written from bash to use tmux's native configuration language. This occurred after v0.3.0. Old configurations will need to be updated. Please consider if the upgrade is worth the tradeoff.

In order to have the icons displayed correctly please use/update your favorite patched font. If you do not have a patched font installed, you can override or remove any icon. Check the documentation below on the options available.

Note

If you are using a tmux version older than 3.0, you will need to follow the instructions for older versions.

Manual (Recommended)

This method is recommended as TPM has some issues with name conflicts.

1. Clone this repository to your desired location (e.g. ~/.config/tmux/plugins/catppuccin).

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

2. Add the following line to your tmux.conf file: run ~/.config/tmux/plugins/catppuccin/tmux/catppuccin.tmux
3. (Optional) Set your preferred flavor and/or add configuration options as listed in Configuration Options. These options must be added above the run ~/.config... line.
4. Reload Tmux by either restarting or reloading with tmux source ~/.tmux.conf

Important

You may have to run ~/.config/tmux/plugins/tpm/bin/clean_plugins if upgrading from an earlier version (especially from v0.3.0).

TPM

1. Install TPM
2. Add the Catppuccin plugin:

set -g @plugin 'catppuccin/tmux#v1.0.3' # See https://github.com/catppuccin/tmux/tags for additional tags
# ...alongside
set -g @plugin 'tmux-plugins/tpm'

3. (Optional) Set your preferred flavor, it defaults to "mocha":

set -g @catppuccin_flavor 'mocha' # latte, frappe, macchiato or mocha

For TMUX versions prior to 3.2

This plugin uses features that were only introduced into tmux in version 3.2. If you are using a version earlier than this, you can still have lovely catppuccin colors, the installation method just looks a little different.

# In your ~/.tmux.conf

# Add the colors from the pallete. Check the themes/ directory for all options.

# Some basic mocha colors.
set -g @ctp_bg "#24273a"
set -g @ctp_surface_1 "#494d64"
set -g @ctp_fg "#cad3f5"
set -g @ctp_mauve "#c6a0f6"
set -g @ctp_crust "#181926"

# status line
set -gF status-style "bg=#{@ctp_bg},fg=#{@ctp_fg}"

# windows
set -gF window-status-format "#[bg=#{@ctp_surface_1},fg=#{@ctp_fg}] ##I ##T "
set -gF window-status-current-format "#[bg=#{@ctp_mauve},fg=#{@ctp_crust}] ##I ##T "

Upgrading from 0.3

Breaking changes have been introduced since 0.3, to understand how to migrate your configuration, see pinned issue #291.

Recommended Default Configuration

This configuration shows some customisation options, that can be further extended as desired.

# ~/.tmux.conf

# Options to make tmux more pleasant
set -g mouse on
set -g default-terminal "tmux-256color"

# Configure the catppuccin plugin
set -g @catppuccin_flavor "macchiato"
set -g @catppuccin_window_status_style "rounded"
# leave this unset to let applications set the window title
set -g @catppuccin_window_default_text " #W"
set -g @catppuccin_window_current_text " #W"
set -g @catppuccin_window_status "icon"
set -g @catppuccin_window_current_background "#{@thm_mauve}"

# Load catppuccin
run ~/.config/tmux/plugins/catppuccin/tmux/catppuccin.tmux
# For TPM, instead use `run ~/.config/tmux/plugins/tmux/catppuccin.tmux`

# Make the status line pretty and add some modules
set -g status-left ""
set -g status-right "#{E:@catppuccin_status_user}"
set -ag status-right "#{E:@catppuccin_status_directory}"

Overview

This is a diagram of how the theme is split between its components.

Configuration options

All flavors support certain levels of customization that match our Catppuccin Style Guide. To add these customizations, add any of the following options to your Tmux configuration.

Window

The plugin comes with three window styles built in, these can be customized by setting the @catppuccin_window_status_style option. The default is basic.

Option	Effect	Preview
basic	Simple styling with blocks.
rounded	Each window is separated with rounded separators.
slanted	Each window is separated with slanted separators.
custom	Custom separators are used. This is required to override the separators!
none	Styling of the window status is completely disabled.

If you want to change the active color to something else (the default is peach), use the following. For example to use lavender:

set -g @catppuccin_window_current_background "#{@thm_lavender}"

Customising the separators

Add the following (above set -g @plugin "catppuccin/tmux" if using TPM), setting whatever values you'd like for the separators:

set -g @catppuccin_window_status_style "custom"
set -g @catppuccin_window_left_separator ""
set -g @catppuccin_window_middle_separator ""
set -g @catppuccin_window_right_separator ""

Pane

Set the pane border style

set -g @catppuccin_pane_border_style "fg=#{@thm_surface_0}" # Use a value compatible with the standard tmux 'pane-border-style'

Set the pane active border style

set -g @catppuccin_pane_active_border_style "fg=#{@thm_peach}" # Use a value compatible with the standard tmux 'pane-border-active-style'

Menu

Set the menu selected style:

set -g @catppuccin_menu_selected_style "fg=#{@thm_surface_0},bg=#{@thm_yellow}" # Use a value compatible with the standard tmux `menu-selected-style`

Status Line

Set the default status bar visibility:

set -g @catppuccin_status_default "on"

Override the default status background color:

set -g @catppuccin_status_background "default"

This will overwrite the status bar background:

• default will use the color from the selected theme
• none will make the status bar transparent
• use hex color codes for other colors or a theme color (#{@thm_<color>})

Note: you need to restart tmux for this to take effect:

tmux kill-server && tmux

Set the status module left separator:

set -g @catppuccin_status_left_separator ""

Set the status module right separator:

set -g @catppuccin_status_right_separator "█"

Set the status connect separator:

set -g @catppuccin_status_connect_separator "yes"

Possible values:

• yes - the background color of the separator will not blend in with the background color of tmux
• no - the background color of the separator will blend in with the background color of tmux

Set the status module color fill:

set -g @catppuccin_status_fill "icon"

Values:

• icon - only the icon of the module will have color
• all - the entire module will have the same color

Set the status module justify value:

set -g @catppuccin_status_justify "left"

Values:

• left
• centre - puts the window list in the relative centre of the available free space
• right
• absolute-centre - uses the centre of the entire horizontal space

Pane Options

By default no pane styling options are set. To enable, set @catppuccin_pane_status_enabled to yes.

Defaults:

set -g @catppuccin_pane_status_enabled "no"
set -g @catppuccin_pane_border_status "off" # See `pane-border-status`
set -g @catppuccin_pane_left_separator "█"
set -g @catppuccin_pane_right_separator "█"
set -g @catppuccin_pane_middle_separator "█"
set -g @catppuccin_pane_number_position "left"
set -g @catppuccin_pane_default_fill "number"
set -g @catppuccin_pane_default_text "#{b:pane_current_path}"
set -g @catppuccin_pane_border_style "fg=#{@thm_overlay_0}"
set -g @catppuccin_pane_active_border_style "#{?pane_in_mode,fg=#{@thm_lavender},#{?pane_synchronized,fg=#{@thm_magenta},fg=#{@thm_lavender}}}"
set -g @catppuccin_pane_color "#{@thm_green}"
set -g @catppuccin_pane_background_color "#{@thm_surface_0}"

Using the theme's built-in status modules

To use the theme's built in status modules, set the status-left and status-right tmux options after the plugin has been loaded.

The tmux status line modules are set as variables and prefixed with @catppuccin_status_<module>.

To use the application and session modules on the right and have nothing on the left:

set -g status-right "#{E:@catppuccin_status_application}#{E:@catppuccin_status_session}"
set -g status-left ""

Available modules:

• application - display the current window running application
• directory - display the basename of the current window path
• session - display the number of tmux sessions running
• user - display the username
• host - display the hostname
• date_time - display the date and time
• uptime - display the uptime
• battery - display the battery

For a full list of modules and their options see status.

Configuration Examples

Below are provided a few configurations as examples or starting points.

Note: When switching between configurations run:

tmux kill-server

To kill the tmux server and clear all global variables.

Config 1

# Disable catppuccin styling windows.
set -g @catppuccin_window_status_style "none"
set -g @catppuccin_status_left_separator "█"
set -g @catppuccin_status_right_separator "█"

set -g @catppuccin_date_time_text "%Y-%m-%d %H:%M:%S"

# Run catppuccin plugin manually or through tpm
# ...

# Style the windows. See https://man7.org/linux/man-pages/man1/tmux.1.html#STYLES for more details.
set -gF window-status-style "bg=#{@thm_surface_1},fg=#{@thm_fg}"
set -gF window-status-current-style "bg=#{@thm_peach},fg=#{@thm_crust}"

set -g window-status-format " #T | #I "
set -g window-status-current-format " #T | #I "

set -g status-left ""
set -g  status-right "#{E:@catppuccin_status_application}"
set -ag status-right "#{E:@catppuccin_status_session}"
set -ag status-right "#{E:@catppuccin_status_user}"
set -ag status-right "#{E:@catppuccin_status_host}"
set -ag status-right "#{E:@catppuccin_status_date_time}"

Config 2

set -g @catppuccin_window_status_style "slanted"
set -g @catppuccin_window_number_position "right"

set -g @catppuccin_window_default_fill "number"

set -g @catppuccin_window_current_fill "number"
set -g @catppuccin_window_current_text "#{pane_current_path}"

set -g @catppuccin_status_left_separator  ""
set -g @catppuccin_status_right_separator " "
set -g @catppuccin_status_fill "all"
set -g @catppuccin_status_connect_separator "yes"

# Run catppuccin plugin manually or through tpm
# ...

set -g status-left ""
set -gF status-right "#{E:@catppuccin_status_application}#{E:@catppuccin_status_session}#{E:@catppuccin_status_date_time}"

Config 3

set -g @catppuccin_window_status_style "rounded"
set -g @catppuccin_window_number_position "right"

set -g @catppuccin_window_default_fill "number"
set -g @catppuccin_window_default_text "#W "

set -g @catppuccin_window_current_fill "number"
set -g @catppuccin_window_current_text "#W "

set -g @catppuccin_status_left_separator  " "
set -g @catppuccin_status_right_separator ""
set -g @catppuccin_status_fill "icon"
set -g @catppuccin_status_connect_separator "no"

set -g @catppuccin_directory_text "#{pane_current_path}"

# Run catppuccin plugin manually or through tpm
# ...

set -g status-left ""
set -g  status-right "#{E:@catppuccin_status_directory}"
set -ag status-right "#{E:@catppuccin_status_user}"
set -ag status-right "#{E:@catppuccin_status_host}"
set -ag status-right "#{E:@catppuccin_status_session}"

💝 Thanks to

• Pocco81
• vinnyA3
• rogeruiz

 

Copyright © 2021-present Catppuccin Org