docs: Improve --user/--no-user documentation (#12924)

Author: Ashutosh0x

docs/html/user_guide.rst

@@ -897,6 +897,92 @@ To install "SomePackage" into an environment with ``site.USER_BASE`` customized
       set PYTHONUSERBASE=c:/myappenv
       py -m pip install --user SomePackage
 
+Automatic User Install Fallback
+-------------------------------
+
+.. important::
+
+   When pip detects that the normal ``site-packages`` directory is not
+   writeable (e.g., when running as a non-root user on a system Python),
+   it will **automatically default to a user installation** without requiring
+   the ``--user`` flag. You will see this message:
+
+   .. code-block:: text
+
+      Defaulting to user installation because normal site-packages is not writeable
+
+   This automatic fallback can be surprising, especially if the warning is
+   missed among other output. If you explicitly want to prevent this behavior
+   and instead receive an error when ``site-packages`` is not writeable, use
+   the ``--no-user`` option.
+
+The ``--no-user`` Option
+------------------------
+
+The ``--no-user`` option explicitly disables user installs, ensuring that pip
+will attempt to install to the system ``site-packages`` directory. If pip
+cannot write to ``site-packages``, it will fail with a permission error rather
+than silently falling back to a user install.
+
+.. tab:: Unix/macOS
+
+   .. code-block:: shell
+
+      python -m pip install --no-user SomePackage
+
+.. tab:: Windows
+
+   .. code-block:: shell
+
+      py -m pip install --no-user SomePackage
+
+This is useful in scenarios where:
+
+- You want to ensure packages are installed globally and not in user space.
+- You want pip to fail loudly if it doesn't have the necessary permissions,
+  rather than silently succeeding with a user install.
+- You are debugging installation issues and want to understand exactly where
+  packages are being installed.
+
+Environment Variables
+---------------------
+
+The user install behavior can also be controlled via environment variables:
+
+``PIP_USER``
+   Set to ``1``, ``true``, or ``yes`` to enable user installs by default
+   (equivalent to ``--user``). Set to ``0``, ``false``, or ``no`` to disable
+   the automatic user install fallback (equivalent to ``--no-user``).
+
+   .. tab:: Unix/macOS
+
+      .. code-block:: shell
+
+         # Always use user installs
+         export PIP_USER=1
+         python -m pip install SomePackage
+
+         # Never fall back to user installs
+         export PIP_USER=0
+         python -m pip install SomePackage
+
+   .. tab:: Windows
+
+      .. code-block:: shell
+
+         :: Always use user installs
+         set PIP_USER=1
+         py -m pip install SomePackage
+
+         :: Never fall back to user installs
+         set PIP_USER=0
+         py -m pip install SomePackage
+
+``PYTHONUSERBASE``
+   Customizes the user install location by changing the value of
+   ``site.USER_BASE``.
+
+
 ``pip install --user`` follows four rules:
 
 #. When globally installed packages are on the python path, and they *conflict*

news/12924.doc.rst

@@ -0,0 +1,6 @@
+Improved documentation for the ``--user`` and ``--no-user`` options, including:
+
+- Documented the automatic user installation fallback behavior that occurs when site-packages is not writeable.
+- Made the ``--no-user`` option visible in help output (previously hidden).
+- Documented the ``PIP_USER`` environment variable for controlling user install behavior.
+- Added examples and use cases for when to use ``--no-user``.

src/pip/_internal/commands/install.py

@@ -135,8 +135,13 @@ def add_options(self) -> None:
             "--no-user",
             dest="use_user_site",
             action="store_false",
-            help=SUPPRESS_HELP,
+            help=(
+                "Disable user site-packages install. If site-packages is not "
+                "writeable, pip will fail with a permission error rather than "
+                "falling back to a user install."
+            ),
         )
+
         self.cmd_opts.add_option(
             "--root",
             dest="root_path",