导航|地址|刷新
Inline script metadata - Python Packagin…
ContentsMenuExpandLight modeDark modeAuto light/dark, in light modeAuto light/dark, in dark mode
Hide navigation sidebar

Hide table of contents sidebar
Skip to content


Toggle site navigation sidebar



Python Packaging User Guide




Toggle Light / Dark / Auto color theme


Toggle table of contents sidebar



Python Packaging User Guide




Overview of Python Packaging

The Packaging Flow

Tutorials
Toggle navigation of Tutorials

Installing Packages

Managing Application Dependencies

Packaging Python Projects


Guides
Toggle navigation of Guides

Installation
Toggle navigation of Installation

Install packages in a virtual environment using pip and venv

Installing packages using virtualenv

Installing stand alone command line tools

Installing pip/setuptools/wheel with Linux Package Managers

Installing scientific packages


Building and Publishing
Toggle navigation of Building and Publishing

Writing your pyproject.toml

Packaging and distributing projects

Dropping support for older Python versions

Packaging binary extensions

Packaging namespace packages

Creating and packaging command-line tools

Creating and discovering plugins

Using TestPyPI

Making a PyPI-friendly README

Publishing package distribution releases using GitHub Actions CI/CD workflows

How to modernize a setup.py based project?

Licensing examples and user scenarios


Hosting
Toggle navigation of Hosting

Package index mirrors and caches

Hosting your own simple repository


Tool recommendations

Analyzing PyPI package downloads


Discussions
Toggle navigation of Discussions

Versioning

Deploying Python applications

pip vs easy_install

install_requires vs requirements files

Distribution package vs. import package

Package Formats

src layout vs flat layout

Is setup.py deprecated?

Single-sourcing the Project Version

Supporting downstream packaging


PyPA specifications
Toggle navigation of PyPA specifications

Package Distribution Metadata
Toggle navigation of Package Distribution Metadata

Names and normalization

Core metadata specifications

Version specifiers

Dependency specifiers

pyproject.toml specification

Dependency Groups

Inline script metadata

Platform compatibility tags

Well-known Project URLs in Metadata

glob patterns

License Expression


Package Installation Metadata
Toggle navigation of Package Installation Metadata

Recording installed projects

Entry points specification

Recording the Direct URL Origin of installed distributions

Direct URL Data Structure

Python Virtual Environments

Externally Managed Environments


Package Distribution File Formats
Toggle navigation of Package Distribution File Formats

Source distribution format

Binary distribution format


Package Index Interfaces
Toggle navigation of Package Index Interfaces

The .pypirc file

Simple repository API

File Yanking

Index hosted attestations

Project Status Markers


Python Description Formats
Toggle navigation of Python Description Formats

build-details.json
Toggle navigation of build-details.json

v1.0



Reproducible Environments
Toggle navigation of Reproducible Environments

pylock.toml Specification


PyPA schemas


Project Summaries

Glossary

How to Get Support

Contribute to this guide

News







Back to top

View this page

Edit this page


Toggle Light / Dark / Auto color theme


Toggle table of contents sidebar




Inline script metadata¶

This specification defines a metadata format that can be embedded in single-file Python scripts to assist launchers, IDEs and other external tools which may need to interact with such scripts.


Specification¶

This specification defines a metadata comment block format (loosely inspired by reStructuredText Directives).

Any Python script may have top-level comment blocks that MUST start with the line #///TYPE where TYPE determines how to process the content. That is: a single #, followed by a single space, followed by three forward slashes, followed by a single space, followed by the type of metadata. Block MUST end with the line #///. That is: a single #, followed by a single space, followed by three forward slashes. The TYPE MUST only consist of ASCII letters, numbers and hyphens.

