Add legend.linewidth parameter to control legend box edge linewidth #30780

manit2004 · 2025-11-22T19:58:27Z

PR summary

Why is this change necessary?

Users can customize many aspects of legend appearance through rcParams (facecolor, edgecolor, framealpha, shadow, etc.), but there was no way to control the linewidth of the legend's box edges. This created an inconsistency in the customization API and required workarounds when users wanted legends with thicker or thinner frame lines to match their plot aesthetics.

What problem does it solve?

This solves the problem of not being able to independently control legend frame linewidth. Previously, the legend frame linewidth was implicitly tied to the default patch linewidth, making it impossible to have, for example, thin axes borders but thick legend borders, or vice versa.

What is the reasoning for this implementation?

The implementation follows matplotlib's existing pattern for legend customization:

Added a new legend.linewidth rcParam (default: None)
When None, it inherits from axes.linewidth for backward compatibility
Added a linewidth parameter to Legend.__init__() for per-legend control
The parameter is passed directly to the FancyBboxPatch that draws the legend frame

This approach is consistent with how other legend properties like edgecolor and facecolor work, making it intuitive for users already familiar with matplotlib's legend customization.

Minimum self-contained example:

import matplotlib.pyplot as plt
import matplotlib as mpl
import numpy as np

x = np.linspace(0, 2*np.pi, 100)

fig, axes = plt.subplots(1, 3, figsize=(12, 4))

# Default behavior (inherits axes.linewidth)
axes[0].plot(x, np.sin(x), label='sin(x)')
axes[0].legend()
axes[0].set_title('Default (axes.linewidth=0.8)')

# Set via rcParams
mpl.rcParams['legend.linewidth'] = 3.0
axes[1].plot(x, np.cos(x), label='cos(x)')
axes[1].legend()
axes[1].set_title('Via rcParams (linewidth=3.0)')
mpl.rcParams['legend.linewidth'] = None  # Reset

# Set via parameter
axes[2].plot(x, np.sin(2*x), label='sin(2x)')
axes[2].legend(linewidth=5.0, edgecolor='red')
axes[2].set_title('Via parameter (linewidth=5.0)')

plt.tight_layout()
plt.show()

PR checklist

Closes issue [ENH]: Add rcParams for the width of the legend's box edge #30767
new and changed code is tested
128/131 legend tests pass; 3 image comparison tests have minor visual differences (RMS < 3.0) that may require baseline updates
Plotting related features are demonstrated in an example
This is a styling parameter not a new plotting feature.
New Features and API Changes are noted with a directive and release note
Check doc/api/next_api_changes/development/30767-MS.rst
Documentation complies with general and docstring guidelines

rcomer

Thanks for your work on this @manit2004. As well as my specific comments below, I think this should default to the patch linewidth. As you noted in your summary, that is what is currently used so having it as the default will give us backwards compatibility. I think that will clear up the image test failures.

This should also get a test to verify the behaviour.

doc/release/next_whats_new/legend_line_width.rst

rcomer · 2025-11-23T08:06:02Z

doc/api/next_api_changes/development/30767-MS.rst

+value from ``axes.linewidth``. This allows for independent control of the
+legend frame line width without affecting other elements.
+
+.. versionadded:: 3.10


The versionadded directive is not needed in the release notes. All these files will later be combined to make a single page for the release. Like this

rcomer · 2025-11-23T08:10:43Z

doc/release/next_whats_new/legend_line_width.rst

+
+The `.Legend` constructor also accepts a new *linewidth* parameter to set the
+legend frame line width directly, overriding the rcParam value::
+


Using the plot directive here will mean we get an output image with the example. See here for an example of how that’s done.

rcomer · 2025-11-23T08:15:39Z

lib/matplotlib/legend.py

+    The legend's background patch edge linewidth.
+    If ``None``, use :rc:`axes.linewidth`.
+
+    .. versionadded:: 3.10


Suggested change

.. versionadded:: 3.10

.. versionadded:: 3.11

v3.10 is already released.

rcomer · 2025-11-23T08:33:02Z

lib/matplotlib/mpl-data/matplotlibrc

 #legend.handletextpad: 0.8  # the space between the legend line and legend text
 #legend.borderaxespad: 0.5  # the border between the axes and legend edge
 #legend.columnspacing: 2.0  # column separation
+#legend.linewidth:     None # line width of the legend frame, None means inherit from axes.linewidth


I would move this up with edgecolor, etc. Although it is technically a size, it comes under the same style consideration as color and alpha. Also it is measured in points, not fraction of font size.

rcomer · 2025-11-23T08:35:45Z

lib/matplotlib/rcsetup.py

    # legend properties
    "legend.fancybox": validate_bool,
    "legend.loc": _validate_legend_loc,
+    "legend.linewidth": validate_float_or_None,  # linewidth of legend frame


Move this down with framealpha.

rcomer

Thanks for the quick update @manit2004. Just a couple more minor comments but otherwise this looks great!

doc/release/next_whats_new/legend_line_width.rst

rcomer · 2025-11-23T19:06:33Z

lib/matplotlib/legend.py

+        if linewidth is None:
+            linewidth = mpl.rcParams["patch.linewidth"]


Suggested change

if linewidth is None:

linewidth = mpl.rcParams["patch.linewidth"]

I think we can leave this as None, and the FancyBboxPatch will take care of swapping it for the rcParam.

manit2004 · 2025-11-23T19:14:33Z

@rcomer I have implemented your suggestions and also added a test to verify the feature implemented.

Added test_legend_linewidth() to verify the new parameter's behavior across four scenarios:

