Create a Matplotlib pie chart with ax.pie(values, labels=labels, autopct='%1.1f%%'). The input values determine each wedge’s share of the total; category labels, percentage text, rotation, slice separation, and donut styling are controlled with parameters on pie().
Make a basic Matplotlib pie chart
Use matplotlib.pyplot.pie() for a quick chart, or call pie() on an Axes when you want to manage the figure with Matplotlib’s object-oriented interface. This example uses the latter:
import matplotlib.pyplot as plt
labels = ['A', 'B', 'C']
values = [45, 30, 25]
fig, ax = plt.subplots(figsize=(5, 5))
ax.pie(values, labels=labels, autopct='%1.1f%%', startangle=90)
ax.set_title('Share by category')
plt.show()Matplotlib calculates each wedge’s fraction of the pie as its value divided by the sum of all values. With the default normalize=True, the values are normalized to make a complete pie. The pie method sets the Axes aspect ratio to equal; a square plotting area generally helps the chart retain a circular appearance. Matplotlib’s pie() API reference documents the calculation and parameters.
Add category names and percentage labels
Pass one category name per value in labels. Add autopct to print a numeric label inside each wedge. A format such as '%1.1f%%' displays percentages to one decimal place.
Recommended Free Tools
#1 Best Overall
labelssupplies the category names for the wedges.autopctaccepts a format string or a callable that generates numeric labels.pctdistancechanges the radial position ofautopcttext. Values greater than 1 place that text outside the pie.labeldistancechanges the radial position of category labels. Set it toNoneto suppress drawing those labels while retaining them for a legend.
When the chart has too many categories for readable labels around the circle, use a legend instead of forcing every name beside its wedge. Matplotlib’s pie and donut label example shows wedge patches used as legend handles, with the legend placed outside the chart using bbox_to_anchor. It also demonstrates annotations with leader lines for donut labels.
Use pie_label in Matplotlib 3.11 and later
Matplotlib 3.11 added Axes.pie_label(), which labels a pie after it has been created. It takes a string list or a format string using placeholders such as {absval} and {frac}. For example, the documented format below combines the absolute value and percentage:
pie = ax.pie(values)
ax.pie_label(pie, '{absval:d} ({frac:.0%})')The method also supports label distance, text properties, and rotation, and can automatically align labels placed outside the pie on the left and right. Check your installed Matplotlib version before using it: the feature is documented as a 3.11 addition. See the Axes.pie_label() API reference and the Matplotlib 3.11 release notes.
Rotate the chart, separate a slice, and style wedges
Use startangle to rotate where the first wedge begins. It is measured counterclockwise from the x-axis; startangle=90 starts at the top of the chart. The default direction is counterclockwise, and counterclock=False reverses it.
To pull a wedge away from the center, pass an explode sequence with one offset per value. Each offset is a fraction of the pie radius; use zero for wedges that should remain in place. For appearance, colors sets wedge colors, while wedgeprops and textprops pass styling options to the wedge patches and text. Other available controls include radius, center, shadow, frame, and rotatelabels. Hatching patterns via hatch are documented as available since Matplotlib 3.7. The current API reference documents dictionary values for shadow since Matplotlib 3.8. Refer to the API reference for parameter details.
Make a donut chart
A donut is a pie with a hole in the middle. Set the wedge width through wedgeprops; its value must be less than the wedge radius:
fig, ax = plt.subplots(figsize=(5, 5))
ax.pie(values, labels=labels, autopct='%1.1f%%',
wedgeprops={'width': 0.4})
ax.set_title('Share by category')
plt.show()The width controls the thickness of the wedges. For many categories, combine the donut with an outside legend or annotated labels and leader lines, as shown in Matplotlib’s gallery example.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.When to use a partial pie
By default, Matplotlib normalizes the inputs into a full circle. If you set normalize=False, a partial pie is allowed when the values sum to at most 1; a sum greater than 1 raises ValueError. This is different from the default, where values are interpreted as relative parts of a whole and normalized automatically. Consult the API reference when choosing between these behaviors.
Outdated Drivers Are Slowing You Down
One free scan finds every outdated or missing driver and matches the right update for your exact hardware.Free scan · exact hardware matchWindows Errors? Fix Them Before They Spread
Repair common Windows errors and clear accumulated junk for a smoother, more stable PC - no reinstall needed.Free scan · no reinstallQuick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
