From 486efeea46824c8dbee7f9b069a567351f2c006d Mon Sep 17 00:00:00 2001
From: Ruth Comer <10599679+rcomer@users.noreply.github.com>
Date: Mon, 16 Mar 2026 13:13:56 +0000
Subject: [PATCH] DOC: setting active axes position is ineffective

---
 lib/matplotlib/axes/_base.py | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/lib/matplotlib/axes/_base.py b/lib/matplotlib/axes/_base.py
index db85c1eea7fe..5af3b0adcc2d 100644
--- 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