Direct parameter usage - Confirms ax.legend(linewidth=2.5) correctly sets the legend frame linewidth
rcParam configuration - Validates legend.linewidth rcParam is properly applied
Default inheritance - Ensures None correctly inherits from patch.linewidth (backward compatibility)
Parameter precedence - Verifies direct parameter overrides rcParam value

manit2004 · 2025-11-23T19:55:51Z

@rcomer I have renamed the .rst file and also removed those two lines as you pointed out. Is there anything else that I should do or is it ready to merge?

rcomer

Thanks @manit2004 this looks good to me. For code changes we require two approving reviews, so now we just need to wait for someone else to take a look.

manit2004 · 2025-11-23T21:16:09Z

Thanks @rcomer for guiding me through one of my first contributions in a big project like matplotlib. Waiting for the reviews.

timhoffm · 2025-11-25T00:03:22Z

lib/matplotlib/mpl-data/matplotlibrc

 #legend.framealpha:    0.8      # legend patch transparency
 #legend.facecolor:     inherit  # inherit from axes.facecolor; or color spec
 #legend.edgecolor:     0.8      # background patch boundary color
+#legend.linewidth:     None     # line width of the legend frame, None means inherit from patch.linewidth


It seems we have a mixture already in that we sometimes use "inherit" and sometimes None. We should do an analysis of the cases and decide which one to use in the future.

I see the point about consistency. I followed the edgecolor pattern which uses "inherit". Happy to adjust based on the team's preferred convention.

Unfortunately, we are inconsistent already.

rcParams using inherit:

legend.facecolor: inherit # inherit from axes.facecolor; or color spec

legend.edgecolor

xtick.labelcolor

ytick.labelcolor

rcParams using None:

grid.major.color: None # If None defaults to grid.color

grid.major.linestyle: None # If None defaults to grid.linestyle

grid.major.linewidth: None # If None defaults to grid.linewidth

grid.major.alpha: None # If None defaults to grid.alpha

grid.minor.color: None # If None defaults to grid.color

grid.minor.linestyle: None # If None defaults to grid.linestyle

grid.minor.linewidth: None # If None defaults to grid.linewidth

grid.minor.alpha: None # If None defaults to grid.alpha

legend.labelcolor: None # None: use text.color

contour.linewidth: None # {float, None} Size of the contour line widths. If set to None, it falls back to line.linewidth.

rcParams using auto

axes.titlecolor: auto # color of the axes title, auto falls back to text.color as default value

savefig.facecolor: auto # figure face color when saving

Summary
"auto" is out. The decision is between None and inherit. There are arguments for both.
I'm ok with sticking with None for now.

Thanks for clarifying. Is there anything needed from my side to move this PR forward being merged?

lib/matplotlib/tests/test_legend.py

…atplotlib#30780) * Added legend.linewidth parameter to control legend box edge linewidth * Added legend.linewidth parameter to control legend box edge linewidth * linting issue and mypy subtest issue fixed * suggestions implemented * tests added * suggestion taken and .rst file renamed * Fix linting error --------- Co-authored-by: Tim Hoffmann <2836374+timhoffm@users.noreply.github.com>

manit2004 added 2 commits November 22, 2025 23:51

Added legend.linewidth parameter to control legend box edge linewidth

8f42926

Added legend.linewidth parameter to control legend box edge linewidth

d92308c

github-actions bot added topic: rcparams topic: legend labels Nov 22, 2025

linting issue and mypy subtest issue fixed

6d4de61

rcomer reviewed Nov 23, 2025

View reviewed changes

rcomer linked an issue Nov 23, 2025 that may be closed by this pull request

[ENH]: Add rcParams for the width of the legend's box edge #30767

Closed

rcomer added this to First Time Contributors Nov 23, 2025

rcomer moved this to Waiting for author in First Time Contributors Nov 23, 2025

manit2004 added 2 commits November 23, 2025 23:43

suggestions implemented

1d7ed10

tests added

c931dc6

rcomer reviewed Nov 23, 2025

View reviewed changes

suggestion taken and .rst file renamed

8541748

rcomer approved these changes Nov 23, 2025

View reviewed changes

rcomer added this to the v3.11.0 milestone Nov 23, 2025

rcomer added the New feature label Nov 23, 2025

timhoffm reviewed Nov 25, 2025

View reviewed changes

github-actions bot added the status: needs rebase label Nov 26, 2025

Merge branch 'main' into main

2dee159

github-actions bot removed the status: needs rebase label Nov 28, 2025

timhoffm reviewed Nov 29, 2025

View reviewed changes

lib/matplotlib/tests/test_legend.py Outdated Show resolved Hide resolved

Fix linting error

6f24f53

timhoffm approved these changes Nov 29, 2025

View reviewed changes

timhoffm merged commit 7bf7e47 into matplotlib:main Nov 29, 2025
39 checks passed

rcomer mentioned this pull request Dec 6, 2025

Add legend.linewidth to rcParam type hint #30813

Merged

5 tasks


		The `.Legend` constructor also accepts a new linewidth parameter to set the
		legend frame line width directly, overriding the rcParam value::

		if linewidth is None:
		linewidth = mpl.rcParams["patch.linewidth"]

Uh oh!

Add legend.linewidth parameter to control legend box edge linewidth #30780

Add legend.linewidth parameter to control legend box edge linewidth #30780

Conversation

manit2004 commented Nov 22, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

PR summary

PR checklist

Uh oh!

rcomer left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

rcomer left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

manit2004 commented Nov 23, 2025

Uh oh!

manit2004 commented Nov 23, 2025

Uh oh!

rcomer left a comment

Choose a reason for hiding this comment

Uh oh!

manit2004 commented Nov 23, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

manit2004 commented Nov 22, 2025 •

edited

Loading

rcomer left a comment •

edited

Loading