CINXE.COM

<!DOCTYPE html> <html lang="en"> <head> <meta charset="utf-8"> <meta name="viewport" content="width=device-width, initial-scale=1.0"> <meta name="color-scheme" content="light dark"> <title>PEP 739 – build-details.json 1.0 — a static description file for Python build details | peps.python.org</title> <link rel="shortcut icon" href="../_static/py.png"> <link rel="canonical" href="https://peps.python.org/pep-0739/"> <link rel="stylesheet" href="../_static/style.css" type="text/css"> <link rel="stylesheet" href="../_static/mq.css" type="text/css"> <link rel="stylesheet" href="../_static/pygments.css" type="text/css" media="(prefers-color-scheme: light)" id="pyg-light"> <link rel="stylesheet" href="../_static/pygments_dark.css" type="text/css" media="(prefers-color-scheme: dark)" id="pyg-dark"> <link rel="alternate" type="application/rss+xml" title="Latest PEPs" href="https://peps.python.org/peps.rss"> <meta property="og:title" content='PEP 739 – build-details.json 1.0 — a static description file for Python build details | peps.python.org'> <meta property="og:description" content="This PEP introduces build-details.json, a static description file containing build details of Python installations."> <meta property="og:type" content="website"> <meta property="og:url" content="https://peps.python.org/pep-0739/"> <meta property="og:site_name" content="Python Enhancement Proposals (PEPs)"> <meta property="og:image" content="https://peps.python.org/_static/og-image.png"> <meta property="og:image:alt" content="Python PEPs"> <meta property="og:image:width" content="200"> <meta property="og:image:height" content="200"> <meta name="description" content="This PEP introduces build-details.json, a static description file containing build details of Python installations."> <meta name="theme-color" content="#3776ab"> </head> <body> <svg xmlns="http://www.w3.org/2000/svg" style="display: none;"> <symbol id="svg-sun-half" viewBox="0 0 24 24" pointer-events="all"> <title>Following system colour scheme</title> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"> <circle cx="12" cy="12" r="9"></circle> <path d="M12 3v18m0-12l4.65-4.65M12 14.3l7.37-7.37M12 19.6l8.85-8.85"></path> </svg> </symbol> <symbol id="svg-moon" viewBox="0 0 24 24" pointer-events="all"> <title>Selected dark colour scheme</title> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"> <path stroke="none" d="M0 0h24v24H0z" fill="none"></path> <path d="M12 3c.132 0 .263 0 .393 0a7.5 7.5 0 0 0 7.92 12.446a9 9 0 1 1 -8.313 -12.454z"></path> </svg> </symbol> <symbol id="svg-sun" viewBox="0 0 24 24" pointer-events="all"> <title>Selected light colour scheme</title> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"> <circle cx="12" cy="12" r="5"></circle> <line x1="12" y1="1" x2="12" y2="3"></line> <line x1="12" y1="21" x2="12" y2="23"></line> <line x1="4.22" y1="4.22" x2="5.64" y2="5.64"></line> <line x1="18.36" y1="18.36" x2="19.78" y2="19.78"></line> <line x1="1" y1="12" x2="3" y2="12"></line> <line x1="21" y1="12" x2="23" y2="12"></line> <line x1="4.22" y1="19.78" x2="5.64" y2="18.36"></line> <line x1="18.36" y1="5.64" x2="19.78" y2="4.22"></line> </svg> </symbol> </svg> <script> document.documentElement.dataset.colour_scheme = localStorage.getItem("colour_scheme") || "auto" </script> <section id="pep-page-section"> <header> <h1>Python Enhancement Proposals</h1> <ul class="breadcrumbs"> <li><a href="https://www.python.org/" title="The Python Programming Language">Python</a> » </li> <li><a href="../pep-0000/">PEP Index</a> » </li> <li>PEP 739</li> </ul> <button id="colour-scheme-cycler" onClick="setColourScheme(nextColourScheme())"> <svg aria-hidden="true" class="colour-scheme-icon-when-auto"><use href="#svg-sun-half"></use></svg> <svg aria-hidden="true" class="colour-scheme-icon-when-dark"><use href="#svg-moon"></use></svg> <svg aria-hidden="true" class="colour-scheme-icon-when-light"><use href="#svg-sun"></use></svg> Toggle light / dark / auto colour theme </button> </header> <article> <section id="pep-content"> <h1 class="page-title">PEP 739 – <code class="docutils literal notranslate">build-details.json</code> 1.0 — a static description file for Python build details</h1> <dl class="rfc2822 field-list simple"> <dt class="field-odd">Author:</dt> <dd class="field-odd">Filipe Laíns <lains at python.org></dd> <dt class="field-even">PEP-Delegate:</dt> <dd class="field-even">Paul Moore <p.f.moore at gmail.com></dd> <dt class="field-odd">Discussions-To:</dt> <dd class="field-odd"><a class="reference external" href="https://discuss.python.org/t/pep-739-static-description-file-for-build-details-of-python-installations/44572">Discourse thread</a></dd> <dt class="field-even">Status:</dt> <dd class="field-even"><abbr title="Normative proposal accepted for implementation">Accepted</abbr></dd> <dt class="field-odd">Type:</dt> <dd class="field-odd"><abbr title="Normative PEP with a new feature for Python, implementation change for CPython or interoperability standard for the ecosystem">Standards Track</abbr></dd> <dt class="field-even">Topic:</dt> <dd class="field-even"><a class="reference external" href="../topic/packaging/">Packaging</a></dd> <dt class="field-odd">Created:</dt> <dd class="field-odd">19-Dec-2023</dd> <dt class="field-even">Python-Version:</dt> <dd class="field-even">3.14</dd> <dt class="field-odd">Resolution:</dt> <dd class="field-odd"><a class="reference external" href="https://discuss.python.org/t/44572/90">Discourse message</a></dd> </dl> <hr class="docutils" /> <section id="contents"> <details><summary>Table of Contents</summary><ul class="simple"> <li><a class="reference internal" href="#abstract">Abstract</a></li> <li><a class="reference internal" href="#rationale">Rationale</a></li> <li><a class="reference internal" href="#scope">Scope</a></li> <li><a class="reference internal" href="#specification">Specification</a></li> <li><a class="reference internal" href="#format">Format</a><ul> <li><a class="reference internal" href="#schema-version"><code class="docutils literal notranslate">schema_version</code></a></li> <li><a class="reference internal" href="#base-prefix"><code class="docutils literal notranslate">base_prefix</code></a></li> <li><a class="reference internal" href="#base-interpreter"><code class="docutils literal notranslate">base_interpreter</code></a></li> <li><a class="reference internal" href="#platform"><code class="docutils literal notranslate">platform</code></a></li> <li><a class="reference internal" href="#language"><code class="docutils literal notranslate">language</code></a><ul> <li><a class="reference internal" href="#language-version"><code class="docutils literal notranslate">language.version</code></a></li> <li><a class="reference internal" href="#language-version-info"><code class="docutils literal notranslate">language.version_info</code></a><ul> <li><a class="reference internal" href="#language-version-info-major"><code class="docutils literal notranslate">language.version_info.major</code></a></li> <li><a class="reference internal" href="#language-version-info-minor"><code class="docutils literal notranslate">language.version_info.minor</code></a></li> <li><a class="reference internal" href="#language-version-info-micro"><code class="docutils literal notranslate">language.version_info.micro</code></a></li> <li><a class="reference internal" href="#language-version-info-releaselevel"><code class="docutils literal notranslate">language.version_info.releaselevel</code></a></li> <li><a class="reference internal" href="#language-version-info-serial"><code class="docutils literal notranslate">language.version_info.serial</code></a></li> </ul> </li> </ul> </li> <li><a class="reference internal" href="#implementation"><code class="docutils literal notranslate">implementation</code></a><ul> <li><a class="reference internal" href="#implementation-name"><code class="docutils literal notranslate">implementation.name</code></a></li> <li><a class="reference internal" href="#implementation-version"><code class="docutils literal notranslate">implementation.version</code></a><ul> <li><a class="reference internal" href="#implementation-version-major"><code class="docutils literal notranslate">implementation.version.major</code></a></li> <li><a class="reference internal" href="#implementation-version-minor"><code class="docutils literal notranslate">implementation.version.minor</code></a></li> <li><a class="reference internal" href="#implementation-version-micro"><code class="docutils literal notranslate">implementation.version.micro</code></a></li> <li><a class="reference internal" href="#implementation-version-releaselevel"><code class="docutils literal notranslate">implementation.version.releaselevel</code></a></li> <li><a class="reference internal" href="#implementation-version-serial"><code class="docutils literal notranslate">implementation.version.serial</code></a></li> </ul> </li> </ul> </li> <li><a class="reference internal" href="#abi"><code class="docutils literal notranslate">abi</code></a><ul> <li><a class="reference internal" href="#abi-flags"><code class="docutils literal notranslate">abi.flags</code></a></li> <li><a class="reference internal" href="#abi-extension-suffix"><code class="docutils literal notranslate">abi.extension_suffix</code></a></li> <li><a class="reference internal" href="#abi-stable-abi-suffix"><code class="docutils literal notranslate">abi.stable_abi_suffix</code></a></li> </ul> </li> <li><a class="reference internal" href="#suffixes"><code class="docutils literal notranslate">suffixes</code></a></li> <li><a class="reference internal" href="#libpython"><code class="docutils literal notranslate">libpython</code></a><ul> <li><a class="reference internal" href="#libpython-dynamic"><code class="docutils literal notranslate">libpython.dynamic</code></a></li> <li><a class="reference internal" href="#libpython-dynamic-stableabi"><code class="docutils literal notranslate">libpython.dynamic_stableabi</code></a></li> <li><a class="reference internal" href="#libpython-static"><code class="docutils literal notranslate">libpython.static</code></a></li> <li><a class="reference internal" href="#libpython-link-extensions"><code class="docutils literal notranslate">libpython.link_extensions</code></a></li> </ul> </li> <li><a class="reference internal" href="#c-api"><code class="docutils literal notranslate">c_api</code></a><ul> <li><a class="reference internal" href="#c-api-headers"><code class="docutils literal notranslate">c_api.headers</code></a></li> <li><a class="reference internal" href="#c-api-pkgconfig-path"><code class="docutils literal notranslate">c_api.pkgconfig_path</code></a></li> </ul> </li> <li><a class="reference internal" href="#arbitrary-data"><code class="docutils literal notranslate">arbitrary_data</code></a></li> </ul> </li> <li><a class="reference internal" href="#example">Example</a></li> <li><a class="reference internal" href="#json-schema">JSON Schema</a></li> <li><a class="reference internal" href="#rejected-ideas">Rejected Ideas</a><ul> <li><a class="reference internal" href="#including-environment-specific-data">Including environment-specific data</a></li> </ul> </li> <li><a class="reference internal" href="#copyright">Copyright</a></li> </ul> </details></section> <section id="abstract"> <h2><a class="toc-backref" href="#abstract" role="doc-backlink">Abstract</a></h2> This PEP introduces <code class="docutils literal notranslate">build-details.json</code>, a static description file containing build details of Python installations. It includes the definition of version 1.0 of the file format, and defines the standard location for this file. </section> <section id="rationale"> <h2><a class="toc-backref" href="#rationale" role="doc-backlink">Rationale</a></h2> When introspecting a Python installation, running code is often undesirable or impossible. Having a static description file makes various build details of the Python installation available without having to run the interpreter. This is helpful for use-cases such as cross-compilation, Python launchers, etc. </section> <section id="scope"> <h2><a class="toc-backref" href="#scope" role="doc-backlink">Scope</a></h2> <code class="docutils literal notranslate">build-details.json</code> is an installation-wide file, meaning that it MUST only contain information that is constant across all environments of the Python installation. Information specific to a Python environment, such as the <code class="docutils literal notranslate">site-packages</code> path, is outside the scope for this file, and the PEP authors expect that a static environment description file will be introduced via a future PEP. </section> <section id="specification"> <h2><a class="toc-backref" href="#specification" role="doc-backlink">Specification</a></h2> Starting from Python 3.14, a file named <code class="docutils literal notranslate">build-details.json</code> following the format specified in this PEP, or a future version, MUST be installed in the platform-independent standard library directory (<code class="docutils literal notranslate">stdlib</code>, eg. <code class="docutils literal notranslate">/usr/lib/python3.14/build-details.json</code>), UNLESS unfeasible due to technical limitations. <div class="admonition attention"> Attention In addition to the standard location specified by this PEP, the <code class="docutils literal notranslate">build-details.json</code> file MAY also be installed into additional locations, and under a different name. Notwithstanding, the file SHOULD still be available at the standard location. In actuality, the PEP authors expect future PEPs to define additional install locations with better discoverability. </div> </section> <section id="format"> <h2><a class="toc-backref" href="#format" role="doc-backlink">Format</a></h2> The format specification is defined by the JSON Schema definition provided below, which is rendered in an human-readable format here. <table class="docutils align-default" id="spec-start"> <colgroup> <col style="width: 25.0%" /> <col style="width: 75.0%" /> </colgroup> <tbody> <tr class="row-odd"><td><code class="docutils literal notranslate">$schema</code></td> <td><a class="reference external" href="https://json-schema.org/draft/2020-12/schema">https://json-schema.org/draft/2020-12/schema</a></td> </tr> <tr class="row-even"><td><code class="docutils literal notranslate">$id</code></td> <td><a class="reference external" href="https://github.com/python/peps/blob/main/peps/pep-0739/python-build-info-v1.0.schema.json">https://github.com/python/peps/blob/main/peps/pep-0739/python-build-info-v1.0.schema.json</a></td> </tr> <tr class="row-odd"><td>Title</td> <td>build-details.json — a static description file with build details of Python installations</td> </tr> <tr class="row-even"><td>Type</td> <td><code class="docutils literal notranslate">object</code></td> </tr> <tr class="row-odd"><td>Additional properties</td> <td>Not allowed</td> </tr> </tbody> </table> <section id="schema-version"> <h3><a class="toc-backref" href="#schema-version" role="doc-backlink"><code class="docutils literal notranslate">schema_version</code></a></h3> <table class="docutils align-default"> <colgroup> <col style="width: 25.0%" /> <col style="width: 75.0%" /> </colgroup> <tbody> <tr class="row-odd"><td>Type</td> <td><code class="docutils literal notranslate">string</code> (constant — <code class="docutils literal notranslate">1.0</code>)</td> </tr> <tr class="row-even"><td>Description</td> <td>Schema version.This is a string following the format <code class="docutils literal notranslate"><MAJOR>.<MINOR></code>, where <code class="docutils literal notranslate"><MAJOR></code> and <code class="docutils literal notranslate"><MINOR></code> are unpadded numbers and represent the major and minor components of the version. Versions may be arithmetically compared by interpreting the version string as a decimal number. For this specification version, this value is constant and MUST be <code class="docutils literal notranslate">1.0</code>. Future versions of this schema MUST use a higher version number. Future versions of this schema MUST NOT use the same major version component as other schema version unless its specification is deemed backwards-compatible with them — it can’t change, or extend, any parts of the current specification in such a way as the semantics of the interpreted data differ, or that data valid under the new specification is invalid under the older specification, with the exception of additional properties (errors caused by <code class="docutils literal notranslate">additionalProperties</code>). </td> </tr> <tr class="row-odd"><td>Required</td> <td>True</td> </tr> </tbody> </table> </section> <section id="base-prefix"> <h3><a class="toc-backref" href="#base-prefix" role="doc-backlink"><code class="docutils literal notranslate">base_prefix</code></a></h3> <table class="docutils align-default"> <colgroup> <col style="width: 25.0%" /> <col style="width: 75.0%" /> </colgroup> <tbody> <tr class="row-odd"><td>Type</td> <td><code class="docutils literal notranslate">string</code></td> </tr> <tr class="row-even"><td>Description</td> <td>Base prefix of the Python installation.Either an absolute path, or a path relative to directory where this file is contained. </td> </tr> <tr class="row-odd"><td>Examples</td> <td><code class="docutils literal notranslate">/usr</code>, <code class="docutils literal notranslate">../..</code>, etc.</td> </tr> <tr class="row-even"><td>Required</td> <td>True</td> </tr> </tbody> </table> </section> <section id="base-interpreter"> <h3><a class="toc-backref" href="#base-interpreter" role="doc-backlink"><code class="docutils literal notranslate">base_interpreter</code></a></h3> <table class="docutils align-default"> <colgroup> <col style="width: 25.0%" /> <col style="width: 75.0%" /> </colgroup> <tbody> <tr class="row-odd"><td>Type</td> <td><code class="docutils literal notranslate">string</code></td> </tr> <tr class="row-even"><td>Description</td> <td>The path to the Python interpreter of the base installation.Either an absolute path, or a path relative to <code class="docutils literal notranslate">base_prefix</code>. This field MUST be present if the installation provides an interpreter executable. </td> </tr> <tr class="row-odd"><td>Examples</td> <td><ul class="simple"> <li><code class="docutils literal notranslate">/usr/bin/python</code></li> <li><code class="docutils literal notranslate">bin/python</code></li> <li>etc.</li> </ul> </td> </tr> <tr class="row-even"><td>Required</td> <td>False</td> </tr> </tbody> </table> </section> <section id="platform"> <h3><a class="toc-backref" href="#platform" role="doc-backlink"><code class="docutils literal notranslate">platform</code></a></h3> <table class="docutils align-default"> <colgroup> <col style="width: 25.0%" /> <col style="width: 75.0%" /> </colgroup> <tbody> <tr class="row-odd"><td>Type</td> <td><code class="docutils literal notranslate">string</code></td> </tr> <tr class="row-even"><td>Description</td> <td>System platform string.This field SHOULD be equivalent to <code class="docutils literal notranslate">sysconfig.get_platform()</code>. </td> </tr> <tr class="row-odd"><td>Examples</td> <td><ul class="simple"> <li><code class="docutils literal notranslate">linux-x86_64</code></li> <li>etc.</li> </ul> </td> </tr> <tr class="row-even"><td>Required</td> <td>True</td> </tr> </tbody> </table> </section> <section id="language"> <h3><a class="toc-backref" href="#language" role="doc-backlink"><code class="docutils literal notranslate">language</code></a></h3> <table class="docutils align-default"> <colgroup> <col style="width: 25.0%" /> <col style="width: 75.0%" /> </colgroup> <tbody> <tr class="row-odd"><td>Type</td> <td><code class="docutils literal notranslate">object</code></td> </tr> <tr class="row-even"><td>Description</td> <td>Object containing details related to the Python language specification.</td> </tr> <tr class="row-odd"><td>Required</td> <td>True</td> </tr> <tr class="row-even"><td>Additional properties</td> <td>Not allowed</td> </tr> </tbody> </table> <section id="language-version"> <h4><a class="toc-backref" href="#language-version" role="doc-backlink"><code class="docutils literal notranslate">language.version</code></a></h4> <table class="docutils align-default"> <colgroup> <col style="width: 25.0%" /> <col style="width: 75.0%" /> </colgroup> <tbody> <tr class="row-odd"><td>Type</td> <td><code class="docutils literal notranslate">string</code></td> </tr> <tr class="row-even"><td>Description</td> <td>String representation the Python language version — a version string consisting only of the major and minor components.This field SHOULD be equivalent to <code class="docutils literal notranslate">sysconfig.get_python_version()</code>. </td> </tr> <tr class="row-odd"><td>Examples</td> <td><code class="docutils literal notranslate">3.14</code>, etc.</td> </tr> <tr class="row-even"><td>Required</td> <td>True</td> </tr> </tbody> </table> </section> <section id="language-version-info"> <h4><a class="toc-backref" href="#language-version-info" role="doc-backlink"><code class="docutils literal notranslate">language.version_info</code></a></h4> <table class="docutils align-default"> <colgroup> <col style="width: 25.0%" /> <col style="width: 75.0%" /> </colgroup> <tbody> <tr class="row-odd"><td>Type</td> <td><code class="docutils literal notranslate">object</code></td> </tr> <tr class="row-even"><td>Description</td> <td>Object in the format of <a class="reference external" href="https://docs.python.org/3/library/sys.html#sys.version_info" title="(in Python v3.13)"><code class="xref py py-data docutils literal notranslate">sys.version_info</code></a>.This section SHOULD be equivalent to <a class="reference external" href="https://docs.python.org/3/library/sys.html#sys.version_info" title="(in Python v3.13)"><code class="xref py py-data docutils literal notranslate">sys.version_info</code></a>. </td> </tr> <tr class="row-odd"><td>Examples</td> <td><ul class="simple"> <li><code class="docutils literal notranslate">{'major': 3, 'minor': 14, 'micro': 1, 'releaselevel': 'final', 'serial': 0}</code></li> <li>etc.</li> </ul> </td> </tr> <tr class="row-even"><td>Required</td> <td>False</td> </tr> <tr class="row-odd"><td>Additional properties</td> <td>Not allowed</td> </tr> </tbody> </table> <section id="language-version-info-major"> <h5><a class="toc-backref" href="#language-version-info-major" role="doc-backlink"><code class="docutils literal notranslate">language.version_info.major</code></a></h5> <table class="docutils align-default"> <colgroup> <col style="width: 25.0%" /> <col style="width: 75.0%" /> </colgroup> <tbody> <tr class="row-odd"><td>Type</td> <td><code class="docutils literal notranslate">number</code></td> </tr> <tr class="row-even"><td>Required</td> <td>True</td> </tr> </tbody> </table> </section> <section id="language-version-info-minor"> <h5><a class="toc-backref" href="#language-version-info-minor" role="doc-backlink"><code class="docutils literal notranslate">language.version_info.minor</code></a></h5> <table class="docutils align-default"> <colgroup> <col style="width: 25.0%" /> <col style="width: 75.0%" /> </colgroup> <tbody> <tr class="row-odd"><td>Type</td> <td><code class="docutils literal notranslate">number</code></td> </tr> <tr class="row-even"><td>Required</td> <td>True</td> </tr> </tbody> </table> </section> <section id="language-version-info-micro"> <h5><a class="toc-backref" href="#language-version-info-micro" role="doc-backlink"><code class="docutils literal notranslate">language.version_info.micro</code></a></h5> <table class="docutils align-default"> <colgroup> <col style="width: 25.0%" /> <col style="width: 75.0%" /> </colgroup> <tbody> <tr class="row-odd"><td>Type</td> <td><code class="docutils literal notranslate">number</code></td> </tr> <tr class="row-even"><td>Required</td> <td>True</td> </tr> </tbody> </table> </section> <section id="language-version-info-releaselevel"> <h5><a class="toc-backref" href="#language-version-info-releaselevel" role="doc-backlink"><code class="docutils literal notranslate">language.version_info.releaselevel</code></a></h5> <table class="docutils align-default"> <colgroup> <col style="width: 25.0%" /> <col style="width: 75.0%" /> </colgroup> <tbody> <tr class="row-odd"><td>Type</td> <td><code class="docutils literal notranslate">string</code> (enum — <code class="docutils literal notranslate">alpha</code>, <code class="docutils literal notranslate">beta</code>, <code class="docutils literal notranslate">candidate</code>, <code class="docutils literal notranslate">final</code>)</td> </tr> <tr class="row-even"><td>Required</td> <td>True</td> </tr> </tbody> </table> </section> <section id="language-version-info-serial"> <h5><a class="toc-backref" href="#language-version-info-serial" role="doc-backlink"><code class="docutils literal notranslate">language.version_info.serial</code></a></h5> <table class="docutils align-default"> <colgroup> <col style="width: 25.0%" /> <col style="width: 75.0%" /> </colgroup> <tbody> <tr class="row-odd"><td>Type</td> <td><code class="docutils literal notranslate">number</code></td> </tr> <tr class="row-even"><td>Required</td> <td>True</td> </tr> </tbody> </table> </section> </section> </section> <section id="implementation"> <h3><a class="toc-backref" href="#implementation" role="doc-backlink"><code class="docutils literal notranslate">implementation</code></a></h3> <table class="docutils align-default"> <colgroup> <col style="width: 25.0%" /> <col style="width: 75.0%" /> </colgroup> <tbody> <tr class="row-odd"><td>Type</td> <td><code class="docutils literal notranslate">object</code></td> </tr> <tr class="row-even"><td>Description</td> <td>Object containing details related to the Python implementation.This section SHOULD be equivalent to <a class="reference external" href="https://docs.python.org/3/library/sys.html#sys.implementation" title="(in Python v3.13)"><code class="xref py py-data docutils literal notranslate">sys.implementation</code></a>. It follows the specification defined in <a class="pep reference internal" href="../pep-0421/" title="PEP 421 – Adding sys.implementation">PEP 421</a>, meaning that in addition to the required keys, implementation-specific keys can also exist, but must be prefixed with an underscore. </td> </tr> <tr class="row-odd"><td>Required</td> <td>True</td> </tr> <tr class="row-even"><td>Additional properties</td> <td>Allowed</td> </tr> </tbody> </table> <section id="implementation-name"> <h4><a class="toc-backref" href="#implementation-name" role="doc-backlink"><code class="docutils literal notranslate">implementation.name</code></a></h4> <table class="docutils align-default"> <colgroup> <col style="width: 25.0%" /> <col style="width: 75.0%" /> </colgroup> <tbody> <tr class="row-odd"><td>Type</td> <td><code class="docutils literal notranslate">string</code></td> </tr> <tr class="row-even"><td>Description</td> <td>Lower-case name of the Python implementation.</td> </tr> <tr class="row-odd"><td>Examples</td> <td><code class="docutils literal notranslate">cpython</code>, <code class="docutils literal notranslate">pypy</code>, etc.</td> </tr> <tr class="row-even"><td>Required</td> <td>True</td> </tr> </tbody> </table> </section> <section id="implementation-version"> <h4><a class="toc-backref" href="#implementation-version" role="doc-backlink"><code class="docutils literal notranslate">implementation.version</code></a></h4> <table class="docutils align-default"> <colgroup> <col style="width: 25.0%" /> <col style="width: 75.0%" /> </colgroup> <tbody> <tr class="row-odd"><td>Type</td> <td><code class="docutils literal notranslate">object</code></td> </tr> <tr class="row-even"><td>Description</td> <td>Object in the format of <a class="reference external" href="https://docs.python.org/3/library/sys.html#sys.version_info" title="(in Python v3.13)"><code class="xref py py-data docutils literal notranslate">sys.version_info</code></a>, containing the implementation version.</td> </tr> <tr class="row-odd"><td>Examples</td> <td><ul class="simple"> <li><code class="docutils literal notranslate">{'major': 3, 'minor': 14, 'micro': 1, 'releaselevel': 'final', 'serial': 0}</code></li> <li><code class="docutils literal notranslate">{'major': 7, 'minor': 3, 'micro': 16, 'releaselevel': 'final', 'serial': 0}</code></li> <li>etc.</li> </ul> </td> </tr> <tr class="row-even"><td>Required</td> <td>True</td> </tr> <tr class="row-odd"><td>Additional properties</td> <td>Not allowed</td> </tr> </tbody> </table> <section id="implementation-version-major"> <h5><a class="toc-backref" href="#implementation-version-major" role="doc-backlink"><code class="docutils literal notranslate">implementation.version.major</code></a></h5> <table class="docutils align-default"> <colgroup> <col style="width: 25.0%" /> <col style="width: 75.0%" /> </colgroup> <tbody> <tr class="row-odd"><td>Type</td> <td><code class="docutils literal notranslate">number</code></td> </tr> <tr class="row-even"><td>Required</td> <td>True</td> </tr> </tbody> </table> </section> <section id="implementation-version-minor"> <h5><a class="toc-backref" href="#implementation-version-minor" role="doc-backlink"><code class="docutils literal notranslate">implementation.version.minor</code></a></h5> <table class="docutils align-default"> <colgroup> <col style="width: 25.0%" /> <col style="width: 75.0%" /> </colgroup> <tbody> <tr class="row-odd"><td>Type</td> <td><code class="docutils literal notranslate">number</code></td> </tr> <tr class="row-even"><td>Required</td> <td>True</td> </tr> </tbody> </table> </section> <section id="implementation-version-micro"> <h5><a class="toc-backref" href="#implementation-version-micro" role="doc-backlink"><code class="docutils literal notranslate">implementation.version.micro</code></a></h5> <table class="docutils align-default"> <colgroup> <col style="width: 25.0%" /> <col style="width: 75.0%" /> </colgroup> <tbody> <tr class="row-odd"><td>Type</td> <td><code class="docutils literal notranslate">number</code></td> </tr> <tr class="row-even"><td>Required</td> <td>True</td> </tr> </tbody> </table> </section> <section id="implementation-version-releaselevel"> <h5><a class="toc-backref" href="#implementation-version-releaselevel" role="doc-backlink"><code class="docutils literal notranslate">implementation.version.releaselevel</code></a></h5> <table class="docutils align-default"> <colgroup> <col style="width: 25.0%" /> <col style="width: 75.0%" /> </colgroup> <tbody> <tr class="row-odd"><td>Type</td> <td><code class="docutils literal notranslate">string</code> (enum — <code class="docutils literal notranslate">alpha</code>, <code class="docutils literal notranslate">beta</code>, <code class="docutils literal notranslate">candidate</code>, <code class="docutils literal notranslate">final</code>)</td> </tr> <tr class="row-even"><td>Required</td> <td>True</td> </tr> </tbody> </table> </section> <section id="implementation-version-serial"> <h5><a class="toc-backref" href="#implementation-version-serial" role="doc-backlink"><code class="docutils literal notranslate">implementation.version.serial</code></a></h5> <table class="docutils align-default"> <colgroup> <col style="width: 25.0%" /> <col style="width: 75.0%" /> </colgroup> <tbody> <tr class="row-odd"><td>Type</td> <td><code class="docutils literal notranslate">number</code></td> </tr> <tr class="row-even"><td>Required</td> <td>True</td> </tr> </tbody> </table> </section> </section> </section> <section id="abi"> <h3><a class="toc-backref" href="#abi" role="doc-backlink"><code class="docutils literal notranslate">abi</code></a></h3> <table class="docutils align-default"> <colgroup> <col style="width: 25.0%" /> <col style="width: 75.0%" /> </colgroup> <tbody> <tr class="row-odd"><td>Type</td> <td><code class="docutils literal notranslate">object</code></td> </tr> <tr class="row-even"><td>Description</td> <td>Object containing details related to ABI.</td> </tr> <tr class="row-odd"><td>Required</td> <td>False</td> </tr> <tr class="row-even"><td>Additional properties</td> <td>Not allowed</td> </tr> </tbody> </table> <section id="abi-flags"> <h4><a class="toc-backref" href="#abi-flags" role="doc-backlink"><code class="docutils literal notranslate">abi.flags</code></a></h4> <table class="docutils align-default"> <colgroup> <col style="width: 25.0%" /> <col style="width: 75.0%" /> </colgroup> <tbody> <tr class="row-odd"><td>Type</td> <td><code class="docutils literal notranslate">array</code></td> </tr> <tr class="row-even"><td>Description</td> <td>Build configuration flags, used to calculate the extension suffix.The flags MUST be defined in the order they appear on the extension suffix. </td> </tr> <tr class="row-odd"><td>Examples</td> <td><code class="docutils literal notranslate">['t', 'd']</code>, etc.</td> </tr> <tr class="row-even"><td>Required</td> <td>True</td> </tr> </tbody> </table> </section> <section id="abi-extension-suffix"> <h4><a class="toc-backref" href="#abi-extension-suffix" role="doc-backlink"><code class="docutils literal notranslate">abi.extension_suffix</code></a></h4> <table class="docutils align-default"> <colgroup> <col style="width: 25.0%" /> <col style="width: 75.0%" /> </colgroup> <tbody> <tr class="row-odd"><td>Type</td> <td><code class="docutils literal notranslate">string</code></td> </tr> <tr class="row-even"><td>Description</td> <td>Suffix used for extensions built against the current implementation version.This field MUST be present if the Python implementation supports extensions, otherwise this entry will be missing. </td> </tr> <tr class="row-odd"><td>Examples</td> <td><ul class="simple"> <li><code class="docutils literal notranslate">.cpython-314-x86_64-linux-gnu.so</code></li> <li>etc.</li> </ul> </td> </tr> <tr class="row-even"><td>Required</td> <td>False</td> </tr> </tbody> </table> </section> <section id="abi-stable-abi-suffix"> <h4><a class="toc-backref" href="#abi-stable-abi-suffix" role="doc-backlink"><code class="docutils literal notranslate">abi.stable_abi_suffix</code></a></h4> <table class="docutils align-default"> <colgroup> <col style="width: 25.0%" /> <col style="width: 75.0%" /> </colgroup> <tbody> <tr class="row-odd"><td>Type</td> <td><code class="docutils literal notranslate">string</code></td> </tr> <tr class="row-even"><td>Description</td> <td>Suffix used for extensions built against the <a class="reference external" href="https://docs.python.org/3/c-api/stable.html#stable-abi">stable ABI</a>.This field MUST be present if the Python implementation has a stable ABI extension suffix, otherwise this entry will be missing. </td> </tr> <tr class="row-odd"><td>Examples</td> <td><code class="docutils literal notranslate">.abi3.so</code>, etc.</td> </tr> <tr class="row-even"><td>Required</td> <td>False</td> </tr> </tbody> </table> </section> </section> <section id="suffixes"> <h3><a class="toc-backref" href="#suffixes" role="doc-backlink"><code class="docutils literal notranslate">suffixes</code></a></h3> <table class="docutils align-default"> <colgroup> <col style="width: 25.0%" /> <col style="width: 75.0%" /> </colgroup> <tbody> <tr class="row-odd"><td>Type</td> <td><code class="docutils literal notranslate">object</code></td> </tr> <tr class="row-even"><td>Description</td> <td>Valid module suffixes grouped by type.This section MUST be present if the Python installation supports importing external files, and it SHOULD be equivalent to the <code class="docutils literal notranslate">importlib.machinery.*_SUFFIXES</code> attributes. Additionally, if a Python implementation provides extension kinds other than the ones listed on <code class="docutils literal notranslate">importlib.machinery</code> module, they MAY add a sub-section for them. </td> </tr> <tr class="row-odd"><td>Examples</td> <td><ul class="simple"> <li><code class="docutils literal notranslate">{'source': ['.py'], 'bytecode': ['.pyc'], 'optimized_bytecode': ['.pyc'], 'debug_bytecode': ['.pyc'], 'extensions': ['.cpython-313-x86_64-linux-gnu.so', '.abi3.so', '.so']}</code></li> <li>etc.</li> </ul> </td> </tr> <tr class="row-even"><td>Required</td> <td>False</td> </tr> <tr class="row-odd"><td>Additional properties</td> <td>Allowed</td> </tr> </tbody> </table> </section> <section id="libpython"> <h3><a class="toc-backref" href="#libpython" role="doc-backlink"><code class="docutils literal notranslate">libpython</code></a></h3> <table class="docutils align-default"> <colgroup> <col style="width: 25.0%" /> <col style="width: 75.0%" /> </colgroup> <tbody> <tr class="row-odd"><td>Type</td> <td><code class="docutils literal notranslate">object</code></td> </tr> <tr class="row-even"><td>Description</td> <td>Object containing details related to the <code class="docutils literal notranslate">libpython</code> library.This section MUST by present if Python installation provides a <code class="docutils literal notranslate">libpython</code> library, otherwise this section will be missing. </td> </tr> <tr class="row-odd"><td>Required</td> <td>False</td> </tr> <tr class="row-even"><td>Additional properties</td> <td>Not allowed</td> </tr> </tbody> </table> <section id="libpython-dynamic"> <h4><a class="toc-backref" href="#libpython-dynamic" role="doc-backlink"><code class="docutils literal notranslate">libpython.dynamic</code></a></h4> <table class="docutils align-default"> <colgroup> <col style="width: 25.0%" /> <col style="width: 75.0%" /> </colgroup> <tbody> <tr class="row-odd"><td>Type</td> <td><code class="docutils literal notranslate">string</code></td> </tr> <tr class="row-even"><td>Description</td> <td>The path to the dynamic <code class="docutils literal notranslate">libpython</code> library.Either an absolute path, or a path relative to <code class="docutils literal notranslate">base_prefix</code>. This field MUST be present if the Python installation provides a dynamic <code class="docutils literal notranslate">libpython</code> library, otherwise this entry will be missing. </td> </tr> <tr class="row-odd"><td>Examples</td> <td><ul class="simple"> <li><code class="docutils literal notranslate">/usr/lib/libpython3.14.so.1.0</code></li> <li><code class="docutils literal notranslate">lib/libpython3.14.so.1.0</code></li> <li>etc.</li> </ul> </td> </tr> <tr class="row-even"><td>Required</td> <td>False</td> </tr> </tbody> </table> </section> <section id="libpython-dynamic-stableabi"> <h4><a class="toc-backref" href="#libpython-dynamic-stableabi" role="doc-backlink"><code class="docutils literal notranslate">libpython.dynamic_stableabi</code></a></h4> <table class="docutils align-default"> <colgroup> <col style="width: 25.0%" /> <col style="width: 75.0%" /> </colgroup> <tbody> <tr class="row-odd"><td>Type</td> <td><code class="docutils literal notranslate">string</code></td> </tr> <tr class="row-even"><td>Description</td> <td>The path to the dynamic <code class="docutils literal notranslate">libpython</code> library for the stable ABI.Either an absolute path, or a path relative to <code class="docutils literal notranslate">base_prefix</code>. This field MUST be present if the Python installation provides a dynamic <code class="docutils literal notranslate">libpython</code> library targetting the Stable ABI, otherwise this entry will be missing. If this key is present <code class="docutils literal notranslate">dynamic</code> MUST also be set. </td> </tr> <tr class="row-odd"><td>Examples</td> <td><ul class="simple"> <li><code class="docutils literal notranslate">/usr/lib/libpython3.so</code></li> <li><code class="docutils literal notranslate">lib/libpython3.so</code></li> <li>etc.</li> </ul> </td> </tr> <tr class="row-even"><td>Required</td> <td>False</td> </tr> </tbody> </table> </section> <section id="libpython-static"> <h4><a class="toc-backref" href="#libpython-static" role="doc-backlink"><code class="docutils literal notranslate">libpython.static</code></a></h4> <table class="docutils align-default"> <colgroup> <col style="width: 25.0%" /> <col style="width: 75.0%" /> </colgroup> <tbody> <tr class="row-odd"><td>Type</td> <td><code class="docutils literal notranslate">string</code></td> </tr> <tr class="row-even"><td>Description</td> <td>The path to the static <code class="docutils literal notranslate">libpython</code> library.Either an absolute path, or a path relative to <code class="docutils literal notranslate">base_prefix</code>. This field MUST be present if the Python installation provides a static <code class="docutils literal notranslate">libpython</code> library, otherwise this entry will be missing. </td> </tr> <tr class="row-odd"><td>Examples</td> <td><ul class="simple"> <li><code class="docutils literal notranslate">/usr/lib/python3.14/config-3.14-x86_64-linux-gnu/libpython3.14.a</code></li> <li><code class="docutils literal notranslate">lib/python3.14/config-3.14-x86_64-linux-gnu/libpython3.14.a</code></li> <li>etc.</li> </ul> </td> </tr> <tr class="row-even"><td>Required</td> <td>False</td> </tr> </tbody> </table> </section> <section id="libpython-link-extensions"> <h4><a class="toc-backref" href="#libpython-link-extensions" role="doc-backlink"><code class="docutils literal notranslate">libpython.link_extensions</code></a></h4> <table class="docutils align-default"> <colgroup> <col style="width: 25.0%" /> <col style="width: 75.0%" /> </colgroup> <tbody> <tr class="row-odd"><td>Type</td> <td><code class="docutils literal notranslate">boolean</code></td> </tr> <tr class="row-even"><td>Description</td> <td>Should extensions built against a dynamic <code class="docutils literal notranslate">libpython</code> link to it?This field MUST be present if the Python installation provides a dynamic <code class="docutils literal notranslate">libpython</code> library, otherwise this entry will be missing. </td> </tr> <tr class="row-odd"><td>Required</td> <td>False</td> </tr> </tbody> </table> </section> </section> <section id="c-api"> <h3><a class="toc-backref" href="#c-api" role="doc-backlink"><code class="docutils literal notranslate">c_api</code></a></h3> <table class="docutils align-default"> <colgroup> <col style="width: 25.0%" /> <col style="width: 75.0%" /> </colgroup> <tbody> <tr class="row-odd"><td>Type</td> <td><code class="docutils literal notranslate">object</code></td> </tr> <tr class="row-even"><td>Description</td> <td>Object containing details related to the Python C API.This section MUST be present if the Python implementation provides a C API, otherwise this section will be missing. </td> </tr> <tr class="row-odd"><td>Required</td> <td>False</td> </tr> <tr class="row-even"><td>Additional properties</td> <td>Not allowed</td> </tr> </tbody> </table> <section id="c-api-headers"> <h4><a class="toc-backref" href="#c-api-headers" role="doc-backlink"><code class="docutils literal notranslate">c_api.headers</code></a></h4> <table class="docutils align-default"> <colgroup> <col style="width: 25.0%" /> <col style="width: 75.0%" /> </colgroup> <tbody> <tr class="row-odd"><td>Type</td> <td><code class="docutils literal notranslate">string</code></td> </tr> <tr class="row-even"><td>Description</td> <td>The path to the C API headers.Either an absolute path, or a path relative to <code class="docutils literal notranslate">base_prefix</code>. </td> </tr> <tr class="row-odd"><td>Examples</td> <td><ul class="simple"> <li><code class="docutils literal notranslate">/usr/include/python3.14</code></li> <li><code class="docutils literal notranslate">include/python3.14</code></li> <li>etc.</li> </ul> </td> </tr> <tr class="row-even"><td>Required</td> <td>True</td> </tr> </tbody> </table> </section> <section id="c-api-pkgconfig-path"> <h4><a class="toc-backref" href="#c-api-pkgconfig-path" role="doc-backlink"><code class="docutils literal notranslate">c_api.pkgconfig_path</code></a></h4> <table class="docutils align-default"> <colgroup> <col style="width: 25.0%" /> <col style="width: 75.0%" /> </colgroup> <tbody> <tr class="row-odd"><td>Type</td> <td><code class="docutils literal notranslate">string</code></td> </tr> <tr class="row-even"><td>Description</td> <td>The path to the pkg-config definition files.Either an absolute path, or a path relative to <code class="docutils literal notranslate">base_prefix</code>. This field MUST be present if the Python implementation provides pkg-config definition files, otherwise this section will be missing. </td> </tr> <tr class="row-odd"><td>Examples</td> <td><ul class="simple"> <li><code class="docutils literal notranslate">/usr/lib/pkgconfig</code></li> <li><code class="docutils literal notranslate">lib/pkgconfig</code></li> <li>etc.</li> </ul> </td> </tr> <tr class="row-even"><td>Required</td> <td>False</td> </tr> </tbody> </table> </section> </section> <section id="arbitrary-data"> <h3><a class="toc-backref" href="#arbitrary-data" role="doc-backlink"><code class="docutils literal notranslate">arbitrary_data</code></a></h3> <table class="docutils align-default"> <colgroup> <col style="width: 25.0%" /> <col style="width: 75.0%" /> </colgroup> <tbody> <tr class="row-odd"><td>Type</td> <td><code class="docutils literal notranslate">object</code></td> </tr> <tr class="row-even"><td>Description</td> <td>Object containing extra arbitrary data.This is meant to be used as an escape-hatch, to include any relevant data that is not covered by this specification. Implementations may choose what data to provide in this section. </td> </tr> <tr class="row-odd"><td>Required</td> <td>False</td> </tr> <tr class="row-even"><td>Additional properties</td> <td>Allowed</td> </tr> </tbody> </table> </section> </section> <section id="example"> <h2><a class="toc-backref" href="#example" role="doc-backlink">Example</a></h2> <div class="highlight-json notranslate"><div class="highlight"><pre> 1{ 2 "schema_version": "1.0", 3 "base_prefix": "/usr", 4 "base_interpreter": "/usr/bin/python", 5 "platform": "linux-x86_64", 6 "language": { 7 "version": "3.14", 8 "version_info": { 9 "major": 3, 10 "minor": 14, 11 "micro": 0, 12 "releaselevel": "alpha", 13 "serial": 0 14 } 15 }, 16 "implementation": { 17 "name": "cpython", 18 "version": { 19 "major": 3, 20 "minor": 14, 21 "micro": 0, 22 "releaselevel": "alpha", 23 "serial": 0 24 }, 25 "hexversion": 51249312, 26 "cache_tag": "cpython-314", 27 "_multiarch": "x86_64-linux-gnu" 28 }, 29 "abi": { 30 "flags": ["t", "d"], 31 "extension_suffix": ".cpython-314-x86_64-linux-gnu.so", 32 "stable_abi_suffix": ".abi3.so" 33 }, 34 "suffixes": { 35 "source": [".py"], 36 "bytecode": [".pyc"], 37 "optimized_bytecode": [".pyc"], 38 "debug_bytecode": [".pyc"], 39 "extensions": [".cpython-314-x86_64-linux-gnu.so", ".abi3.so", ".so"] 40 }, 41 "libpython": { 42 "dynamic": "/usr/lib/libpython3.14.so.1.0", 43 "dynamic_stableabi": "/usr/lib/libpython3.so", 44 "static": "/usr/lib/python3.14/config-3.14-x86_64-linux-gnu/libpython3.14.a", 45 "link_extensions": true 46 }, 47 "c_api": { 48 "headers": "/usr/include/python3.14", 49 "pkgconfig_path": "/usr/lib/pkgconfig" 50 } 51} </pre></div> </div> </section> <section id="json-schema"> <h2><a class="toc-backref" href="#json-schema" role="doc-backlink">JSON Schema</a></h2> <div class="highlight-json notranslate"><div class="highlight"><pre> 1{ 2 "$schema": "https://json-schema.org/draft/2020-12/schema", 3 "$id": "https://github.com/python/peps/blob/main/peps/pep-0739/python-build-info-v1.0.schema.json", 4 "type": "object", 5 "title": "build-details.json — a static description file with build details of Python installations", 6 "required": [ 7 "schema_version", 8 "base_prefix", 9 "platform", 10 "language", 11 "implementation" 12 ], 13 "additionalProperties": false, 14 "properties": { 15 "schema_version": { 16 "type": "string", 17 "description": "Schema version.\n\nThis is a string following the format ``<MAJOR>.<MINOR>``, where ``<MAJOR>`` and ``<MINOR>`` are unpaded numbers and represent the **major** and **minor** components of the version. Versions may be arithmetically compared by intrepreting the version string as a decimal number.\n\nFor this specification version, this value is constant and **MUST** be ``1.0``.\n\nFuture versions of this schema **MUST** use a higher version number. Future versions of this schema **MUST NOT** use the same **major** version component as other schema version unless its specification is deemed backwards-compatible with them — it can't change, or extend, any parts of the current specification in such a way as the semantics of the interpreted data differ, or that data valid under the new specification is invalid under the older specification, with the exception of additional properties (errors caused by ``additionalProperties``).", 18 "const": "1.0" 19 }, 20 "base_prefix": { 21 "type": "string", 22 "description": "Base prefix of the Python installation.\n\nEither an absolute path, or a path relative to directory where this file is contained.", 23 "examples": [ 24 "/usr", 25 "../.." 26 ] 27 }, 28 "base_interpreter": { 29 "type": "string", 30 "description": "The path to the Python interprer of the base installation.\n\nEither an absolute path, or a path relative to ``base_prefix``.\n\nThis field **MUST** be present if the installation provides an interpreter executable.", 31 "examples": [ 32 "/usr/bin/python", 33 "bin/python" 34 ] 35 }, 36 "platform": { 37 "type": "string", 38 "description": "System platform string.\n\nThis field **SHOULD** be equivalent to ``sysconfig.get_platform()``.", 39 "examples": [ 40 "linux-x86_64" 41 ] 42 }, 43 "language": { 44 "type": "object", 45 "description": "Object containing details related to the Python language specification.", 46 "required": [ 47 "version" 48 ], 49 "additionalProperties": false, 50 "properties": { 51 "version": { 52 "type": "string", 53 "description": "String representation the Python language version — a version string consisting only of the *major* and *minor* components.\n\nThis field **SHOULD** be equivalent to ``sysconfig.get_python_version()``.", 54 "examples": ["3.14"] 55 }, 56 "version_info": { 57 "type": "object", 58 "description": "Object in the format of :py:data:`sys.version_info`.\n\nThis section **SHOULD** be equivalent to :py:data:`sys.version_info`.", 59 "required": ["major", "minor", "micro", "releaselevel", "serial"], 60 "additionalProperties": false, 61 "examples": [ 62 { 63 "major": 3, 64 "minor": 14, 65 "micro": 1, 66 "releaselevel": "final", 67 "serial": 0 68 } 69 ], 70 "properties": { 71 "major": { 72 "type": "number" 73 }, 74 "minor": { 75 "type": "number" 76 }, 77 "micro": { 78 "type": "number" 79 }, 80 "releaselevel": { 81 "type": "string", 82 "enum": ["alpha", "beta", "candidate", "final"] 83 }, 84 "serial": { 85 "type": "number" 86 } 87 } 88 } 89 } 90 }, 91 "implementation": { 92 "type": "object", 93 "description": "Object containing details related to Python implementation.\n\nThis section **SHOULD** be equivalent to :py:data:`sys.implementation`. It follows specification defined in PEP 421, meaning that on top of the required keys, implementation-specific keys can also exist, but must be prefixed with an underscore.", 94 "required": [ 95 "name", 96 "version", 97 "hexversion", 98 "cache_tag" 99 ], 100 "additionalProperties": true, 101 "properties": { 102 "name": { 103 "type": "string", 104 "description": "Lower-case name of the Python implementation.", 105 "examples": ["cpython", "pypy"] 106 }, 107 "version": { 108 "type": "object", 109 "description": "Object in the format of :py:data:`sys.version_info`, containing the implementation version.", 110 "required": ["major", "minor", "micro", "releaselevel", "serial"], 111 "additionalProperties": false, 112 "examples": [ 113 { 114 "major": 3, 115 "minor": 14, 116 "micro": 1, 117 "releaselevel": "final", 118 "serial": 0 119 }, 120 { 121 "major": 7, 122 "minor": 3, 123 "micro": 16, 124 "releaselevel": "final", 125 "serial": 0 126 } 127 ], 128 "properties": { 129 "major": { 130 "type": "number" 131 }, 132 "minor": { 133 "type": "number" 134 }, 135 "micro": { 136 "type": "number" 137 }, 138 "releaselevel": { 139 "type": "string", 140 "enum": ["alpha", "beta", "candidate", "final"] 141 }, 142 "serial": { 143 "type": "number" 144 } 145 } 146 } 147 } 148 }, 149 "abi": { 150 "type": "object", 151 "description": "Object containing details related to ABI.", 152 "required": [ 153 "flags" 154 ], 155 "additionalProperties": false, 156 "properties": { 157 "flags": { 158 "type": "array", 159 "description": "Build configuration flags, used to calculate the extension suffix.\n\nThe flags **MUST** be defined in the order they appear on the extension suffix.", 160 "additionalProperties": true, 161 "examples": [ 162 ["t", "d"] 163 ] 164 }, 165 "extension_suffix": { 166 "type": "string", 167 "description": "Suffix used for extensions built against the current implementation version.\n\nThis field **MUST** be present if the Python implementation supports extensions, otherwise this entry will be missing.", 168 "examples": [ 169 ".cpython-314-x86_64-linux-gnu.so" 170 ] 171 }, 172 "stable_abi_suffix": { 173 "type": "string", 174 "description": "Suffix used for extensions built against the stable ABI.\n\nThis field **MUST** be present if the Python implementation has a stable ABI extension suffix, otherwise this entry will be missing.", 175 "examples": [ 176 ".abi3.so" 177 ] 178 } 179 } 180 }, 181 "suffixes": { 182 "type": "object", 183 "description": "Valid module suffixes grouped by type.\n\nThis section **MUST** be present if the Python installation supports importing external files, and it **SHOULD** be equivalent to the ``importlib.machinery.*_SUFFIXES`` attributes.\n\nAdditionally, if a Python implementation provides extension kinds other than the ones listed on ``importlib.machinery`` module, they **MAY** add a sub-section for them.", 184 "examples": [ 185 { 186 "source": [".py"], 187 "bytecode": [".pyc"], 188 "optimized_bytecode": [".pyc"], 189 "debug_bytecode": [".pyc"], 190 "extensions": [".cpython-313-x86_64-linux-gnu.so", ".abi3.so", ".so"] 191 } 192 ] 193 }, 194 "libpython": { 195 "type": "object", 196 "description": "Object containing details related to the ``libpython`` library.\n\nThis section **MUST** by present if Python installation provides a ``libpython`` library, otherwise this section will be missing.", 197 "additionalProperties": false, 198 "properties": { 199 "dynamic": { 200 "type": "string", 201 "description": "The path to the dynamic ``libpython`` library.\n\nEither an absolute path, or a path relative to ``base_prefix``.\n\nThis field **MUST** be present if the Python installation provides a dynamic ``libpython`` library, otherwise this entry will be missing.", 202 "examples": [ 203 "/usr/lib/libpython3.14.so.1.0", 204 "lib/libpython3.14.so.1.0" 205 ] 206 }, 207 "dynamic_stableabi": { 208 "type": "string", 209 "description": "The path to the dynamic ``libpython`` library for the stable ABI.\n\nEither an absolute path, or a path relative to ``base_prefix``.\n\nThis field **MUST** be present if the Python installation provides a dynamic ``libpython`` library targetting the Stable ABI, otherwise this entry will be missing.\n\nIf this key is present ``dynamic`` **MUST** also be set.", 210 "examples": [ 211 "/usr/lib/libpython3.so", 212 "lib/libpython3.so" 213 ] 214 }, 215 "static": { 216 "type": "string", 217 "description": "The path to the static ``libpython`` library.\n\nEither an absolute path, or a path relative to ``base_prefix``.\n\nThis field **MUST** be present if the Python installation provides a static ``libpython`` library, otherwise this entry will be missing.", 218 "examples": [ 219 "/usr/lib/python3.14/config-3.14-x86_64-linux-gnu/libpython3.14.a", 220 "lib/python3.14/config-3.14-x86_64-linux-gnu/libpython3.14.a" 221 ] 222 }, 223 "link_extensions": { 224 "type": "boolean", 225 "description": "Should extensions built against a dynamic ``libpython`` link to it?\n\nThis field **MUST** be present if the Python installation provides a dynamic ``libpython`` library, otherwise this entry will be missing." 226 } 227 } 228 }, 229 "c_api": { 230 "type": "object", 231 "description": "Object containing details related to the Python C API.\n\nThis section **MUST** be present if the Python implementation provides a C API, otherwise this section will be missing.", 232 "required": [ 233 "headers" 234 ], 235 "additionalProperties": false, 236 "properties": { 237 "headers": { 238 "type": "string", 239 "description": "The path to the C API headers.\n\nEither an absolute path, or a path relative to ``base_prefix``.", 240 "examples": [ 241 "/usr/include/python3.14", 242 "include/python3.14" 243 ] 244 }, 245 "pkgconfig_path": { 246 "type": "string", 247 "description": "The path to the pkg-config definition files.\n\nEither an absolute path, or a path relative to ``base_prefix``.\n\nThis field **MUST** be present if the Python implementation provides pkg-config definition files, otherwise this section will be missing.", 248 "examples": [ 249 "/usr/lib/pkgconfig", 250 "lib/pkgconfig" 251 ] 252 } 253 } 254 }, 255 "arbitrary_data": { 256 "type": "object", 257 "description": "Object containing extra arbitrary data.\n\nThis is meant to be used as an escape-hatch, to include any relevant data that is not covered by this specification. Implementations may choose what data to provide in this section.", 258 "additionalProperties": true 259 } 260 } 261} </pre></div> </div> </section> <section id="rejected-ideas"> <h2><a class="toc-backref" href="#rejected-ideas" role="doc-backlink">Rejected Ideas</a></h2> <section id="including-environment-specific-data"> <h3><a class="toc-backref" href="#including-environment-specific-data" role="doc-backlink">Including environment-specific data</a></h3> One of the main requests in the discussion of this PEP was the inclusion of other kind of information, such as the <code class="docutils literal notranslate">site-packages</code> path. It is the opinion of the PEP authors that information regarding the Python environment should be provided by a separate file. Including environment-specific data in the config file means that it would be environment-specific, so virtual environments would need their own config file. This is problematic because virtual environments survive updates of the base Python installation, creating the possibily for the static config file to be outdated, and making its data unreliable, which defeats its purpose. The proposed solution, partially implemented in this PEP, is to have a <code class="docutils literal notranslate">build-details.json</code> file, referent to the base Python installation, and a <code class="docutils literal notranslate">environment.json</code> file, referent to the specific environment. With <code class="docutils literal notranslate">build-details.json</code> being part of the Python distribution, when the base Python installation gets updated, <code class="docutils literal notranslate">build-details.json</code> does too, ensuring the static description files are never outdated. </section> </section> <section id="copyright"> <h2><a class="toc-backref" href="#copyright" role="doc-backlink">Copyright</a></h2> This document is placed in the public domain or under the CC0-1.0-Universal license, whichever is more permissive. </section> </section> <hr class="docutils" /> Source: <a class="reference external" href="https://github.com/python/peps/blob/main/peps/pep-0739.rst">https://github.com/python/peps/blob/main/peps/pep-0739.rst</a> Last modified: <a class="reference external" href="https://github.com/python/peps/commits/main/peps/pep-0739.rst">2025-02-07 01:10:57 GMT</a> </article> <nav id="pep-sidebar"> <h2>Contents</h2> <ul> <li><a class="reference internal" href="#abstract">Abstract</a></li> <li><a class="reference internal" href="#rationale">Rationale</a></li> <li><a class="reference internal" href="#scope">Scope</a></li> <li><a class="reference internal" href="#specification">Specification</a></li> <li><a class="reference internal" href="#format">Format</a><ul> <li><a class="reference internal" href="#schema-version"><code class="docutils literal notranslate">schema_version</code></a></li> <li><a class="reference internal" href="#base-prefix"><code class="docutils literal notranslate">base_prefix</code></a></li> <li><a class="reference internal" href="#base-interpreter"><code class="docutils literal notranslate">base_interpreter</code></a></li> <li><a class="reference internal" href="#platform"><code class="docutils literal notranslate">platform</code></a></li> <li><a class="reference internal" href="#language"><code class="docutils literal notranslate">language</code></a><ul> <li><a class="reference internal" href="#language-version"><code class="docutils literal notranslate">language.version</code></a></li> <li><a class="reference internal" href="#language-version-info"><code class="docutils literal notranslate">language.version_info</code></a><ul> <li><a class="reference internal" href="#language-version-info-major"><code class="docutils literal notranslate">language.version_info.major</code></a></li> <li><a class="reference internal" href="#language-version-info-minor"><code class="docutils literal notranslate">language.version_info.minor</code></a></li> <li><a class="reference internal" href="#language-version-info-micro"><code class="docutils literal notranslate">language.version_info.micro</code></a></li> <li><a class="reference internal" href="#language-version-info-releaselevel"><code class="docutils literal notranslate">language.version_info.releaselevel</code></a></li> <li><a class="reference internal" href="#language-version-info-serial"><code class="docutils literal notranslate">language.version_info.serial</code></a></li> </ul> </li> </ul> </li> <li><a class="reference internal" href="#implementation"><code class="docutils literal notranslate">implementation</code></a><ul> <li><a class="reference internal" href="#implementation-name"><code class="docutils literal notranslate">implementation.name</code></a></li> <li><a class="reference internal" href="#implementation-version"><code class="docutils literal notranslate">implementation.version</code></a><ul> <li><a class="reference internal" href="#implementation-version-major"><code class="docutils literal notranslate">implementation.version.major</code></a></li> <li><a class="reference internal" href="#implementation-version-minor"><code class="docutils literal notranslate">implementation.version.minor</code></a></li> <li><a class="reference internal" href="#implementation-version-micro"><code class="docutils literal notranslate">implementation.version.micro</code></a></li> <li><a class="reference internal" href="#implementation-version-releaselevel"><code class="docutils literal notranslate">implementation.version.releaselevel</code></a></li> <li><a class="reference internal" href="#implementation-version-serial"><code class="docutils literal notranslate">implementation.version.serial</code></a></li> </ul> </li> </ul> </li> <li><a class="reference internal" href="#abi"><code class="docutils literal notranslate">abi</code></a><ul> <li><a class="reference internal" href="#abi-flags"><code class="docutils literal notranslate">abi.flags</code></a></li> <li><a class="reference internal" href="#abi-extension-suffix"><code class="docutils literal notranslate">abi.extension_suffix</code></a></li> <li><a class="reference internal" href="#abi-stable-abi-suffix"><code class="docutils literal notranslate">abi.stable_abi_suffix</code></a></li> </ul> </li> <li><a class="reference internal" href="#suffixes"><code class="docutils literal notranslate">suffixes</code></a></li> <li><a class="reference internal" href="#libpython"><code class="docutils literal notranslate">libpython</code></a><ul> <li><a class="reference internal" href="#libpython-dynamic"><code class="docutils literal notranslate">libpython.dynamic</code></a></li> <li><a class="reference internal" href="#libpython-dynamic-stableabi"><code class="docutils literal notranslate">libpython.dynamic_stableabi</code></a></li> <li><a class="reference internal" href="#libpython-static"><code class="docutils literal notranslate">libpython.static</code></a></li> <li><a class="reference internal" href="#libpython-link-extensions"><code class="docutils literal notranslate">libpython.link_extensions</code></a></li> </ul> </li> <li><a class="reference internal" href="#c-api"><code class="docutils literal notranslate">c_api</code></a><ul> <li><a class="reference internal" href="#c-api-headers"><code class="docutils literal notranslate">c_api.headers</code></a></li> <li><a class="reference internal" href="#c-api-pkgconfig-path"><code class="docutils literal notranslate">c_api.pkgconfig_path</code></a></li> </ul> </li> <li><a class="reference internal" href="#arbitrary-data"><code class="docutils literal notranslate">arbitrary_data</code></a></li> </ul> </li> <li><a class="reference internal" href="#example">Example</a></li> <li><a class="reference internal" href="#json-schema">JSON Schema</a></li> <li><a class="reference internal" href="#rejected-ideas">Rejected Ideas</a><ul> <li><a class="reference internal" href="#including-environment-specific-data">Including environment-specific data</a></li> </ul> </li> <li><a class="reference internal" href="#copyright">Copyright</a></li> </ul> <a id="source" href="https://github.com/python/peps/blob/main/peps/pep-0739.rst">Page Source (GitHub)</a> </nav> </section> <script src="../_static/colour_scheme.js"></script> <script src="../_static/wrap_tables.js"></script> <script src="../_static/sticky_banner.js"></script> </body> </html>