Matplotlib is the most famous library for data visualization with python. It allows to create literally every type of chart with a great level of customization. This page provides some general tips that can be applied on any kind of chart made with matplotlib like customizing titles or colors. If you're looking at creating a specific chart type, visit the gallery instead.

⏱ Quick start

Matplotlib is the most famous python data visualization library. It is widely used and most of other viz libraries (like seaborn) are actually built on top of it.

Once installed, matplotlib must be imported, usually using import matplotlib.pyplot as plt. You can then use use the functions available in the plt object.

# library
import numpy as np
import matplotlib.pyplot as plt

# Create data

# Area plot
plt.fill_between(x, y)

Matplotlib logoBasic vocabulary

The figure below describes the anatomy of a matplotlib charts. It names all the main components, names that you need to know to understand the documentation properly.

⚠️ Disclaimer: this figure comes from the very complete matplotlib documentation. Have a look at it for a thorough explanation on how this library works.

Anatomy of a matplotlib chart: all the basic vocabulary you need to know to understand the documentation properly

Matplotlib logoTwo distinct APIs

There are 2 main ways to build a chart with matplotlib: the pyplot API and the object-oriented API.

➡️ pyplot API

Pyplot is a collection of functions, each function applying a change to a figure. For instance, plt.barh() will build a barplot and plt.title() will add a title to it.

# import libraries
import pandas as pd
import matplotlib.pyplot as plt

# Create a data frame
df = pd.DataFrame ({'Group':  ['A', 'B', 'C', 'D', 'E'], 'Value': [1,5,4,3,9]})

# Create horizontal bars
plt.barh(y=df.Group, width=df.Value);

# Add title
plt.title('A simple barplot');

➡️ object oriented API

The object oriented API usually starts by initializing one Figure object and one or more Axes object using the subplot() function. Then the methods of those objects will be used to apply changes to the chart.

# import libraries
import pandas as pd
import matplotlib.pyplot as plt

# Create a data frame
df = pd.DataFrame ({'Group':  ['A', 'B', 'C', 'D', 'E'], 'Value': [1,5,4,3,9]})

# Initialize a Figure and an Axes
fig, ax = plt.subplots()

# Fig size

# Create horizontal bars
ax.barh(y=df.Group, width=df.Value);

# Add title
ax.set_title('A simple barplot');

See how the syntax slightly differs between both options? (plt.title versus ax.set_title(). This is pretty confusing and I advise to have a look to the official documentation for a more thorough explanation. In the gallery, both APIs are used.

Matplotlib logoCustomizing titles

The title is a key part of a good chart. It has to summarize its key message in a few words. Always avoid to simply repeat what is displayed on each axis. Try to provide some more insight allowing to understand the main result instead.

The post #190 goes in depth on how to customize the matplotlibtitle. All the main types of change are descried: changing its color, adding a subtitle, using math formulas and so on. Give it a go!

Matplotlib logoAnnotation

Annotation is a key part of a great visualization. It transforms a simple chart in a whole piece of story telling. Before you share your graph with anyone, make sure the key insight are highlighted with labels, shapes or color.

All those kind of annotation are built thanks to various matplotlib functions like annotate() or add_patch(). The blogposts showcased below should get you started with it.

Matplotlib logoCustom fonts

Using custom fonts adds a nice touch to your graph and make it shine among all the other plots using defaults. The blog-post below will guide you through the process: installing a font and calling it with matplotlib functions.

How to use custom fonts with matplotlib

Matplotlib logoAdd margin around a matplotlib chart

It is a common struggle to deal with the margins around the chart. Fortunately this is pretty straightforward thanks to the subplots_adjust() function as explained in the examples below.

Matplotlib logoSplit the figure in subplots

It can be really useful to split your graphic window in several parts, in order to display several charts in the same time. The subplot() function of matplotlib allows to do it quickly with a great level of customization.

Additional note: how to remove some unused entries in a grid using the ax.remove() function:

Matplotlib logoAvailable style sheets

Matplotlib comes with a set of 26 pre-built themes to style your chart easily. This post is dedicated to this feature, explaining how to use to pick a theme up.

Customize a matplotlib chart with a preset theme

Matplotlib logoCustomizing axis

Matplotlib allows every kind of axis configuration. It is mainly done thanks to the tick_params(), xticks() and xlabels() functions. The post #191 will guide you through all the possibilities.

Matplotlib logoCustomizing the legend

If you have several colors or marker on your chart, you can't escape the hassle of building a nice legend. The blogpost linked below should help for all the most common use cases like positioning the legend, adding and customizing a title to it, controling markers and labels and more.


👋 This document is a work by Yan Holtz. Any feedback is highly encouraged. You can fill an issue on Github, drop me a message onTwitter, or send an email pasting with










Connected Scatter

2D Density


Spider / Radar




Circular Barplot


Venn Diagram


Pie Chart


Circular Packing

Line chart

Area chart

Stacked Area


Timeseries with python








Chord Diagram



Arc Diagram

Edge Bundling



Animation with python


Cheat sheets