python-build-standalone

the python-build-standalone project produces highly portable, self-contained python distributions. originally created by gregory szorc, the project is now maintained by astral, the company behind uv and ruff. these builds are designed to run on a wide variety of systems with minimal runtime dependencies, making them ideal for embedding, ci/cd pipelines, and consistent development environments.

this project is the source of the python builds used by uv for its uv python management commands.

• github repository: github.com/astral-sh/python-build-standalone
• official documentation: gregoryszorc.com/docs/python-build-standalone

key features

• portability: built to run on almost any machine of the target architecture and os (e.g., x86_64 linux, aarch64 macos).
• self-contained: the entire python standard library, including pip, is included in a single directory.
• multiple variants: provides different builds based on:
  • c library (glibc, musl)
  • build optimizations (pgo, lto)
  • debug symbols
• up-to-date: tracks cpython main and stable branches, often providing builds of unreleased versions.

use cases

• ci/cd pipelines: quickly fetch a specific, consistent python version for build and test jobs without relying on system-installed pythons.
• development environments: used by tools like uv to provide a reliable way to install and manage python versions locally.
• application bundling: embed a known python interpreter with an application to eliminate environment-related bugs.
• testing and experimentation: easily test code against upcoming or development versions of python without compiling from source.

integration with uv

uv uses python-build-standalone as its source for python distributions. when you run uv python install 3.13, uv downloads, verifies, and installs the appropriate build from this project for your platform. this integration provides a fast and reliable way to manage python versions.

manual usage

while uv is the recommended interface, the builds can be downloaded and used manually.

linux (x86_64 with glibc)

# download the pgo+lto optimized build for python 3.13.5
curl -L -O https://github.com/astral-sh/python-build-standalone/releases/download/20250801/cpython-3.13.5+20250801-x86_64-unknown-linux-gnu-install_pgo+lto.tar.zst

# decompress the archive
tar -xvf cpython-3.13.5+20250801-x86_64-unknown-linux-gnu-install_pgo+lto.tar.zst

# run python
./python/bin/python3.13 --version
# output: python 3.13.5

macos (apple silicon)

# download the pgo+lto optimized build for python 3.13.5
curl -L -O https://github.com/astral-sh/python-build-standalone/releases/download/20250801/cpython-3.13.5+20250801-aarch64-apple-darwin-install_pgo+lto.tar.zst

# decompress
tar -xvf cpython-3.13.5+20250801-aarch64-apple-darwin-install_pgo+lto.tar.zst

# run python
./python/bin/python3.13 --version
# output: python 3.13.5

build variants

release files use a detailed naming convention: cpython-{version}+{timestamp}-{arch}-{platform}-{flavor}.tar.zst.

• flavor: describes the build configuration.

  • install_pgo+lto: recommended for production. profile-guided optimization and link-time optimization for maximum performance.
  • install_debug: includes debug symbols, useful for debugging c extensions.
  • install_shared: builds python as a shared library (libpython).

• platform: the target operating system and c library.

  • unknown-linux-gnu: linux with glibc.
  • unknown-linux-musl: linux with musl (for alpine).
  • apple-darwin: macos.
  • pc-windows-msvc: windows.