Every line between these two lines (#///TYPE and #///) MUST be a comment starting with #. If there are characters after the # then the first character MUST be a space. The embedded content is formed by taking away the first two characters of each line if the second character is a space, otherwise just the first character (which means the line consists of only a single #).

Precedence for an ending line #/// is given when the next line is not a valid embedded content line as described above. For example, the following is a single fully valid block:


# /// some-toml# embedded-csharp = """# /// <summary># /// text# ///# /// </summary># public class MyClass { }# """# ///


A starting line MUST NOT be placed between another starting line and its ending line. In such cases tools MAY produce an error. Unclosed blocks MUST be ignored.

When there are multiple comment blocks of the same TYPE defined, tools MUST produce an error.

Tools reading embedded metadata MAY respect the standard Python encoding declaration. If they choose not to do so, they MUST process the file as UTF-8.

This is the canonical regular expression that MAY be used to parse the metadata:


(?m)^# /// (?P<type>[a-zA-Z0-9-]+)$\s(?P<content>(^#(| .*)$\s)+)^# ///$


In circumstances where there is a discrepancy between the text specification and the regular expression, the text specification takes precedence.

Tools MUST NOT read from metadata blocks with types that have not been standardized by this specification.

Note that the specification only requires that top-level comment blocks are recognised as containing metadata. However, parsing Python code is non-trivial, and therefore:


Tools MAY choose to do a simple textual scan, rather than a full Python parse.



As a result of the previous point, the behaviour of scripts that contain data that looks like metadata within another Python construct such as a multi-line string is tool-dependent and should not be relied on.



The canonical regular expression provided above is an example of an implementation that does a simple textual scan.



script type¶

The first type of metadata block is named script, which contains script metadata (dependency data and tool configuration).

This document MAY include the top-level fields dependencies and requires-python, and MAY optionally include a [tool] table.

The [tool] table MAY be used by any tool, script runner or otherwise, to configure behavior. It has the same semantics as the [tool] table in pyproject.toml.

The top-level fields are:


dependencies: A list of strings that specifies the runtime dependencies of the script. Each entry MUST be a valid dependency specifier.



requires-python: A string that specifies the Python version(s) with which the script is compatible. The value of this field MUST be a valid version specifier.


Script runners MUST error if the specified dependencies cannot be provided. Script runners SHOULD error if no version of Python that satisfies the specified requires-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])





Reference Implementation¶

The following is an example of how to read the metadata on Python 3.11 or higher.


importreimporttomllibREGEX=r'(?m)^# /// (?P<type>[a-zA-Z0-9-]+)$\s(?P<content>(^#(| .*)$\s)+)^# ///$'defread(script:str)->dict|None:name='script'matches=list(filter(lambdam:m.group('type')==name,re.finditer(REGEX,script)))iflen(matches)>1:raiseValueError(f'Multiple {name} blocks found')eliflen(matches)==1:content=''.join(line[2:]ifline.startswith('# ')elseline[1:]forlineinmatches[0].group('content').splitlines(keepends=True))returntomllib.loads(content)else:returnNone


Often tools will edit dependencies like package managers or dependency update automation in CI. The following is a crude example of modifying the content using the tomlkitlibrary.


importreimporttomlkitREGEX=r'(?m)^# /// (?P<type>[a-zA-Z0-9-]+)$\s(?P<content>(^#(| .*)$\s)+)^# ///$'defadd(script:str,dependency:str)->str:match=re.search(REGEX,script)content=''.join(line[2:]ifline.startswith('# ')elseline[1:]forlineinmatch.group('content').splitlines(keepends=True))config=tomlkit.parse(content)config['dependencies'].append(dependency)new_content=''.join(f'# {line}'ifline.strip()elsef'#{line}'forlineintomlkit.dumps(config).splitlines(keepends=True))start,end=match.span('content')returnscript[:start]+new_content+script[end:]


Note that this example used a library that preserves TOML formatting. This is not a requirement for editing by any means but rather is a “nice to have” feature.

The following is an example of how to read a stream of arbitrary metadata blocks.


importrefromtypingimportIteratorREGEX=r'(?m)^# /// (?P<type>[a-zA-Z0-9-]+)$\s(?P<content>(^#(| .*)$\s)+)^# ///$'defstream(script:str)->Iterator[tuple[str,str]]:formatchinre.finditer(REGEX,script):yieldmatch.group('type'),''.join(line[2:]ifline.startswith('# ')elseline[1:]forlineinmatch.group('content').splitlines(keepends=True))




Recommendations¶

Tools that support managing different versions of Python should attempt to use the highest available version of Python that is compatible with the script’s requires-python metadata, if defined.



History¶


October 2023: This specification was conditionally approved through PEP 723.



January 2024: Through amendments to PEP 723, the pyproject metadata block type was renamed to script, and the [run] table was dropped, making the dependencies and requires-python keys top-level. Additionally, the specification is no longer provisional.








Next

Platform compatibility tags



Previous

Dependency Groups





Copyright © 2013–2020, PyPA
Made with Sphinx and @pradyunsg's Furo
Last updated on Jul 29, 2026







On this page



Inline script metadata
Specification
script type

Example


Reference Implementation

Recommendations

History







------
导航页 打开网址