script type

The first type of metadata block is namedscript which contains scriptmetadata (dependency data and tool configuration).

This document MAY include top-level fieldsdependencies andrequires-python,and MAY optionally include a[tool] table.

The[tool] table MAY be used by any tool, script runner or otherwise, to configurebehavior. It has the same semantics as thetool table inpyproject.toml.

The top-level fields are:

• dependencies: A list of strings that specifies the runtime dependenciesof the script. Each entry MUST be a validPEP 508 dependency.
• requires-python: A string that specifies the Python version(s) with whichthe script is compatible. The value of this field MUST be a validversion specifier.

Script runners MUST error if the specifieddependencies cannot be provided.Script runners SHOULD error if no version of Python that satisfies the specifiedrequires-python can be provided.

Example

The following is an example of a script with embedded metadata:

# /// script# requires-python = ">=3.11"# dependencies = [#   "requests<3",#   "rich",# ]# ///importrequestsfromrich.prettyimportpprintresp=requests.get("https://peps.python.org/api/peps.json")data=resp.json()pprint([(k,v["title"])fork,vindata.items()][:10])

Why not use a comment block resembling requirements.txt?

This PEP considers there to be different types of users for whom Python codewould live as single-file scripts:

• Non-programmers who are just using Python as a scripting language to achievea specific task. These users are unlikely to be familiar with concepts ofoperating systems like shebang lines or thePATH environment variable.Some examples:
  • The average person, perhaps at a workplace, who wants to write a script toautomate something for efficiency or to reduce tedium
  • Someone doing data science or machine learning in industry or academia whowants to write a script to analyze some data or for research purposes.These users are special in that, although they have limited programmingknowledge, they learn from sources like StackOverflow and blogs that have aprogramming bent and are increasingly likely to be part of communities thatshare knowledge and code. Therefore, a non-trivial number of these userswill have some familiarity with things like Git(Hub), Jupyter, HuggingFace,etc.
• Non-programmers who manage operating systems e.g. a sysadmin. These users areable to set upPATH, for example, but are unlikely to be familiar withPython concepts like virtual environments. These users often operate inisolation and have limited need to gain exposure to tools intended forsharing like Git.
• Programmers who manage operating systems/infrastructure e.g. SREs. Theseusers are not very likely to be familiar with Python concepts like virtualenvironments, but are likely to be familiar with Git and most often use itto version control everything required to manage infrastructure like Pythonscripts and Kubernetes config.
• Programmers who write scripts primarily for themselves. These users over timeaccumulate a great number of scripts in various languages that they use toautomate their workflow and often store them in a single directory, that ispotentially version controlled for persistence. Non-Windows users may setup each Python script with a shebang line pointing to the desired Pythonexecutable or script runner.

This PEP argues that the proposed TOML-based metadata format is the best foreach category of user and that the requirements-like block comment is onlyapproachable for those who have familiarity withrequirements.txt, whichrepresents a small subset of users.

• For the average person automating a task or the data scientist, they arealready starting with zero context and are unlikely to be familiar withTOML norrequirements.txt. These users will very likely rely onsnippets found online via a search engine or utilize AI in the formof a chat bot or direct code completion software. The similarity withdependency information stored inpyproject.toml will provide usefulsearch results relatively quickly, and while thepyproject.toml formatand the script metadata format are not the same, any resulting discrepanciesare unlikely to be difficult for the intended users to resolve.

  Additionally, these users are most susceptible to formatting quirks andsyntax errors. TOML is a well-defined format with existing onlinevalidators that features assignment that is compatible with Pythonexpressions and has no strict indenting rules. The block comment formaton the other hand could be easily malformed by forgetting the colon, forexample, and debugging why it’s not working with a search engine would bea difficult task for such a user.

• For the sysadmin types, they are equally unlikely as the previously describedusers to be familiar with TOML orrequirements.txt. For either formatthey would have to read documentation. They would likely be more comfortablewith TOML since they are used to structured data formats and there would beless perceived magic in their systems.

  Additionally, for maintenance of their systems///script would bemuch easier to search for from a shell than a block comment with potentiallynumerous extensions over time.

• For the SRE types, they are likely to be familiar with TOML already fromother projects that they might have to work with like configuring theGitLab Runner orCloud Native Buildpacks.

  These users are responsible for the security of their systems and most likelyhave security scanners set up to automatically open PRs to update versionsof dependencies. Such automated tools like Dependabot would have a mucheasier time using existing TOML libraries than writing their own customparser for a block comment format.

• For the programmer types, they are more likely to be familiar with TOMLthan they have ever seen arequirements.txt file, unless they are aPython programmer who has had previous experience with writing applications.In the case of experience with the requirements format, it necessarily meansthat they are at least somewhat familiar with the ecosystem and thereforeit is safe to assume they know what TOML is.

  Another benefit of this PEP to these users is that their IDEs like VisualStudio Code would be able to provide TOML syntax highlighting much moreeasily than each writing custom logic for this feature.

