This is all expected. The suptitle is in all cases positionned in the horizontal center of the figure. horizontalalignment aligns the text relative to this center position, i.e. if for horizontalalignment=left, the left end of the text is at the center position, for horizontalalignment=right the right end of the text is at the center.

The suptitle does not have a loc parameter. In order to position a suptitle you may however use the x and y arguments. The position is in figure coordinates. So if you want to have a suptitle aligned with the (only) subplot in a figure you may set its position according to the subplot paramters, e.g. the left parameter (fig.subplotpars.left) is 0.125. You will still need to set the aligment as well.

fig = plt.figure(figsize=(9,4))
ax = fig.add_subplot(111)
fig.suptitle('This figure suptitle should be on the left', 
             horizontalalignment = 'left', x=fig.subplotpars.left) # x=0.125
ax.set_title('This axis title should be on the left', loc='left');

# Right alignment test, short title
fig = plt.figure(figsize=(9,4))
ax = fig.add_subplot(111)
fig.suptitle('This figure suptitle should be on the right', 
             horizontalalignment = 'right', x=fig.subplotpars.right) # x=0.9
ax.set_title('This axis title should be on the right', loc='right');

# Right alignment test, longer title
fig = plt.figure(figsize=(9,4))
ax = fig.add_subplot(111)
fig.suptitle('This figure suptitle should be on the right and it actually is.', 
             horizontalalignment = 'right', x=fig.subplotpars.right) # x=0.9
ax.set_title('This axis title should be on the left', loc='left')

plt.show()

I will close this because I don't think there is anything wrong with the library here. Feel free to reopen in case you disagree.

Thank you for your answer!

Do you agree this should be documented?

subtitle documents

x : float, default 0.5 The x location of the text in figure coordinates.
y : float, default 0.98 The y location of the text in figure coordinates.
**kwargs: Additional kwargs are matplotlib.text.Text properties.

matplotlib.text.Text documents

horizontalalignment: {'center', 'right', 'left'}

There is the Text alignment example which shows the different alignments.

At which point exactly do you think the documentation should be extended? We're always open to improvements of the docs, so feel free to make a suggestion here.

suptitle could be more precise in documenting horizontalalignment and verticalalignment e.g.

The horizontal alignment of the text relative to (*x*, *y*).

Feel free to open a PR.

Since horizontalalignment isn't really an argument of suptitle but part of the kwargs, which are passed on to Text, do you feel one should make an exception here and document this kwarg explicitely?

I would have though maybe documenting Text's horizontalalignment in a bit more than half a sentence could make sense?

(reopening this to let the discussion evolve)

It's already documented separately, because the defaults are different from Text.
https://matplotlib.org/api/_as_gen/matplotlib.figure.Figure.html#matplotlib.figure.Figure.suptitle

True, I must have looked at a completely different page, despite linking the correct one. 😳

@gansanay Is the above proposal by @timhoffm

The horizontal alignment of the text relative to (x, y).

how you imagine this to be clearified? Would you like to change it yourself?

Should I also need to generate any file? Thanks.