How to Use Patches in Matplotlib: Simple Guide with Examples

In matplotlib, patches are shapes like rectangles, circles, and polygons that you can add to plots using matplotlib.patches. You create a patch object (e.g., Rectangle) and add it to an Axes using ax.add_patch() to display it on the plot.

Syntax

To use patches in matplotlib, first import the patch class you want from matplotlib.patches. Then create an instance of the patch with parameters like position and size. Finally, add the patch to an axes object using ax.add_patch().

• patch = Rectangle((x, y), width, height, **kwargs): Creates a rectangle patch.
• ax.add_patch(patch): Adds the patch to the plot.
• plt.show(): Displays the plot with the patch.

python

from matplotlib.patches import Rectangle
import matplotlib.pyplot as plt

fig, ax = plt.subplots()
rect = Rectangle((0.1, 0.1), 0.5, 0.3, edgecolor='blue', facecolor='cyan')
ax.add_patch(rect)
plt.show()

Example

This example shows how to draw a blue rectangle and a red circle on a plot using patches. It demonstrates creating patch objects and adding them to the axes.

python

import matplotlib.pyplot as plt
from matplotlib.patches import Rectangle, Circle

fig, ax = plt.subplots()

# Create a rectangle patch
rect = Rectangle((0.2, 0.3), 0.4, 0.2, edgecolor='blue', facecolor='lightblue', linewidth=2)
ax.add_patch(rect)

# Create a circle patch
circle = Circle((0.7, 0.7), 0.1, edgecolor='red', facecolor='pink', linewidth=2)
ax.add_patch(circle)

# Set limits and show plot
ax.set_xlim(0, 1)
ax.set_ylim(0, 1)
ax.set_aspect('equal')
plt.show()

Output

A plot window showing a light blue rectangle with blue border near bottom-left and a pink circle with red border near top-right inside a square plot area.

Common Pitfalls

Common mistakes when using patches include:

• Not adding the patch to the axes with ax.add_patch(), so the shape does not appear.
• Forgetting to set plot limits, causing patches to be outside the visible area.
• Using incorrect coordinates or sizes that place patches off the plot.
• Not setting aspect='equal' when shapes need to keep their proportions.

python

import matplotlib.pyplot as plt
from matplotlib.patches import Rectangle

fig, ax = plt.subplots()

# Wrong: creating patch but not adding it
rect = Rectangle((0.1, 0.1), 0.5, 0.3, edgecolor='green', facecolor='yellow')
# ax.add_patch(rect)  # Missing this line

ax.set_xlim(0, 1)
ax.set_ylim(0, 1)
plt.show()

# Correct way:
fig, ax = plt.subplots()
rect = Rectangle((0.1, 0.1), 0.5, 0.3, edgecolor='green', facecolor='yellow')
ax.add_patch(rect)
ax.set_xlim(0, 1)
ax.set_ylim(0, 1)
ax.set_aspect('equal')
plt.show()

Output

First plot shows empty axes with no rectangle visible. Second plot shows a yellow rectangle with green border inside the plot.

Quick Reference

Patch Type	Constructor Example	Description
Rectangle	Rectangle((x, y), width, height, **kwargs)	Draws a rectangle at (x,y) with given width and height.
Circle	Circle((x_center, y_center), radius, **kwargs)	Draws a circle with center and radius.
Polygon	Polygon([[x1, y1], [x2, y2], ...], **kwargs)	Draws a polygon with given vertices.
Ellipse	Ellipse((x_center, y_center), width, height, **kwargs)	Draws an ellipse centered at given point.
FancyBboxPatch	FancyBboxPatch((x, y), width, height, boxstyle, **kwargs)	Draws a fancy box with styles like round corners.

Key Takeaways

Create patch objects from matplotlib.patches and add them to axes with ax.add_patch().

Always set plot limits and aspect ratio to ensure patches are visible and proportioned.

Common errors include forgetting to add patches to axes or setting limits.

Patches let you draw shapes like rectangles, circles, polygons, and ellipses on plots.

Customize patches with colors, edge styles, and line widths using keyword arguments.