gh-72327: Suggest using system terminal for pip install in REPL

Users new to Python packaging often try to use pip from the REPL only to
be met with a confusing SyntaxError. If this happens, guide the user to
use a system terminal instead to invoke pip.

Co-authored-by: Tom Viner <tom@viner.tv>

Author: ichard26

Lib/site.py

@@ -488,9 +488,46 @@ def enablerlcompleter():
     """Enable default readline configuration on interactive prompts, by
     registering a sys.__interactivehook__.
     """
+    # NOTE: This function is only kept for backwards compatibility.
     sys.__interactivehook__ = register_readline
 
 
+def _set_interactive_hook():
+    """Register a sys.__interactivehook__:
+        - Enable default readline configuration on interactive prompts.
+        - Register an excepthook to detect pip usage in the REPL.
+    """
+    def interactivehook():
+        enablerlcompleter()
+        _register_detect_pip_usage_in_repl()
+
+    sys.__interactivehook__ = interactivehook
+
+
+def _register_detect_pip_usage_in_repl():
+    """Register an exception hook that adds a helpful hint to use the
+    system command prompt if pip install is invoked in the REPL, often
+    done by newbies.
+    """
+    old_excepthook = sys.excepthook
+
+    def detect_pip_usage_in_repl(typ, value, traceback):
+        if typ is SyntaxError and (
+            "pip install" in value.text or "pip3 install" in value.text
+        ):
+            value.add_note(
+                "The Python package manager (pip) can only be"
+                " used outside of the Python REPL.\n"
+                "Please try the 'pip' command in a separate terminal"
+                " or command prompt."
+            )
+
+        old_excepthook(typ, value, traceback)
+
+    detect_pip_usage_in_repl.__wrapped__ = old_excepthook
+    sys.excepthook = detect_pip_usage_in_repl
+
+
 def register_readline():
     """Configure readline completion on interactive prompts.
 
@@ -711,7 +748,7 @@ def main():
     setcopyright()
     sethelper()
     if not sys.flags.isolated:
-        enablerlcompleter()
+        _set_interactive_hook()
     execsitecustomize()
     if ENABLE_USER_SITE:
         execusercustomize()

Lib/test/test_site.py

@@ -655,8 +655,8 @@ def test_startup_interactivehook_isolated(self):
     def test_startup_interactivehook_isolated_explicit(self):
         # issue28192 readline can be explicitly enabled in isolated mode
         r = subprocess.Popen([sys.executable, '-I', '-c',
-            'import site, sys; site.enablerlcompleter(); sys.exit(hasattr(sys, "__interactivehook__"))']).wait()
-        self.assertTrue(r, "'__interactivehook__' not added by enablerlcompleter()")
+            'import site, sys; site._set_interactive_hook(); sys.exit(hasattr(sys, "__interactivehook__"))']).wait()
+        self.assertTrue(r, "'__interactivehook__' not added by _set_interactive_hook()")
 
 class _pthFileTests(unittest.TestCase):
 
@@ -803,5 +803,29 @@ def test_underpth_dll_file(self):
         self.assertTrue(rc, "sys.path is incorrect")
 
 
+class DetectPipUsageInReplTests(unittest.TestCase):
+    def setUp(self):
+        self.old_excepthook = sys.excepthook
+        site._register_detect_pip_usage_in_repl()
+
+    def tearDown(self):
+        sys.excepthook = self.old_excepthook
+
+    def test_detect_pip_usage_in_repl(self):
+        for pip_cmd in [
+            'pip install a', 'pip3 install b', 'python -m pip install c'
+        ]:
+            with self.subTest(pip_cmd=pip_cmd):
+                try:
+                    exec(pip_cmd, {}, {})
+                except SyntaxError as exc:
+                    with captured_stderr() as err_out:
+                        sys.excepthook(SyntaxError, exc, exc.__traceback__)
+
+                self.assertIn("The Python package manager (pip) can only be"
+                               " used outside of the Python REPL",
+                               err_out.getvalue())
+
+
 if __name__ == "__main__":
     unittest.main()

Misc/ACKS

@@ -1742,6 +1742,7 @@ Joel Shprentz
 Yue Shuaijie
 Jaysinh Shukla
 Terrel Shumway
+Richard Si
 Eric Siegerman
 Reilly Tucker Siemens
 Paul Sijben
@@ -1986,6 +1987,7 @@ Olivier Vielpeau
 Kannan Vijayan
 Kurt Vile
 Norman Vine
+Tom Viner
 Pauli Virtanen
 Frank Visser
 Long Vo

Misc/NEWS.d/next/Library/2025-07-05-18-02-52.gh-issue-72327.wLvRuj.rst

@@ -0,0 +1,2 @@
+Suggest using the system command prompt when ``pip install`` is typed into
+the REPL. Patch by Tom Viner and Richard Si.