Text of peps.python.org › pep-0711 as Styx crawled it on Nov 19, 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 711 – PyBI: a standard format for distributing Python Binaries | peps.python.org

PEP 711 – PyBI: a standard format for distributing Python Binaries PEP 711 – PyBI: a standard format for distributing Python Binaries Author : Nathaniel J. Smith <njs at pobox.com> Discussions-To : Discourse thread Status : Draft Type : Standards Track Topic : Packaging Created : 06-Apr-2023 Post-History : 06-Apr-2023 Table of Contents Abstract Motivation Examples Specification Filename File contents Pybi-specific core metadata Symlinks Representing symlinks in zip files Representing symlinks in RECORD files Storing symlinks in pybi files Limitations Non-normative comments Why not just use conda?

Sdists (or not) What packages should be bundled inside a pybi? Backwards Compatibility Security Implications How to Teach This Copyright Abstract “Like wheels, but instead of a pre-built python package, it’s a pre-built python interpreter” Motivation End goal: Pypi.org has pre-built packages for all Python versions on all popular platforms, so automated tools can easily grab any of them and set it up. It becomes quick and easy to try Python prereleases, pin Python versions in CI, make a temporary environment to reproduce a bug report that only happens on a specific Python point release, etc.

First step (this PEP): define a standard packaging file format to hold pre-built Python interpreters, that reuses existing Python packaging standards as much as possible. Examples Example pybi builds are available at pybi.vorpus.org . They’re zip files, so you can unpack them and poke around inside if you want to get a feel for how they’re laid out. You can also look at the tooling I used to create them . Specification Filename Filename: {distribution}-{version}[-{build tag}]-{platform tag}.pybi This matches the wheel file format defined in PEP 427 , except dropping the {python tag} and {abi tag} and changing the extension from .whl → .pybi .

For example: cpython-3.9.3-manylinux_2014.pybi cpython-3.10b2-win_amd64.pybi Just like for wheels, if a pybi supports multiple platforms, you can separate them by dots to make a “compressed tag set”: cpython-3.9.5-macosx_11_0_x86_64.macosx_11_0_arm64.pybi (Though in practice this probably won’t be used much, e.g. the above filename is more idiomatically written as cpython-3.9.5-macosx_11_0_universal2.pybi .) File contents A .pybi file is a zip file, that can be unpacked directly into an arbitrary location and then used as a self-contained Python environment.

There’s no .data directory or install scheme keys, because the Python environment knows which install scheme it’s using, so it can just put things in the right places to start with. The “arbitrary location” part is important: the pybi can’t contain any hardcoded absolute paths. In particular, any preinstalled scripts MUST NOT embed absolute paths in their shebang lines. Similar to wheels’ <package>-<version>.dist-info directory, the pybi archive must contain a top-level directory named pybi-info/ . (Rationale: calling it pybi-info instead dist-info makes sure that tools don’t get confused about which kind of metadata they’re looking at; leaving off the {name}-{version} part is fine because only one pybi can be installed into a given directory.) The pybi-info/ directory contains at least the following files: .../PYBI : metadata about the archive itself, in the same RFC822-ish format as METADATA and WHEEL files: Pybi - Version : 1.0 Generator : { name } { version } Tag : { platform tag } Tag : { another platform tag } Tag : { ... and so on ... } Build : 1 # optional .../RECORD : same as in wheels, except see the note about symlinks, below. .../METADATA : In the same format as described in the current core metadata spec, except that the following keys are forbidden because they don’t make sense: Requires-Dist Provides-Extra Requires-Python And also there are some new, required keys described below.

