Skip to main content
Version: 2.25 (dev)

python-build-standalone-python-provider

A subsystem for Pants-provided Python leveraging Python Build Standalone (or PBS) (https://gregoryszorc.com/docs/python-build-standalone/main/).

Enabling this subsystem will switch Pants from trying to find an appropriate Python on your system to using PBS to download the correct Python(s).

The Pythons provided by PBS will be used to run any "user" code (your Python code as well as any Python-based tools you use, like black or pylint). The Pythons are also read-only to ensure they remain hermetic across runs of different tools and code.

The Pythons themselves are stored in your named_caches_dir: https://www.pantsbuild.org/docs/reference-global#named_caches_dir under python_build_standalone/<version>. Wiping the relevant version directory (with sudo rm -rf) will force a re-download of Python.

WARNING: PBS does have some behavior quirks, most notably that it has some hardcoded references to build-time paths (such as constants that are found in the sysconfig module). These paths may be used when trying to compile some extension modules from source.

For more info, see https://gregoryszorc.com/docs/python-build-standalone/main/quirks.html.

Backend: pants.backend.python.providers.experimental.python_build_standalone

Config section: [python-build-standalone-python-provider]

Basic options​

release_constraints​

--python-build-standalone-python-provider-release-constraints=<str>
PANTS_PYTHON_BUILD_STANDALONE_PYTHON_PROVIDER_RELEASE_CONSTRAINTS
pants.toml
[python-build-standalone-python-provider]
release_constraints = <str>
default: None

Version constraints on the PBS "release" version to ensure only matching PBS releases are considered. Constraints should be specfied using operators like >=, <=, >, <, ==, or != in a similar manner to Python interpreter constraints: e.g., >=20241201 or >=20241201,<20250101.

Advanced options​

known_python_versions​

--python-build-standalone-python-provider-known-python-versions="['<str>', '<str>', ...]"
PANTS_PYTHON_BUILD_STANDALONE_PYTHON_PROVIDER_KNOWN_PYTHON_VERSIONS
pants.toml
[python-build-standalone-python-provider]
known_python_versions = [
    '<str>',
    '<str>',
    ...,
]
default: <Metadata for versions: 3.10.11, 3.10.12, 3.10.13, 3.10.14, 3.10.15, 3.10.16, 3.10.2, 3.10.3, 3.10.4, 3.10.5, 3.10.6, 3.10.7, 3.10.8, 3.10.9, 3.11.1, 3.11.10, 3.11.11, 3.11.3, 3.11.4, 3.11.5, 3.11.6, 3.11.7, 3.11.8, 3.11.9, 3.12.0, 3.12.1, 3.12.2, 3.12.3, 3.12.4, 3.12.5, 3.12.6, 3.12.7, 3.12.8, 3.13.0, 3.13.1, 3.8.12, 3.8.13, 3.8.14, 3.8.15, 3.8.16, 3.8.17, 3.8.18, 3.8.19, 3.8.20, 3.9.10, 3.9.11, 3.9.12, 3.9.13, 3.9.14, 3.9.15, 3.9.16, 3.9.17, 3.9.18, 3.9.19, 3.9.20, 3.9.21>

Known versions to verify downloads against.

Each element is a pipe-separated string of version|platform|sha256|length|url, where:

  • version is the version string
  • platform is one of [linux_arm64,linux_x86_64,macos_arm64,macos_x86_64]
  • sha256 is the 64-character hex representation of the expected sha256 digest of the download file, as emitted by shasum -a 256
  • length is the expected length of the download file in bytes, as emitted by wc -c
  • url is the download URL to the .tar.gz archive

E.g., 3.1.2|macos_x86_64|6d0f18cd84b918c7b3edd0203e75569e0c7caecb1367bbbe409b44e28514f5be|42813|https://<URL>.

Values are space-stripped, so pipes can be indented for readability if necessary.

Additionally, any versions you specify here will override the default Pants metadata for that version.

require_inferrable_release_tag​

--[no-]python-build-standalone-python-provider-require-inferrable-release-tag
PANTS_PYTHON_BUILD_STANDALONE_PYTHON_PROVIDER_REQUIRE_INFERRABLE_RELEASE_TAG
pants.toml
[python-build-standalone-python-provider]
require_inferrable_release_tag = <bool>
default: False

Normally, Pants will try to infer the PBS release "tag" from URLs supplied to the --python-build-standalone-known-python-versions option. If this option is True, then it is an error if Pants cannot infer the tag from the URL.

Deprecated options​

None

None