Skip to content

gh-76303: Improve -x option documentation#144857

Open
RoryGlenn wants to merge 3 commits intopython:mainfrom
RoryGlenn:gh-76303-improve-x-option-docs
Open

gh-76303: Improve -x option documentation#144857
RoryGlenn wants to merge 3 commits intopython:mainfrom
RoryGlenn:gh-76303-improve-x-option-docs

Conversation

@RoryGlenn
Copy link

@RoryGlenn RoryGlenn commented Feb 16, 2026

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.

The current documentation is a single line:

Skip the first line of the source, allowing use of non-Unix forms of #!cmd. This is intended for a DOS specific hack only.

This gives virtually no information about why the option exists or how to use it. As noted by @serhiy-storchaka in the issue, the purpose of -x is to allow turning Python scripts into Windows batch files (similar to how shebang lines work on Unix).

The expanded documentation now includes:

  • A clear explanation of the use case (Windows batch files)
  • Two practical examples of batch file header lines
  • An explanation of why -x is needed (the header line is not valid Python syntax)

📚 Documentation preview 📚: https://cpython-previews--144857.org.readthedocs.build/

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.

Closes python#76303.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

News entries are not needed for docs changes - this can be deleted. See Changes that require NEWS entries for more on what changes do/do not require a new entry

RoryGlenn and others added 2 commits February 16, 2026 15:24
Co-authored-by: Brian Schubert <brianm.schubert@gmail.com>
Co-authored-by: Brian Schubert <brianm.schubert@gmail.com>
Comment on lines +529 to +537
.. 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
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fix trailing whitespace lints (my bad!)

Suggested change
.. 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
.. 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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

awaiting review docs Documentation in the Doc dir skip news

Projects

Status: Todo

Development

Successfully merging this pull request may close these issues.

2 participants