Skip to content

SubFigure hspace=None incorrectly applies default vertical spacing when wspace is specified #32076

Open

Description

@SuYanqi

Bug summary

SubFigure with hspace=None incorrectly applies the default vertical spacing when wspace is specified. This produces an unintended vertical gap between subfigures.

Code for reproduction

import matplotlib
matplotlib.use("Agg")
import matplotlib.pyplot as plt

fig = plt.figure(figsize=(6, 4))
wspace, hspace = 0.2, None
print("Input: wspace=", wspace, "hspace=None")
subfigures = fig.subfigures(nrows=2, ncols=2,
                            wspace=wspace, hspace=hspace)

for row in range(2):
    for column in range(2):
        subfigures[row, column].add_subplot().plot([0, 1], [0, 1])

fig.canvas.draw()
for row in range(2):
    for column in range(2):
        print(f"Subfigure ({row}, {column}) bounds:",
              tuple(round(value, 3)
                    for value in subfigures[row, column].bbox.bounds))
plt.close(fig)

Actual outcome

Input: wspace= 0.2 hspace=None
Subfigure (0, 0) bounds: (np.float64(0.0), np.float64(218.182), np.float64(272.727), np.float64(181.818))
Subfigure (0, 1) bounds: (np.float64(327.273), np.float64(218.182), np.float64(272.727), np.float64(181.818))
Subfigure (1, 0) bounds: (np.float64(0.0), np.float64(0.0), np.float64(272.727), np.float64(181.818))
Subfigure (1, 1) bounds: (np.float64(327.273), np.float64(0.0), np.float64(272.727), np.float64(181.818))

Expected outcome

Input: wspace= 0.2 hspace=None
Subfigure (0, 0) bounds: (0.0, 200.0, 300.0, 200.0)
Subfigure (0, 1) bounds: (300.0, 200.0, 300.0, 200.0)
Subfigure (1, 0) bounds: (0.0, 0.0, 300.0, 200.0)
Subfigure (1, 1) bounds: (300.0, 0.0, 300.0, 200.0)

When no layout engine is active, hspace=None should result in no vertical spacing, while the requested wspace=0.2 should be applied.

Additional information

This is a regression introduced by PR #25960.

The example uses only public Matplotlib APIs and legal inputs, and its output is deterministic. The horizontal spacing is applied as requested, but hspace=None produces a vertical gap: the subfigure heights are 181.818 pixels with a 36.364-pixel gap. According to the updated documentation and the intent of PR #25960, unspecified spacing should be zero when no layout engine is active.

Passing hspace=None through GridSpec appears to fall back to the figure's default subplot hspace, causing unintended vertical spacing when only wspace is specified. The analogous issue may occur when only hspace is specified.

Operating system

Linux

Matplotlib Version

3.11.1

Matplotlib Backend

agg

Python version

3.11.13

Jupyter version

N/A

Installation

N/A

Activity

  1. rcomer commented on Jul 20, 2026

    @rcomer
    Member

    I note the user can easily work around this by explicitly passing hspace=0. If both wspace and hspace are None, the behaviour is as documented.

    So the easiest "fix" would be to document that if you pass one of these you have to pass both.

  2. mohit-sharma-001 commented on Jul 29, 2026

    @mohit-sharma-001

    @SuYanqi @melissawm is this issue still open if yes I would like to take it

  3. melissawm commented on Jul 29, 2026

    @melissawm
    Member

    HI @mohit-sharma-001 - you can see there is already a linked PR for this issue. Feel free to look for other issues where there are no PRs linked. We don't assign issues, so if you are interested in contributing please read our Contributing guide and send in your PR. Thanks!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions