PEP 658 lets a package index serve a distribution's METADATA file on its own, so a tool can resolve dependencies without downloading whole archives. A mirror that does not pass it along forces slower, larger downloads. PEP 714 later renamed the key that advertises it, so mirror operators should serve the current name.
The problem it solves
To choose which versions to install, a resolver needs each candidate's declared dependencies. Without help, that meant downloading the wheel or sdist and discarding most of the data. The PEP states the motivation: workflows need to inspect distribution metadata without intending to install, and downloading multiple distributions to choose among them is inefficient.
The earlier workaround was partial downloads using HTTP range requests. The PEP notes this adds requirements for the repository server and still costs an extra request to find the metadata offset inside the archive.
What PEP 658 specifies
The index extracts the core metadata file in advance and exposes it as its own file, linked from the Simple Repository API. The PEP says the metadata must only be served for standards compliant distributions such as wheels and sdists. A client can fetch a small file and read dependency information from it.
PEP 691 later added a JSON form of the Simple API that carries the same information.
The PEP 714 rename
PEP 714 exists because of a naming bug. It renamed the metadata key and provides guidance to both clients and servers. Its motivation section explains that PyPI first shipped support with a mistake in the JSON key name, and that fixing it ran into a separate bug in an old pip version that would fail hard when it saw the correct key. The PEP chose a rename so both sides could move without breaking installs.
For a mirror operator the takeaway is simple: follow the current names in PEP 714, not the original PEP 658 text.
Why this matters for security and operations
Faster resolution is nice, but there are other effects.
- Metadata and file must agree. If your mirror serves metadata that differs from what is inside the wheel, tools may resolve one set of dependencies and install another. Generate it from the file itself.
- Scanners read the same data. Tools that build an inventory from dependency declarations rely on accurate metadata. Wrong metadata means a wrong inventory.
- Proxies should not rewrite it. A caching proxy that strips the field only costs speed. One that alters it can alter resolution.
- Hashes still apply. Metadata files are a convenience for resolving. Your install is still protected, or not, by hash checking on the actual files. See how pip hash checking works.
A check for your mirror
Request the Simple page for a project that is on your mirror, through the JSON form if you support it, and look at whether wheel entries advertise a metadata file. Then fetch that file and compare its Requires-Dist lines with those of the downloaded wheel. If they differ, treat it as a bug.
curl -s -H "Accept: application/vnd.pypi.simple.v1+json" https://your-mirror.example/simple/somepackage/
The Accept header value is the JSON content type defined by PEP 691. If your mirror ignores it and returns HTML, you are on the older form.
Safeguard's dependency scanning and SBOM generation work from declared and resolved dependencies, so a mirror that keeps metadata honest keeps those results honest. A free scan is available at gold.safeguard.sh/scan.
Quick check
Is PEP 658 a security feature?
It is a performance feature. It matters to security because wrong metadata can mislead resolvers and inventories.
Which PEP renamed the metadata key?
PEP 714, which provides guidance for clients and servers on the rename.
Sources
- PEP 658, Serve Distribution Metadata in the Simple Repository API
- PEP 714, Rename dist-info-metadata in the Simple API
- PEP 691, JSON-based Simple API for Python Package Indexes
Last reviewed: 19 October 2026.
