DOC: setting active axes position is ineffective

rcomer · rcomer · commit 486efeea4682 · 2026-03-29T19:25:55.000+01:00
diff --git a/lib/matplotlib/axes/_base.py b/lib/matplotlib/axes/_base.py
@@ -1175,6 +1175,15 @@ def set_position(self, pos, which='both'):
         which : {'both', 'active', 'original'}, default: 'both'
             Determines which position variables to change.
 
+            .. note::
+                This parameter is considered internal. End users should not use it.
+
+                For native Matplotlib `.Axes`, the active position is
+                determined by a combination of the original position and the
+                aspect ratio.  Any active position set by the user will therefore be
+                overwritten by internal handling.  This option is retained as it may be
+                relevant for some third party `.Axes` subclasses.
+
         See Also
         --------
         matplotlib.transforms.Bbox.from_bounds