Pybi-specific core metadata Here’s an example of the new METADATA fields, before we give the full details: Pybi - Environment - Marker - Variables : { "implementation_name" : "cpython" , "implementation_version" : "3.10.8" , "os_name" : "posix" , "platform_machine" : "x86_64" , "platform_system" : "Linux" , "python_full_version" : "3.10.8" , "platform_python_implementation" : "CPython" , "python_version" : "3.10" , "sys_platform" : "linux" } Pybi - Paths : { "stdlib" : "lib/python3.10" , "platstdlib" : "lib/python3.10" , "purelib" : "lib/python3.10/site-packages" , "platlib" : "lib/python3.10/site-packages" , "include" : "include/python3.10" , "platinclude" : "include/python3.10" , "scripts" : "bin" , "data" : "." } Pybi - Wheel - Tag : cp310 - cp310 - PLATFORM Pybi - Wheel - Tag : cp310 - abi3 - PLATFORM Pybi - Wheel - Tag : cp310 - none - PLATFORM Pybi - Wheel - Tag : cp39 - abi3 - PLATFORM Pybi - Wheel - Tag : cp38 - abi3 - PLATFORM Pybi - Wheel - Tag : cp37 - abi3 - PLATFORM Pybi - Wheel - Tag : cp36 - abi3 - PLATFORM Pybi - Wheel - Tag : cp35 - abi3 - PLATFORM Pybi - Wheel - Tag : cp34 - abi3 - PLATFORM Pybi - Wheel - Tag : cp33 - abi3 - PLATFORM Pybi - Wheel - Tag : cp32 - abi3 - PLATFORM Pybi - Wheel - Tag : py310 - none - PLATFORM Pybi - Wheel - Tag : py3 - none - PLATFORM Pybi - Wheel - Tag : py39 - none - PLATFORM Pybi - Wheel - Tag : py38 - none - PLATFORM Pybi - Wheel - Tag : py37 - none - PLATFORM Pybi - Wheel - Tag : py36 - none - PLATFORM Pybi - Wheel - Tag : py35 - none - PLATFORM Pybi - Wheel - Tag : py34 - none - PLATFORM Pybi - Wheel - Tag : py33 - none - PLATFORM Pybi - Wheel - Tag : py32 - none - PLATFORM Pybi - Wheel - Tag : py31 - none - PLATFORM Pybi - Wheel - Tag : py30 - none - PLATFORM Pybi - Wheel - Tag : py310 - none - any Pybi - Wheel - Tag : py3 - none - any Pybi - Wheel - Tag : py39 - none - any Pybi - Wheel - Tag : py38 - none - any Pybi - Wheel - Tag : py37 - none - any Pybi - Wheel - Tag : py36 - none - any Pybi - Wheel - Tag : py35 - none - any Pybi - Wheel - Tag : py34 - none - any Pybi - Wheel - Tag : py33 - none - any Pybi - Wheel - Tag : py32 - none - any Pybi - Wheel - Tag : py31 - none - any Pybi - Wheel - Tag : py30 - none - any Specification: Pybi-Environment-Marker-Variables : The value of all PEP 508 environment marker variables that are static across installs of this Pybi, as a JSON dict.

So for example: python_version will always be present, because a Python 3.10 package always has python_version == "3.10" . platform_version will generally not be present, because it gives detailed information about the OS where Python is running, for example: #60-Ubuntu SMP Thu May 6 07:46:32 UTC 2021 platform_release has similar issues. platform_machine will usually be present, except for macOS universal2 pybis: these can potentially be run in either x86-64 or arm64 mode, and we don’t know which until the interpreter is actually invoked, so we can’t record it in static metadata.

Rationale: In many cases, this should allow a resolver running on Linux to compute package pins for a Python environment on Windows, or vice-versa, so long as the resolver has access to the target platform’s .pybi file. (Note that Requires-Python constraints can be checked by using the python_full_version value.) While we have to leave out a few keys sometimes, they’re either fairly useless ( platform_version , platform_release ) or can be reconstructed by the resolver ( platform_machine ).

The markers are also just generally useful information to have accessible. For example, if you have a pypy3-7.3.2 pybi, and you want to know what version of the Python language that supports, then that’s recorded in the python_version marker. (Note: we may want to deprecate/remove platform_version and platform_release ? They’re problematic and I can’t figure out any cases where they’re useful. But that’s out of scope of this particular PEP.) Pybi-Paths : The install paths needed to install wheels (same keys as sysconfig.get_paths() ), as relative paths starting at the root of the zip file, as a JSON dict.

These paths MUST be written i

The rest of this page is on the live site.