Custom legend entries in Matplotlib

Introduction

Sometimes you want to explain your plot with labels that are different from the default ones. Custom legend entries let you create clear, easy-to-understand legends for your charts.

When your plot has multiple lines or markers but you want to group some of them under one label.

When you want to add a legend entry for something not directly plotted, like a threshold line or a special marker.

When the automatic legend labels are too long or unclear and you want simpler descriptions.

When you want to show a legend for colors or shapes used in the plot that don’t come from a single plot command.

Syntax

Matplotlib

import matplotlib.pyplot as plt
from matplotlib.lines import Line2D

# Create custom legend entries
custom_legend = [
    Line2D([0], [0], color='blue', lw=2, label='Blue line'),
    Line2D([0], [0], marker='o', color='w', markerfacecolor='red', markersize=10, label='Red dots')
]

# Add legend to plot
plt.legend(handles=custom_legend)

You create custom legend entries by making objects like Line2D or Patch with the style you want.

Then you pass these objects as a list to the handles parameter of plt.legend().

Examples

This shows a legend with one green line even though the plot is empty.

Matplotlib

import matplotlib.pyplot as plt
from matplotlib.lines import Line2D

# Empty plot
plt.plot([])

# Custom legend with one entry
custom_legend = [Line2D([0], [0], color='green', lw=3, label='Green line')]
plt.legend(handles=custom_legend)
plt.show()

Legend shows a purple line and an orange square marker, even though only the purple line is plotted.

Matplotlib

import matplotlib.pyplot as plt
from matplotlib.lines import Line2D

# Plot one line
plt.plot([1, 2, 3], [4, 5, 6], color='purple')

# Custom legend with two entries
custom_legend = [
    Line2D([0], [0], color='purple', lw=2, label='Purple line'),
    Line2D([0], [0], marker='s', color='w', markerfacecolor='orange', markersize=8, label='Orange square')
]
plt.legend(handles=custom_legend)
plt.show()

Custom legend entry for bar color using Patch.

Matplotlib

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

# Plot bars
plt.bar([1, 2], [3, 4], color='cyan')

# Custom legend with patch
custom_legend = [Patch(facecolor='cyan', label='Cyan bars')]
plt.legend(handles=custom_legend)
plt.show()

Sample Program

This program first shows a normal legend for two lines. Then it shows how to add a custom legend with an extra marker entry that is not plotted.

Matplotlib

import matplotlib.pyplot as plt
from matplotlib.lines import Line2D

# Plot two lines
x_values = [0, 1, 2, 3]
line1 = plt.plot(x_values, [1, 2, 3, 4], color='blue')
line2 = plt.plot(x_values, [4, 3, 2, 1], color='red')

print('Before adding custom legend:')
plt.legend(['Blue line', 'Red line'])
plt.show()

# Now create custom legend entries
custom_legend = [
    Line2D([0], [0], color='blue', lw=2, label='Blue line'),
    Line2D([0], [0], color='red', lw=2, label='Red line'),
    Line2D([0], [0], marker='o', color='w', markerfacecolor='green', markersize=10, label='Special marker')
]

print('After adding custom legend with extra marker:')
plt.plot(x_values, [1, 2, 3, 4], color='blue')
plt.plot(x_values, [4, 3, 2, 1], color='red')
plt.legend(handles=custom_legend)
plt.show()

Important Notes

Time complexity is very low since legend creation is simple and fast.

Space complexity depends on how many custom entries you create, usually small.

Common mistake: forgetting to pass the custom objects to handles and expecting automatic legend.

Use custom legend entries when you want full control over legend appearance beyond automatic labels.

Summary

Custom legend entries let you create clear, tailored legends for your plots.

You create legend items using objects like Line2D or Patch with desired styles.

Pass these objects as a list to plt.legend(handles=...) to show your custom legend.