[3.14] gh-76303: Improve documentation of the -x command line option (GH-155559) (GH-155566)

miss-islington · serhiy-storchaka · RoryGlenn · web-flow · commit f3648f48df41 · 2026-08-11T15:53:04.000Z
Expand the documentation for the -x command-line option to explain its purpose and usage for turning Python scripts into Windows batch files, with examples of batch file header lines. (cherry picked from commit 4b04d5a) Co-authored-by: Serhiy Storchaka <storchaka@gmail.com> Co-authored-by: Rory Glenn <glennrory@gmail.com> Co-authored-by: Brian Schubert <brianm.schubert@gmail.com>
diff --git a/Doc/using/cmdline.rst b/Doc/using/cmdline.rst
@@ -501,7 +501,25 @@ Miscellaneous options
 .. option:: -x
 
    Skip the first line of the source, allowing use of non-Unix forms of
-   ``#!cmd``.  This is intended for a DOS specific hack only.
+   ``#!cmd``.
+
+   This can be used to turn a Python script into a Windows batch file.
+   Similarly to adding a shebang line and setting the executable bit on Unix,
+   the extension of the Python script can be changed to ``.bat`` and the
+   following line can be added at the start of the script:
+
+   .. code-block:: batch
+
+      @py -x "%~f0" %* & exit /b
+
+   Or, to specify the path to the Python interpreter explicitly:
+
+   .. code-block:: batch
+
+      @"C:\Path\to\python.exe" -x "%~f0" %* & exit /b
+
+   Unlike a shebang line which is a Python comment, this line is not valid
+   Python syntax, and the :option:`-x` option is needed to skip it.
 
 
 .. option:: -X
