Merge pull request #11775 from pelson/doc/prefix-warning

Document the limitations of the pip install --prefix argument

Author: sbidoul

news/11775.doc.rst

@@ -0,0 +1,2 @@
+Cross-reference the ``--python`` flag from the ``--prefix`` flag,
+and mention limitations of ``--prefix`` regarding script installation.

src/pip/_internal/commands/install.py

@@ -156,7 +156,12 @@ def add_options(self) -> None:
             default=None,
             help=(
                 "Installation prefix where lib, bin and other top-level "
-                "folders are placed"
+                "folders are placed. Note that the resulting installation may "
+                "contain scripts and other resources which reference the "
+                "Python interpreter of pip, and not that of ``--prefix``. "
+                "See also the ``--python`` option if the intention is to "
+                "install packages into another (possibly pip-free) "
+                "environment."
             ),
         )