Additionally, since the original block comment alternative format (double#) went against the recommendation ofPEP 8 and as a result lintersand IDE auto-formatters that respected the recommendation wouldfail by default, the finalproposal uses standard comments starting with a single# character withoutany obvious start nor end sequence.

The concept of regular comments that do not appear to be intended for machines(i.e.encoding declarations) affecting behavior would not be customary tousers of Python and goes directly against the “explicit is better thanimplicit” foundational principle.

Users typing what to them looks like prose could alter runtime behavior. ThisPEP takes the view that the possibility of that happening, even when a toolhas been set up as such (maybe by a sysadmin), is unfriendly to users.

Finally, and critically, the alternatives to this PEP likePEP 722 do notsatisfy the use cases enumerated herein, such as setting the supported Pythonversions, the eventual building of scripts into packages, and the ability tohave machines edit metadata on behalf of users. It is very likely that therequests for such features persist and conceivable that another PEP in thefuture would allow for the embedding of such metadata. At that point therewould be multiple ways to achieve the same thing which goes against ourfoundational principle of “there should be one - and preferably only one -obvious way to do it”.

Why not use a multi-line string?

A previous version of this PEP proposed that the metadata be stored as follows:

__pyproject__="""..."""

The most significant problem with this proposal is that the embedded TOML wouldbe limited in the following ways:

• It would not be possible to use multi-line double-quoted strings in the TOMLas that would conflict with the Python string containing the document. ManyTOML writers do not preserve style and may potentially produce output thatwould be malformed.
• The way in which character escaping works in Python strings is not quite theway it works in TOML strings. It would be possible to preserve a one-to-onecharacter mapping by enforcing raw strings, but thisr prefix requirementmay be potentially confusing to users.

Why not reuse core metadata fields?

A previous version of this PEP proposed to reuse the existingmetadata standard that is used to describe projects.

There are two significant problems with this proposal:

• Thename andversion fields are required and changing that wouldrequire its own PEP
• Reusing the data isfundamentally a misuse of it

Why not limit to specific metadata fields?

By limiting the metadata to justdependencies, we would prevent the knownuse case of tools that support managing Python installations, which wouldallows users to target specific versions of Python for new syntax or standardlibrary functionality.

Why not limit tool configuration?

By not allowing the[tool] table, we would prevent known functionalitythat would benefit users. For example:

• A script runner may support injecting of dependency resolution data for anembedded lock file (this is what Go’sgorun can do).
• A script runner may support configuration instructing to run scripts incontainers for situations in which there is no cross-platform support for adependency or if the setup is too complex for the average user like whenrequiring Nvidia drivers. Situations like this would allow users to proceedwith what they want to do whereas otherwise they may stop at that pointaltogether.
• Tools may wish to experiment with features to ease development burden forusers such as the building of single-file scripts into packages. We receivedfeedback stating that there arealready tools that exist in the wild that build wheels and sourcedistributions from single files.

  The author of the Rust RFC for embedding metadatamentioned to us that they areactively looking into that as well based on user feedback saying that thereis unnecessary friction with managing small projects.

  There has beena commitment tosupport this by at least one major build system.

Why not limit tool behavior?

A previous version of this PEP proposed that non-script running tools SHOULDNOT modify their behavior when the script is not the sole input to the tool.For example, if a linter is invoked with the path to a directory, it SHOULDbehave the same as if zero files had embedded metadata.

This was done as a precaution to avoid tool behavior confusion and generatingvarious feature requests for tools to support this PEP. However, duringdiscussion we receivedfeedbackfrom maintainers of tools that this would be undesirable and potentiallyconfusing to users. Additionally, this may allow for a universally easierway to configure tools in certain circumstances and solve existing issues.

Why not just set up a Python project with apyproject.toml?

Again, a key issue here is that the target audience for this proposal is peoplewriting scripts which aren’t intended for distribution. Sometimes scripts willbe “shared”, but this is far more informal than “distribution” - it typicallyinvolves sending a script via an email with some written instructions on how torun it, or passing someone a link to a GitHub gist.

Expecting such users to learn the complexities of Python packaging is asignificant step up in complexity, and would almost certainly give theimpression that “Python is too hard for scripts”.

In addition, if the expectation here is that thepyproject.toml willsomehow be designed for running scripts in place, that’s a new feature of thestandard that doesn’t currently exist. At a minimum, this isn’t a reasonablesuggestion until thecurrent discussion on Discourse about usingpyproject.toml for projects thatwon’t be distributed as wheels is resolved. And even then, it doesn’t addressthe “sending someone a script in a gist or email” use case.

Why not infer the requirements from import statements?

The idea would be to automatically recognizeimport statements in the sourcefile and turn them into a list of requirements.

However, this is infeasible for several reasons. First, the points above aboutthe necessity to keep the syntax easily parsable, for all Python versions, alsoby tools written in other languages, apply equally here.

Second, PyPI and other package repositories conforming to the Simple RepositoryAPI do not provide a mechanism to resolve package names from the module namesthat are imported (see alsothis related discussion).

Third, even if repositories did offer this information, the same import name maycorrespond to several packages on PyPI. One might object that disambiguatingwhich package is wanted would only be needed if there are several projectsproviding the same import name. However, this would make it easy for anyone tounintentionally or malevolently break working scripts, by uploading a package toPyPI providing an import name that is the same as an existing project. Thealternative where, among the candidates, the first package to have beenregistered on the index is chosen, would be confusing in case a popular packageis developed with the same import name as an existing obscure package, and evenharmful if the existing package is malware intentionally uploaded with asufficiently generic import name that has a high probability of being reused.

A related idea would be to attach the requirements as comments to the importstatements instead of gathering them in a block, with a syntax such as:

importnumpyasnp# requires: numpyimportrich# requires: rich

This still suffers from parsing difficulties. Also, where to place the commentin the case of multiline imports is ambiguous and may look ugly:

fromPyQt5.QtWidgetsimport(QCheckBox,QComboBox,QDialog,QDialogButtonBox,QGridLayout,QLabel,QSpinBox,QTextEdit)# requires: PyQt5

Furthermore, this syntax cannot behave as might be intuitively expectedin all situations. Consider:

importplatformifplatform.system()=="Windows":importpywin32# requires: pywin32

Here, the user’s intent is that the package is only required on Windows, butthis cannot be understood by the script runner (the correct way to writeit would berequires:pywin32;sys_platform=='win32').

(Thanks to Jean Abou-Samra for the clear discussion of this point)

Why not use a requirements file for dependencies?

Putting your requirements in a requirements file, doesn’t require a PEP. Youcan do that right now, and in fact it’s quite likely that many adhoc solutionsdo this. However, without a standard, there’s no way of knowing how to locate ascript’s dependency data. And furthermore, the requirements file format ispip-specific, so tools relying on it are depending on a pip implementationdetail.

So in order to make a standard, two things would be required:

1. A standardised replacement for the requirements file format.
2. A standard for how to locate the requirements file for a given script.

The first item is a significant undertaking. It has been discussed on a numberof occasions, but so far no-one has attempted to actually do it. The mostlikely approach would be for standards to be developed for individual use casescurrently addressed with requirements files. One option here would be for thisPEP to simply define a new file format which is simply a text file containingPEP 508 requirements, one per line. That would just leave the question ofhow to locate that file.

The “obvious” solution here would be to do something like name the file thesame as the script, but with a.reqs extension (or something similar).However, this still requirestwo files, where currently only a single file isneeded, and as such, does not match the “better batch file” model (shellscripts and batch files are typically self-contained). It requires thedeveloper to remember to keep the two files together, and this may not alwaysbe possible. For example, system administration policies may require thatallfiles in a certain directory are executable (the Linux filesystem standardsrequire this of/usr/bin, for example). And some methods of sharing ascript (for example, publishing it on a text file sharing service like Github’sgist, or a corporate intranet) may not allow for deriving the location of anassociated requirements file from the script’s location (tools likepipxsupport running a script directly from a URL, so “download and unpack a zip ofthe script and its dependencies” may not be an appropriate requirement).

Essentially, though, the issue here is that there is an explicitly statedrequirement that the format supports storing dependency datain the scriptfile itself. Solutions that don’t do that are simply ignoring thatrequirement.

Why not use (possibly restricted) Python syntax?

This would typically involve storing metadata as multiple special variables,such as the following.

__requires_python__=">=3.11"__dependencies__=["requests","click",]

The most significant problem with this proposal is that it requires allconsumers of the dependency data to implement a Python parser. Even if thesyntax is restricted, therest of the script will use the full Python syntax,and trying to define a syntax which can be successfully parsed in isolationfrom the surrounding code is likely to be extremely difficult and error-prone.

Furthermore, Python’s syntax changes in every release. If extracting dependencydata needs a Python parser, the parser will need to know which version ofPython the script is written for, and the overhead for a generic tool of havinga parser that can handlemultiple versions of Python is unsustainable.

With this approach there is the potential to clutter scripts with manyvariables as new extensions get added. Additionally, intuiting which metadatafields correspond to which variable names would cause confusion for users.

It is worth noting, though, that thepip-run utility does implement (anextended form of) this approach.Further discussion ofthepip-run design is available on the project’s issue tracker.

What about local dependencies?

These can be handled without needing special metadata and tooling, simply byadding the location of the dependencies tosys.path. This PEP simply isn’tneeded for this case. If, on the other hand, the “local dependencies” areactual distributions which are published locally, they can be specified asusual with aPEP 508 requirement, and the local package index specified whenrunning a tool by using the tool’s UI for that.