Description
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
rcomer commentedon Jul 20, 2026
I note the user can easily work around this by explicitly passing
hspace=0. If both wspace and hspace areNone, 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.
mohit-sharma-001 commentedon Jul 29, 2026
@SuYanqi @melissawm is this issue still open if yes I would like to take it
melissawm commentedon Jul 29, 2026
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!