pypa/pip · error · PEP723Exception

File does not contain {name!r} metadata: {scriptfile!r}

Error message

File does not contain {name!r} metadata: {scriptfile!r}

What it means

Raised by pep723_metadata() when a script file is processed for PEP 723 inline metadata but contains zero `# /// script` blocks (the else branch at pep723.py:37). pip was asked to read PEP 723 metadata from the file, but none exists, so it cannot determine the script's dependencies.

Source

Thrown at src/pip/_internal/req/pep723.py:37

    name = "script"
    matches = list(
        filter(lambda m: m.group("type") == name, re.finditer(REGEX, script))
    )

    if len(matches) > 1:
        raise PEP723Exception(f"Multiple {name!r} blocks found in {scriptfile!r}")
    elif len(matches) == 1:
        content = "".join(
            line[2:] if line.startswith("# ") else line[1:]
            for line in matches[0].group("content").splitlines(keepends=True)
        )
        try:
            metadata = tomllib.loads(content)
        except Exception as exc:
            raise PEP723Exception(f"Failed to parse TOML in {scriptfile!r}") from exc
    else:
        raise PEP723Exception(
            f"File does not contain {name!r} metadata: {scriptfile!r}"
        )

    return metadata

View on GitHub (pinned to d7d0d0a394)

Solutions

If the script needs dependencies declared inline, add a `# /// script` block with a `dependencies` array.
If the script has no external dependencies, either add an empty block or use a normal `python script.py` invocation after installing deps separately.
Verify the block uses the exact marker `# /// script` (lowercase, no extra text on the marker line).

Example fix

# before
# (script with no metadata block)
import requests
# after
# /// script
# dependencies = ["requests"]
# ///
import requests

Defensive patterns

Strategy: validation

Validate before calling

import re

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

def has_pep723_block(scriptfile: str) -> bool:
    with open(scriptfile, encoding="utf8") as f:
        script = f.read()
    return any(m.group("type") == "script" for m in re.finditer(PEP723_RE, script))

# before invoking a PEP 723 code path:
if not has_pep723_block(scriptfile):
    raise ValueError(f"{scriptfile} has no PEP 723 script metadata block")

Type guard

null

Try / catch

from pip._internal.req.pep723 import pep723_metadata, PEP723Exception

try:
    meta = pep723_metadata(scriptfile)
except PEP723Exception as e:
    if "does not contain" in e.msg:
        meta = {}  # treat as no inline deps
    else:
        raise

Prevention

Add a `# /// script` block (even if just with `dependencies = []`) to scripts meant for PEP 723 tooling.
Use the exact marker `# /// script` on its own line.
For scripts without external deps, prefer plain `python script.py` over PEP 723 tooling.

When it happens

Trigger: Running a PEP 723-aware code path (e.g. `pip run script.py`) on a plain Python script that has no `# /// script` block. The regex finds zero matches of type 'script'.

Common situations: Passing a regular script to a tool that requires inline metadata. Forgetting to add the metadata block when migrating to pip run. A script that intentionally has no deps but the tooling still requires the block.

Related errors

AI-assisted analysis of pypa/pip@d7d0d0a394 (2026-08-04). Data as JSON: /data/errors/7ce0055616222349.json. Report an issue: GitHub.