Catppuccin for Python

Installation

Install with pip or your preferred dependency management tool.

pip install catppuccin

Usage

Get access to the palette with the catppuccin.PALETTE constant:

from catppuccin import PALETTE

PALETTE.latte.colors.mauve.hex
# '#8839ef'
PALETTE.mocha.colors.teal.rgb
# RGB(r=148, g=226, b=213)

The Palette data structure matches the palette JSON.

Iteration

Both Palette and FlavorColors can be iterated to yield flavors and colors respectively:

for flavor in PALETTE:
    print(flavor.name)

# Latte
# Frappé
# Macchiato
# Mocha

for color in PALETTE.latte.colors:
    print(f"{color.name}: {color.hex}")

# Rosewater: #f2d5cf
# Flamingo: #eebebe
# Pink: #f4b8e4
# ...
# Base: #303446
# Mantle: #292c3c
# Crust: #232634

dataclasses

Palette, Flavor, Color et cetera are all dataclasses, so you can also inspect and iterate their fields using methods from the dataclass module.

For example, to list all color names and their hex codes:

from dataclasses import fields
from catppuccin import PALETTE

flavor = PALETTE.frappe
for field in fields(flavor.colors):
    color = getattr(flavor.colors, field.name)
    print(f"{field.name}: {color.hex}")

# rosewater: #f2d5cf
# flamingo: #eebebe
# pink: #f4b8e4
# ...
# base: #303446
# mantle: #292c3c
# crust: #232634

Pygments Styles

This package provides a Pygments style for each of the four Catppuccin flavors.

Install Catppuccin with the pygments feature to include the relevant dependencies:

pip install catppuccin[pygments]

The styles are registered as importlib entrypoints, which allows Pygments to find them by name:

from pygments.styles import get_style_by_name

get_style_by_name("catppuccin-frappe")
# catppuccin.extras.pygments.FrappeStyle

The following style names are available:

• catppuccin-latte
• catppuccin-frappe
• catppuccin-macchiato
• catppuccin-mocha

They can also be accessed by directly importing them:

from catppuccin.extras.pygments import MacchiatoStyle

IPython

A minimal configuration:

c.TerminalInteractiveShell.true_color = True
c.TerminalInteractiveShell.highlighting_style = "catppuccin-mocha"

Putting this into your IPython configuration and ensuring catppuccin[pygments] is installed in the same environment will give you Catppuccin Mocha syntax highlighting in the REPL. See here for an example of a more complete configuration.

Matplotlib

The library tries to register styles and colormaps if matplotlib is installed. See the examples below for some use cases:

1. Load a style, using mpl.style.use

   import catppuccin
   import matplotlib as mpl
   import matplotlib.pyplot as plt
   
   mpl.style.use(catppuccin.PALETTE.mocha.identifier)
   plt.plot([0,1,2,3], [1,2,3,4])
   plt.show()

2. Mix it with different stylesheets!

   import catppuccin
   import matplotlib as mpl
   import matplotlib.pyplot as plt
   
   mpl.style.use(["ggplot", catppuccin.PALETTE.mocha.identifier])
   plt.plot([0,1,2,3], [1,2,3,4])
   plt.show()

3. Load individual colors

   import matplotlib.pyplot as plt
   import catppuccin
   from catppuccin.extras.matplotlib import load_color
   
   color = load_color(catppuccin.PALETTE.latte.identifier, "peach")
   plt.plot([0,1,2,3], [1,2,3,4], color=color)
   plt.show()

4. Define custom colormaps

   import matplotlib.pyplot as plt
   import numpy as np
   import catppuccin
   from catppuccin.extras.matplotlib import get_colormap_from_list
   
   cmap = get_colormap_from_list(
       catppuccin.PALETTE.frappe.identifier,
       ["red", "peach", "yellow", "green"],
   )
   rng = np.random.default_rng()
   data = rng.integers(2, size=(30, 30))
   
   plt.imshow(data, cmap=cmap)
   plt.show()

Contribution

If you are looking to contribute, please read through our CONTRIBUTING.md first!

Development

This project is maintained with uv. If you don't have uv yet, you can install it using the installation instructions.

Install the project's dependencies including extras:

uv sync --all-extras

Codegen

catppuccin/palette.py is generated by a build script based on the contents of palette.json.

To update after downloading a new palette JSON file:

uv run build.py

Formatting this file is done manually as with any other file, see Code Standards below.

Code Standards

All of the tools listed in this section are automatically installed by uv as part of the dev dependency group.

Unit Tests

Tests are run with pytest.

To run tests and display coverage:

$ pytest --cov catppuccin

Type Checking

Type checking is performed by mypy.

To run type checks:

$ mypy .

Lints and Formatting

Code linting and formatting is done by ruff.

To lint the code:

$ ruff check

To format the code:

$ ruff format

💝 Thanks to

• backwardspy
• Bram de Wilde
• miloth

 

Copyright © 2022-present Catppuccin Org