How to customise annotations in Matplotlib

logo of a chart:ScatterPlot

With matplotlib, you can create title to explain your chart, but it's a limited tool when used with the title() function.

In this post, we'll see how one can customise the style and color of titles in matplotlib using the highlight_text package. For more advanced annotations, check out creating advanced annotations in matplotlib


In data visualization, annotations have a major role in available information to the reader.

They can be used to:

  • highlight specific points
  • provide additional information
  • simply explain the data in more depth

However, it can be quite technicaly challenging to customize annotations in matplotlib.

Let's see how we can create nice annotations in a few examples.


Default tools from matplotlib are unfortunately not enough to create nice annotations. We will use the highlight-text package that simplifies the process.

Keep in mind that it would have been possible to use the flexitext package that can do approximately the same thing.

And we will also need to load matplotlib and numpy libraries.

import numpy as np
import matplotlib.pyplot as plt
from highlight_text import fig_text, ax_text

Combine title and subtitle

With matplotlib, the easiest way to combine a title and a subtitle is to use twice the text() function with different y values (position). However, it can be quite tricky to align them properly.

With highlight_text, we just have to pass different properties to our text to differentiate them to quickly create a title and a subtitle.

# create a simple plot
fig, ax = plt.subplots(figsize=(7,6))
    [1, 2, 3, 4],
    [10, 11, 12, 13]

# remove y-axis ticks

# add annotation on top
text = '<The price is going up!>\n<According to XYZ, this phenomenon will continue>'
    x=0.1, # position on x-axis
    y=1, # position on y-axis
        {"color": "black", "fontsize": 20},
        {"color": "grey", "fontsize": 14}


The highlight_text package also allows to color a specific part of the text. This is a great way to add insight and make your chart more understandable.

# dataset
import pandas as pd
dataset = 'master/static/data/iris.csv'
iris = pd.read_csv(''+dataset)

fig, ax = plt.subplots(figsize=(8, 6))
colors = ["#1B9E77", "#D95F02", "#7570B3"]
for species, color in zip(iris['species'].unique(), colors):
    subset = iris[iris['species'] == species]
    ax.scatter(subset['sepal_length'], subset['sepal_width'], c=color, label=species, s=50)

text = 'The iris dataset contains 3 species:\n<setosa>, <versicolor>, and <virginica>'
    x=.5, y=1,
    highlight_textprops=[{"color": colors[0], 'fontweight': 'bold'},
                         {"color": colors[1], 'fontweight': 'bold'},
                         {"color": colors[2], 'fontweight': 'bold'}],

Going further

This post explains how to create nice title in matplotlib.

You might be interested in how to add math in annotations or how to add an image in a plot

Contact & Edit

👋 This document is a work by Yan Holtz. You can contribute on github, send me a feedback on twitter or subscribe to the newsletter to know when new examples are published! 🔥

This page is just a jupyter notebook, you can edit it here. Please help me making this website better 🙏!