matplotlib · timhoffm · Jul 13, 2024 · Jan 23, 2025 · Jan 22, 2025 · Jan 23, 2025
diff --git a/doc/_embedded_plots/grouped_bar.py b/doc/_embedded_plots/grouped_bar.py
@@ -0,0 +1,15 @@
+import matplotlib.pyplot as plt
+
+categories = ['A', 'B']
+data0 = [1.0, 3.0]
+data1 = [1.4, 3.4]
+data2 = [1.8, 3.8]
+
+fig, ax = plt.subplots(figsize=(4, 2.2))
+ax.grouped_bar(
+    [data0, data1, data2],
+    tick_labels=categories,
+    labels=['dataset 0', 'dataset 1', 'dataset 2'],
+    colors=['#1f77b4', '#58a1cf', '#abd0e6'],
+)
+ax.legend()
diff --git a/doc/api/axes_api.rst b/doc/api/axes_api.rst
@@ -67,6 +67,7 @@ Basic
   Axes.bar
   Axes.barh
   Axes.bar_label
+   Axes.grouped_bar

   Axes.stem
   Axes.eventplot

diff --git a/doc/api/pyplot_summary.rst b/doc/api/pyplot_summary.rst
@@ -61,6 +61,7 @@ Basic
   bar
   barh
   bar_label
+   grouped_bar
   stem
   eventplot
   pie

diff --git a/doc/users/next_whats_new/grouped_bar.rst b/doc/users/next_whats_new/grouped_bar.rst
@@ -0,0 +1,26 @@
+Grouped bar charts
+------------------
+
+The new method `~.Axes.grouped_bar()` simplifies the creation of grouped bar charts
+significantly. It supports different input data types (lists of datasets, dicts of
+datasets, data in 2D arrays, pandas DataFrames), and allows for easy customization
+of placement via controllable distances between bars and between bar groups.
+
+Example:
+
+.. plot::
+    :include-source: true
+    :alt: Diagram of a grouped bar chart of 3 datasets with 2 categories.
+
+    import matplotlib.pyplot as plt
+
+    categories = ['A', 'B']
+    datasets = {
+        'dataset 0': [1, 11],
+        'dataset 1': [3, 13],
+        'dataset 2': [5, 15],
+    }
+
+    fig, ax = plt.subplots()
+    ax.grouped_bar(datasets, tick_labels=categories)
+    ax.legend()
diff --git a/galleries/examples/lines_bars_and_markers/barchart.py b/galleries/examples/lines_bars_and_markers/barchart.py
@@ -10,7 +10,6 @@
 # data from https://allisonhorst.github.io/palmerpenguins/

 import matplotlib.pyplot as plt
-import numpy as np

 species = ("Adelie", "Chinstrap", "Gentoo")
 penguin_means = {
@@ -19,22 +18,15 @@
    'Flipper Length': (189.95, 195.82, 217.19),
 }

-x = np.arange(len(species))  # the label locations
-width = 0.25  # the width of the bars
-multiplier = 0
-
 fig, ax = plt.subplots(layout='constrained')

-for attribute, measurement in penguin_means.items():
-    offset = width * multiplier
-    rects = ax.bar(x + offset, measurement, width, label=attribute)
-    ax.bar_label(rects, padding=3)
-    multiplier += 1
+res = ax.grouped_bar(penguin_means, tick_labels=species, group_spacing=1)
+for container in res.bar_containers:
+    ax.bar_label(container, padding=3)

-# Add some text for labels, title and custom x-axis tick labels, etc.
+# Add some text for labels, title, etc.
 ax.set_ylabel('Length (mm)')
 ax.set_title('Penguin attributes by species')
-ax.set_xticks(x + width, species)
 ax.legend(loc='upper left', ncols=3)
 ax.set_ylim(0, 250)