diff --git a/Doc/using/cmdline.rst b/Doc/using/cmdline.rst index 677fbbae3f4219a..6d1cd36fcfa902b 100644 --- a/Doc/using/cmdline.rst +++ b/Doc/using/cmdline.rst @@ -163,10 +163,11 @@ source. added to the start of :data:`sys.path` and the ``__main__.py`` file in that location is executed as the :mod:`__main__` module. - :option:`-I` option can be used to run the script in isolated mode where - :data:`sys.path` contains neither the script's directory nor the user's - site-packages directory. All ``PYTHON*`` environment variables are - ignored, too. + :option:`-I` can be used to run the script in isolated mode. For a Python + file, the containing directory is then omitted from :data:`sys.path`, as + is the user's site-packages directory; a directory or zipfile target + remains, as described under :option:`-P`. All ``PYTHON*`` environment + variables are ignored, too. .. audit-event:: cpython.run_file filename @@ -362,6 +363,13 @@ Miscellaneous options * ``python -c code`` and ``python`` (REPL) command lines: Don't prepend an empty string, which means the current working directory. + If the script name refers to a directory or zipfile (see + :ref:`using-on-interface-options`), the script name is still added to the + start of :data:`sys.path`. This also applies when safe-path mode is + enabled by :option:`-I` or :envvar:`PYTHONSAFEPATH`. The entry is used to + locate ``__main__.py`` and makes other modules stored in the target + importable. + See also the :envvar:`PYTHONSAFEPATH` environment variable, and :option:`-E` and :option:`-I` (isolated) options. diff --git a/Misc/NEWS.d/next/Documentation/2026-07-29-12-50-00.gh-issue-131484.Xk2mVq.rst b/Misc/NEWS.d/next/Documentation/2026-07-29-12-50-00.gh-issue-131484.Xk2mVq.rst new file mode 100644 index 000000000000000..d4c76b89110df22 --- /dev/null +++ b/Misc/NEWS.d/next/Documentation/2026-07-29-12-50-00.gh-issue-131484.Xk2mVq.rst @@ -0,0 +1,2 @@ +Clarify that a directory or zipfile passed as the script argument remains on +:data:`sys.path` in safe-path and isolated modes.