Text of peps.python.org › pep-0722 as Styx crawled it on Oct 13, 2026. The page may have changed since. Only its words are kept, without pictures or layout, and only the first part of a long page.

Open the live page

PEP 722 – Dependency specification for single-file scripts | peps.python.org

PEP 722 – Dependency specification for single-file scripts PEP 722 – Dependency specification for single-file scripts Author : Paul Moore <p.f.moore at gmail.com> PEP-Delegate : Brett Cannon <brett at python.org> Discussions-To : Discourse thread Status : Rejected Type : Standards Track Topic : Packaging Created : 19-Jul-2023 Post-History : 19-Jul-2023 Superseded-By : 723 Resolution : 21-Oct-2023 Table of Contents Abstract Motivation Rationale Specification Example Backwards Compatibility Security Implications How to Teach This Recommendations Reference Implementation Rejected Ideas Why not include other metadata?

Why not use a marker per line? Why not use a distinct form of comment for the dependency block? Why not allow multiple dependency blocks and merge them? Why not use a more standard data format (e.g., TOML)? Why not use (possibly restricted) Python syntax? Why not embed a pyproject.toml file in the script? Why not infer the requirements from import statements? Why not simply manage the environment at runtime? Why not just set up a Python project with a pyproject.toml ?

Why not use a requirements file for dependencies? Should scripts be able to specify a package index? What about local dependencies? Open Issues Copyright Warning This PEP was rejected in favour of PEP 723 . × Abstract This PEP specifies a format for including 3rd-party dependencies in a single-file Python script. Motivation Not all Python code is structured as a “project”, in the sense of having its own directory complete with a pyproject.toml file, and being built into an installable distribution package.

Python is also routinely used as a scripting language, with Python scripts as a (better) alternative to shell scripts, batch files, etc. When used to create scripts, Python code is typically stored as a single file, often in a directory dedicated to such “utility scripts”, which might be in a mix of languages with Python being only one possibility among many. Such scripts may be shared, often by something as simple as email, or a link to a URL such as a Github gist.

But they are typically not “distributed” or “installed” as part of a normal workflow. One problem when using Python as a scripting language in this way is how to run the script in an environment that contains whatever third party dependencies are required by the script. There is currently no standard tool that addresses this issue, and this PEP does not attempt to define one. However, any tool that does address this issue will need to know what 3rd party dependencies a script requires.

By defining a standard format for storing such data, existing tools, as well as any future tools, will be able to obtain that information without requiring users to include tool-specific metadata in their scripts. Rationale Because a key requirement is writing single-file scripts, and simple sharing by giving someone a copy of the script, the PEP defines a mechanism for embedding dependency data within the script itself , and not in an external file.

We define the concept of a dependency block that contains information about what 3rd party packages a script depends on. In order to identify dependency blocks, the script can simply be read as a text file. This is deliberate, as Python syntax changes over time, so attempting to parse the script as Python code would require choosing a specific version of Python syntax. Also, it is likely that at least some tools will not be written in Python, and expecting them to implement a Python parser is too much of a burden.

However, to avoid needing changes to core Python, the format is designed to appear as comments to the Python parser. It is possible to write code where a dependency block is not interpreted as a comment (for example, by embedding it in a Python multi-line string), but such uses are discouraged and can easily be avoided assuming you are not deliberately trying to create a pathological example. A review of how other languages allow scripts to specify their dependencies shows that a “structured comment” like this is a commonly-used approach.

Specification The content of this section will be published in the Python Packaging user guide, PyPA Specifications section, as a document with the title “Embedding Metadata in Script Files”. Any Python script may contain a dependency block . The dependency block is identified by reading the script as a text file (i.e., the file is not parsed as Python source code), looking for the first line of the form: # Script Dependencies: The hash character must be at the start of the line with no preceding whitespace.

The text “Script Dependencies” is recognised regardless of case, and the spaces represent arbitrary whitespace (although at least one space must be present). The following regular expression recognises the dependency block header line: (?i)^#\s+script\s+dependencies:\s*$ Tools reading the dependency block MAY respect the standard Python encoding declaration. If they choose not to do so, they MUST process the file as UTF-8.

After the header line, all lines in the file up to the first line that doesn’t start with a # sign are considered dependency lines and are treated as follows: The initial # sign is stripped. If the line contains the character sequence “ # “ (SPACE HASH SPACE), then those characters and any subsequent characters are discarded. This allows dependency blocks to contain inline comments. Whitespace at the start and end of the remaining text is discarded.

If the line is now empty, it is ignored. The content of the line MUST now be a valid PEP 508 dependency specifier. The requirement for spaces before and after the # in an inline comment is necessary to distinguish them from part of a PEP 508 URL specifier (which can contain a hash, but without surrounding whitespace). Consumers MUST validate that at a minimum, all dependencies start with a name as defined in PEP 508 , and they MAY validate that all dependencies conform fully to PEP 508 .

They MUST fail with an error if they find an invalid specifier. Example The following is an example of a script with an embedded dependency block: # In order to run, this script needs the following 3rd party libraries # # Script Dependencies: # requests # rich # Needed for the output # # # Not needed - just to show that fragments in URLs do not # # get treated as comments # pip @ https://github.com/pypa/pip/archive/1.3.1.zip#sha1=da9234ee9982d4bbb3c72346a6de940a148ea686 import requests from rich.pretty import pprint resp = requests . get ( "https://peps.python.org/api/peps.json" ) data = resp . json () pprint ([( k , v [ "title" ]) for k , v in data . items ()][: 10 ]) Backwards Compatibility As dependency blocks take the form of a structured comment, they can be added without altering the meaning of existing code.

It is possible that a comment may already exist which matches the form of a dependency block. While the identifying header text, “Script Dependencies” is chosen to minimise this risk, it is still possible. In the rare case where an existing comment would be interpreted incorrectly as a dependency block, this can be addressed by adding an actual dependency block (which can be empty if the script has no dependencies) earlier in the code.

Security Implications If a script containing a dependency block is run using a tool that automatically installs dependencies, this could cause arbitrary code to be downloaded and installed in the user’s environment. The risk here is part of the functionality of the tool being used to run the script, and as such should already be addressed by the tool itself. The only additional risk introduced by this PEP is if an untrusted script with a dependency block is run, when a potentially malicious dependency might be installed.

This risk is addressed by the normal good practice of reviewing code before running it. How to Teach This The format is intended to be close to how a developer might already specify sc

The rest of this page is on the live site.