matplotlib._constrained_layout

Adjust subplot layouts so that there are no overlapping axes or axes decorations. All axes decorations are dealt with (labels, ticks, titles, ticklabels) and some dependent artists are also dealt with (colorbar, suptitle).

Layout is done via ~matplotlib.gridspec, with one constraint per gridspec, so it is possible to have overlapping axes if the gridspecs overlap (i.e. using ~matplotlib.gridspec.GridSpecFromSubplotSpec). Axes placed using figure.subplots() or figure.add_subplots() will participate in the layout. Axes manually placed via figure.add_axes() will not.

See Tutorial: /tutorials/intermediate/constrainedlayout_guide

General idea:

First, a figure has a gridspec that divides the figure into nrows and ncols, with heights and widths set by height_ratios and width_ratios, often just set to 1 for an equal grid.

Subplotspecs that are derived from this gridspec can contain either a SubPanel, a GridSpecFromSubplotSpec, or an Axes. The SubPanel and GridSpecFromSubplotSpec are dealt with recursively and each contain an analogous layout.

Each GridSpec has a _layoutgrid attached to it. The _layoutgrid has the same logical layout as the GridSpec. Each row of the grid spec has a top and bottom “margin” and each column has a left and right “margin”. The “inner” height of each row is constrained to be the same (or as modified by height_ratio), and the “inner” width of each column is constrained to be the same (as modified by width_ratio), where “inner” is the width or height of each column/row minus the size of the margins.

Then the size of the margins for each row and column are determined as the max width of the decorators on each axes that has decorators in that margin. For instance, a normal axes would have a left margin that includes the left ticklabels, and the ylabel if it exists. The right margin may include a colorbar, the bottom margin the xaxis decorations, and the top margin the title.

With these constraints, the solver then finds appropriate bounds for the columns and rows. It’s possible that the margins take up the whole figure, in which case the algorithm is not applied and a warning is raised.

See the tutorial doc:/tutorials/intermediate/constrainedlayout_guide for more discussion of the algorithm with examples.