build-details.json 1.0 — a static description file for Python build detailsThis PEP introducesbuild-details.json, a static description file containingbuild details of Python installations.
It includes the definition of version 1.0 of the file format, and defines thestandard location for this file.
When introspecting a Python installation, running code is often undesirable orimpossible. Having a static description file makes various build details of thePython installation available without having to run the interpreter.
This is helpful for use-cases such as cross-compilation, Python launchers, etc.
build-details.json is an installation-wide file, meaning that itMUSTonly contain information that is constant across all environments of the Pythoninstallation.
Information specific to a Python environment, such as thesite-packagespath, is outside the scope for this file, and the PEP authors expect that astatic environment description file will be introduced via a future PEP.
Starting from Python 3.14, a file namedbuild-details.json following theformat specified in this PEP, or a future version,MUST be installed in theplatform-independent standard library directory (stdlib, eg./usr/lib/python3.14/build-details.json),UNLESS unfeasible due totechnical limitations.
Attention
In addition to the standard location specified by this PEP, thebuild-details.json fileMAY also be installed intoadditionallocations, and under a different name. Notwithstanding, the fileSHOULDstill be available at the standard location.
In actuality, the PEP authors expect future PEPs to define additionalinstall locations with better discoverability.
The format specification is defined by the JSON Schema definition providedbelow, which is rendered in an human-readable format here.
$schema | https://json-schema.org/draft/2020-12/schema |
$id | https://github.com/python/peps/blob/main/peps/pep-0739/python-build-info-v1.0.schema.json |
| Title | build-details.json — a static description file with builddetails of Python installations |
| Type | object |
| Additional properties | Not allowed |
schema_version| Type | string (constant —1.0) |
| Description | Schema version. This is a string following the format For this specification version, this value is constant andMUST be Future versions of this schemaMUST use a higher versionnumber. Future versions of this schemaMUST NOT use the samemajor version component as other schema version unless itsspecification is deemed backwards-compatible with them — itcan’t change, or extend, any parts of the current specificationin such a way as the semantics of the interpreted data differ,or that data valid under the new specification is invalid underthe older specification, with the exception of additionalproperties (errors caused by |
| Required | True |
base_prefix| Type | string |
| Description | Base prefix of the Python installation. Either an absolute path, or a path relative to directory wherethis file is contained. |
| Examples | /usr,../.., etc. |
| Required | True |
base_interpreter| Type | string |
| Description | The path to the Python interpreter of the base installation. Either an absolute path, or a path relative to This fieldMUST be present if the installation provides aninterpreter executable. |
| Examples |
|
| Required | False |
platform| Type | string |
| Description | System platform string. This fieldSHOULD be equivalent to |
| Examples |
|
| Required | True |
language| Type | object |
| Description | Object containing details related to the Python languagespecification. |
| Required | True |
| Additional properties | Not allowed |
language.version| Type | string |
| Description | String representation the Python language version — a versionstring consisting only of themajor andminor components. This fieldSHOULD be equivalent to |
| Examples | 3.14, etc. |
| Required | True |
language.version_info| Type | object |
| Description | Object in the format ofsys.version_info.This sectionSHOULD be equivalent to |
| Examples |
|
| Required | False |
| Additional properties | Not allowed |
language.version_info.major| Type | number |
| Required | True |
language.version_info.minor| Type | number |
| Required | True |
language.version_info.micro| Type | number |
| Required | True |
language.version_info.releaselevel| Type | string (enum —alpha,beta,candidate,final) |
| Required | True |
language.version_info.serial| Type | number |
| Required | True |
implementation| Type | object |
| Description | Object containing details related to the Python implementation. This sectionSHOULD be equivalent to |
| Required | True |
| Additional properties | Allowed |
implementation.name| Type | string |
| Description | Lower-case name of the Python implementation. |
| Examples | cpython,pypy, etc. |
| Required | True |
implementation.version| Type | object |
| Description | Object in the format ofsys.version_info, containingthe implementation version. |
| Examples |
|
| Required | True |
| Additional properties | Not allowed |
implementation.version.major| Type | number |
| Required | True |
implementation.version.minor| Type | number |
| Required | True |
implementation.version.micro| Type | number |
| Required | True |
implementation.version.releaselevel| Type | string (enum —alpha,beta,candidate,final) |
| Required | True |
implementation.version.serial| Type | number |
| Required | True |
abi| Type | object |
| Description | Object containing details related to ABI. |
| Required | False |
| Additional properties | Not allowed |
abi.flags| Type | array |
| Description | Build configuration flags, used to calculate the extensionsuffix. The flagsMUST be defined in the order they appear on theextension suffix. |
| Examples | ['t','d'], etc. |
| Required | True |
abi.extension_suffix| Type | string |
| Description | Suffix used for extensions built against the currentimplementation version. This fieldMUST be present if the Python implementationsupports extensions, otherwise this entry will be missing. |
| Examples |
|
| Required | False |
abi.stable_abi_suffix| Type | string |
| Description | Suffix used for extensions built against thestable ABI. This fieldMUST be present if the Python implementation hasa stable ABI extension suffix, otherwise this entry will bemissing. |
| Examples | .abi3.so, etc. |
| Required | False |
suffixes| Type | object |
| Description | Valid module suffixes grouped by type. This sectionMUST be present if the Python installationsupports importing external files, and itSHOULD beequivalent to the Additionally, if a Python implementation provides extensionkinds other than the ones listed on |
| Examples |
|
| Required | False |
| Additional properties | Allowed |
libpython| Type | object |
| Description | Object containing details related to thelibpython library.This sectionMUST by present if Python installation providesa |
| Required | False |
| Additional properties | Not allowed |
libpython.dynamic| Type | string |
| Description | The path to the dynamiclibpython library.Either an absolute path, or a path relative to This fieldMUST be present if the Python installationprovides a dynamic |
| Examples |
|
| Required | False |
libpython.dynamic_stableabi| Type | string |
| Description | The path to the dynamiclibpython library for the stableABI.Either an absolute path, or a path relative to This fieldMUST be present if the Python installationprovides a dynamic If this key is present |
| Examples |
|
| Required | False |
libpython.static| Type | string |
| Description | The path to the staticlibpython library.Either an absolute path, or a path relative to This fieldMUST be present if the Python installationprovides a static |
| Examples |
|
| Required | False |
libpython.link_extensions| Type | boolean |
| Description | Should extensions built against a dynamiclibpython link toit?This fieldMUST be present if the Python installationprovides a dynamic |
| Required | False |
c_api| Type | object |
| Description | Object containing details related to the Python C API. This sectionMUST be present if the Python implementationprovides a C API, otherwise this section will be missing. |
| Required | False |
| Additional properties | Not allowed |
c_api.headers| Type | string |
| Description | The path to the C API headers. Either an absolute path, or a path relative to |
| Examples |
|
| Required | True |
c_api.pkgconfig_path| Type | string |
| Description | The path to the pkg-config definition files. Either an absolute path, or a path relative to This fieldMUST be present if the Python implementationprovides pkg-config definition files, otherwise this sectionwill be missing. |
| Examples |
|
| Required | False |
arbitrary_data| Type | object |
| Description | Object containing extra arbitrary data. This is meant to be used as an escape-hatch, to include anyrelevant data that is not covered by this specification.Implementations may choose what data to provide in this section. |
| Required | False |
| Additional properties | Allowed |
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":014}15},16"implementation":{17"name":"cpython",18"version":{19"major":3,20"minor":14,21"micro":0,22"releaselevel":"alpha",23"serial":024},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":true46},47"c_api":{48"headers":"/usr/include/python3.14",49"pkgconfig_path":"/usr/lib/pkgconfig"50}51}
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":0119},120{121"major":7,122"minor":3,123"micro":16,124"releaselevel":"final",125"serial":0126}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":true259}260}261}
One of the main requests in the discussion of this PEP was the inclusion ofother kind of information, such as thesite-packages path. It is the opinionof the PEP authors that information regarding the Python environment should beprovided by a separate file.
Including environment-specific data in the config file means that it would beenvironment-specific, so virtual environments would need their own config file.This is problematic because virtual environments survive updates of the basePython installation, creating the possibily for the static config file to beoutdated, and making its data unreliable, which defeats its purpose.
The proposed solution, partially implemented in this PEP, is to have abuild-details.json file, referent to the base Python installation, and aenvironment.json file, referent to the specific environment.
Withbuild-details.json being part of the Python distribution, when the basePython installation gets updated,build-details.json does too, ensuring thestatic description files are never outdated.
This document is placed in the public domain or under theCC0-1.0-Universal license, whichever is more permissive.
Source:https://github.com/python/peps/blob/main/peps/pep-0739.rst
Last modified:2025-02-07 01:10:57 GMT