# astral-sh/python-build-standalone architecture

> Architecture diagram of the GitHub repository astral-sh/python-build-standalone, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/astral-sh/python-build-standalone
- Repository: https://github.com/astral-sh/python-build-standalone

## Overview

Python Build Standalone builds portable CPython distributions for supported versions, platforms, architectures, and build variants. The principal workflow is a platform-specific build driver coordinating CPython configuration, dependencies, and build environments to produce archives; distribution tests and a Rust CLI for validation and release handling support those artifacts. The graph follows README capabilities and SOURCE INDEX references. Some runtime dispatch details and unsampled subsystems are not shown, so their links are omitted rather than inferred.

Main entry points: [`cpython-unix/build.py`](https://github.com/astral-sh/python-build-standalone/blob/main/cpython-unix/build.py) (Unix builds), [`src/main.rs`](https://github.com/astral-sh/python-build-standalone/blob/main/src/main.rs) (Artifact CLI), [`cpython-windows/build.py`](https://github.com/astral-sh/python-build-standalone/blob/main/cpython-windows/build.py) (Windows builds), [`pythonbuild/cpython.py`](https://github.com/astral-sh/python-build-standalone/blob/main/pythonbuild/cpython.py) (CPython configuration)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_build["Distribution builds"]
  node_unix_build["Unix builds<br/>[build.py]"]
  node_windows_build["Windows builds<br/>[build.py]"]
  node_build_main["Unix build orchestration<br/>[build-main.py]"]
  node_distribution["Python distributions<br/>[build.py]"]
end

subgraph group_support["Build support"]
  node_cpython_config["CPython configuration<br/>[cpython.py]"]
  node_build_environment["Build environments<br/>[buildenv.py]"]
  node_docker["Docker images<br/>[docker.py]"]
  node_downloads["Dependency catalog<br/>[downloads.py]"]
  node_build_utils["Build utilities<br/>[utils.py]"]
end

subgraph group_quality["Artifact quality"]
  node_distribution_tests["Distribution tests<br/>[testdist.py]"]
end

subgraph group_release["Validation and release"]
  node_rust_cli["Artifact CLI<br/>[main.rs]"]
  node_validation["Artifact validation<br/>[validation.rs]"]
  node_macho["Mach-O inspection<br/>[macho.rs]"]
  node_json["Metadata JSON<br/>[json.rs]"]
  node_release_ops["Release packaging<br/>[release.rs]"]
  node_github["GitHub operations<br/>[github.rs]"]
  node_github_api_tester["GitHub API tester"]
end

node_developer(("Build operator"))
node_uv(("uv users"))
node_github_releases["GitHub Releases"]

node_developer -->|"starts build"| node_unix_build
node_developer -->|"starts build"| node_windows_build
node_unix_build -->|"delegates to"| node_build_main
node_unix_build -->|"uses"| node_cpython_config
node_unix_build -->|"creates"| node_build_environment
node_unix_build -->|"uses"| node_docker
node_unix_build -->|"uses"| node_downloads
node_windows_build -->|"uses"| node_cpython_config
node_windows_build -->|"uses"| node_downloads
node_build_main -->|"uses"| node_cpython_config
node_build_main -->|"uses"| node_downloads
node_build_environment -->|"uses"| node_docker
node_unix_build -->|"produces"| node_distribution
node_windows_build -->|"produces"| node_distribution
node_distribution_tests -->|"uses"| node_cpython_config
node_developer -->|"runs commands"| node_rust_cli
node_rust_cli -->|"uses"| node_validation
node_rust_cli -->|"uses"| node_macho
node_rust_cli -->|"uses"| node_json
node_rust_cli -->|"uses"| node_release_ops
node_rust_cli -->|"uses"| node_github
node_validation -->|"uses"| node_json
node_validation -->|"uses"| node_macho
node_release_ops -->|"uses"| node_json
node_github -->|"uses"| node_release_ops
node_rust_cli -->|"uploads artifacts"| node_github_releases
node_uv -->|"installs"| node_distribution

click node_unix_build "https://github.com/astral-sh/python-build-standalone/blob/main/cpython-unix/build.py"
click node_windows_build "https://github.com/astral-sh/python-build-standalone/blob/main/cpython-windows/build.py"
click node_build_main "https://github.com/astral-sh/python-build-standalone/blob/main/cpython-unix/build-main.py"
click node_cpython_config "https://github.com/astral-sh/python-build-standalone/blob/main/pythonbuild/cpython.py"
click node_build_environment "https://github.com/astral-sh/python-build-standalone/blob/main/pythonbuild/buildenv.py"
click node_docker "https://github.com/astral-sh/python-build-standalone/blob/main/pythonbuild/docker.py"
click node_downloads "https://github.com/astral-sh/python-build-standalone/blob/main/pythonbuild/downloads.py"
click node_build_utils "https://github.com/astral-sh/python-build-standalone/blob/main/pythonbuild/utils.py"
click node_distribution "https://github.com/astral-sh/python-build-standalone/blob/main/cpython-unix/build.py"
click node_distribution_tests "https://github.com/astral-sh/python-build-standalone/blob/main/pythonbuild/testdist.py"
click node_rust_cli "https://github.com/astral-sh/python-build-standalone/blob/main/src/main.rs"
click node_validation "https://github.com/astral-sh/python-build-standalone/blob/main/src/validation.rs"
click node_macho "https://github.com/astral-sh/python-build-standalone/blob/main/src/macho.rs"
click node_json "https://github.com/astral-sh/python-build-standalone/blob/main/src/json.rs"
click node_release_ops "https://github.com/astral-sh/python-build-standalone/blob/main/src/release.rs"
click node_github "https://github.com/astral-sh/python-build-standalone/blob/main/src/github.rs"
click node_github_api_tester "https://github.com/astral-sh/python-build-standalone/blob/main/src/github_api_tester.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_unix_build,node_windows_build,node_build_main,node_distribution,node_uv toneBlue
class node_cpython_config,node_build_environment,node_docker,node_downloads,node_build_utils toneAmber
class node_distribution_tests toneMint
class node_rust_cli,node_validation,node_macho,node_json,node_release_ops,node_github,node_github_api_tester toneRose
class node_developer,node_github_releases toneIndigo
```

## Components

### Distribution builds

- [Unix builds](https://github.com/astral-sh/python-build-standalone/blob/main/cpython-unix/build.py): `cpython-unix/build.py`
- [Windows builds](https://github.com/astral-sh/python-build-standalone/blob/main/cpython-windows/build.py): `cpython-windows/build.py`
- [Unix build orchestration](https://github.com/astral-sh/python-build-standalone/blob/main/cpython-unix/build-main.py): `cpython-unix/build-main.py`
- [Python distributions](https://github.com/astral-sh/python-build-standalone/blob/main/cpython-unix/build.py): `cpython-unix/build.py`

### Build support

- [CPython configuration](https://github.com/astral-sh/python-build-standalone/blob/main/pythonbuild/cpython.py): `pythonbuild/cpython.py`
- [Build environments](https://github.com/astral-sh/python-build-standalone/blob/main/pythonbuild/buildenv.py): `pythonbuild/buildenv.py`
- [Docker images](https://github.com/astral-sh/python-build-standalone/blob/main/pythonbuild/docker.py): `pythonbuild/docker.py`
- [Dependency catalog](https://github.com/astral-sh/python-build-standalone/blob/main/pythonbuild/downloads.py): `pythonbuild/downloads.py`
- [Build utilities](https://github.com/astral-sh/python-build-standalone/blob/main/pythonbuild/utils.py): `pythonbuild/utils.py`

### Artifact quality

- [Distribution tests](https://github.com/astral-sh/python-build-standalone/blob/main/pythonbuild/testdist.py): `pythonbuild/testdist.py`

### Validation and release

- [Artifact CLI](https://github.com/astral-sh/python-build-standalone/blob/main/src/main.rs): `src/main.rs`
- [Artifact validation](https://github.com/astral-sh/python-build-standalone/blob/main/src/validation.rs): `src/validation.rs`
- [Mach-O inspection](https://github.com/astral-sh/python-build-standalone/blob/main/src/macho.rs): `src/macho.rs`
- [Metadata JSON](https://github.com/astral-sh/python-build-standalone/blob/main/src/json.rs): `src/json.rs`
- [Release packaging](https://github.com/astral-sh/python-build-standalone/blob/main/src/release.rs): `src/release.rs`
- [GitHub operations](https://github.com/astral-sh/python-build-standalone/blob/main/src/github.rs): `src/github.rs`
- [GitHub API tester](https://github.com/astral-sh/python-build-standalone/blob/main/src/github_api_tester.py): `src/github_api_tester.py`

### Other components

- **Build operator**
- **uv users**
- **GitHub Releases**

## Connections

- Build operator → Unix builds: starts build (evidence: `README.md`)
- Build operator → Windows builds: starts build (evidence: `README.md`)
- Unix builds → Unix build orchestration: delegates to (evidence: `cpython-unix/build.py`)
- Unix builds → CPython configuration: uses (evidence: `cpython-unix/build.py`)
- Unix builds → Build environments: creates (evidence: `cpython-unix/build.py`)
- Unix builds → Docker images: uses (evidence: `cpython-unix/build.py`)
- Unix builds → Dependency catalog: uses (evidence: `cpython-unix/build.py`)
- Windows builds → CPython configuration: uses (evidence: `cpython-windows/build.py`)
- Windows builds → Dependency catalog: uses (evidence: `cpython-windows/build.py`)
- Unix build orchestration → CPython configuration: uses (evidence: `cpython-unix/build-main.py`)
- Unix build orchestration → Dependency catalog: uses (evidence: `cpython-unix/build-main.py`)
- Build environments → Docker images: uses (evidence: `pythonbuild/buildenv.py`)
- Unix builds → Python distributions: produces (evidence: `README.md`)
- Windows builds → Python distributions: produces (evidence: `README.md`)
- Distribution tests → CPython configuration: uses (evidence: `pythonbuild/testdist.py`)
- Build operator → Artifact CLI: runs commands (evidence: `src/main.rs`)
- Artifact CLI → Artifact validation: uses (evidence: `src/main.rs`)
- Artifact CLI → Mach-O inspection: uses (evidence: `src/main.rs`)
- Artifact CLI → Metadata JSON: uses (evidence: `src/main.rs`)
- Artifact CLI → Release packaging: uses (evidence: `src/main.rs`)
- Artifact CLI → GitHub operations: uses (evidence: `src/main.rs`)
- Artifact validation → Metadata JSON: uses (evidence: `src/validation.rs`)
- Artifact validation → Mach-O inspection: uses (evidence: `src/validation.rs`)
- Release packaging → Metadata JSON: uses (evidence: `src/release.rs`)
- GitHub operations → Release packaging: uses (evidence: `src/github.rs`)
- Artifact CLI → GitHub Releases: uploads artifacts (evidence: `src/main.rs`)
- uv users → Python distributions: installs (evidence: `README.md`)
