Introduction on how to use the PyPalettes library

logo of a chart:Colours

This post describes how to use the pypalettes library to customize the colors of your Python visualizations. You will learn how create different charts with different kinds of palettes such as categorical or continuous.

This post stands as the official documentation of pypalettes, but you can find more info about it in the dedicated github repo


pypalettes is a python library that provides more than 2500 different palettes to use in your data visualization. It comes with a very simple-to-use API that only requires 1 line of code.

You can find your dream palette on the dedicated web app that highlights how palettes look like on different kind of charts.

You can install it by running pip install pypalettes in your terminal!

Quick start

The easiest way to get started is to choose an example that you like and try to change the name argument of the load_cmap() function:

# load libraries
import geopandas as gpd
import matplotlib.pyplot as plt
from pypalettes import load_cmap

# load the world dataset
df = gpd.read_file('')
df = df[df['name'] != 'Antarctica']

# create a color palette
cmap = load_cmap(name='Acadia', type='continuous')

# display the world map
fig, ax = plt.subplots(figsize=(10, 10), dpi=300)
df.plot(ax=ax, cmap=cmap, edgecolor='white', linewidth=0.3)

All the different ways to load a colormap

Let's start by importing the load_cmap() function:

from pypalettes import load_cmap

Load a random palette

cmap = load_cmap('random')

Load a specific colormap

cmap = load_cmap('Acanthurus_triostegus')

Continuous version of a palette with type='continuous' (default is 'discrete')

cmap = load_cmap('Acanthurus_triostegus', type='continuous')

Reverse the order of a colormap with reverse=True

cmap = load_cmap('Acanthurus_triostegus', reverse=True)

Keep only the first colors of a palette with keep_first_n

cmap = load_cmap('Acanthurus_triostegus', keep_first_n=3)

Keep only specific colors from a palette with the keep argument

cmap = load_cmap('Acanthurus_triostegus', keep=[False, True, False, True, True])

Discrete palettes

When loading a discrete palette, it looks like this:

from pypalettes import load_cmap

cmap = load_cmap("Acadia")

In this case, cmap is actually a function that can be used to retrieve elements. For example:

  • cmap(0) gives us the first color (RGBA format) of the palette
  • cmap(1) gives us the second one
  • and so on
(0.996078431372549, 0.8431372549019608, 0.5372549019607843, 1.0) (0.00784313725490196, 0.21568627450980393, 0.2627450980392157, 1.0)

What if we try cmap(10) for a palette of only 7 colors like in our case? It returns the last color in the palette:


print(f'cmap(6) == cmap(7): {cmap(6) == cmap(7)}')
(0.996078431372549, 0.8431372549019608, 0.5372549019607843, 1.0) (0.00784313725490196, 0.21568627450980393, 0.2627450980392157, 1.0) (0.4470588235294118, 0.5294117647058824, 0.3058823529411765, 1.0) (0.2784313725490196, 0.43529411764705883, 0.5176470588235295, 1.0) (0.6431372549019608, 0.7450980392156863, 0.8352941176470589, 1.0) (0.27058823529411763, 0.2235294117647059, 0.2784313725490196, 1.0) (0.27058823529411763, 0.2235294117647059, 0.2784313725490196, 1.0) (0.27058823529411763, 0.2235294117647059, 0.2784313725490196, 1.0) cmap(6) == cmap(7): True

Ok now let's see we use for a real chart. We will create the now famous iris scatter plot, with colors from pypalettes.

import seaborn as sns
import matplotlib.pyplot as plt
from pypalettes import load_cmap
from highlight_text import fig_text

# load the color map
cmap = load_cmap("Acadia", keep_first_n=3)

# load the dataset
df = sns.load_dataset('iris')

# the column that we want to map with colors must be a `category`
df['species'] = df['species'].astype("category")

# create the chart
fig, ax = plt.subplots(figsize=(14, 10), dpi=300)
   x=df['sepal_length'], y=df['sepal_width'],
   c=df['species'], cmap=cmap,

# title
    s='The iris dataset contains 3 species: <setosa>, <versicolor>, and <virginica>',
    x=.5, y=0.93, fontsize=20, ha='center',
    highlight_textprops=[{"color": cmap(0), 'fontweight': 'bold'},
                         {"color": cmap(1), 'fontweight': 'bold'},
                         {"color": cmap(2), 'fontweight': 'bold'}]