stairwaytowonderland/cpython repository overview

⁠Quick Reference

• Maintained by:
  Andrew Haller⁠
• License:
  MIT⁠

⁠Supported tags and respective Docker Hub links

Tags follow the format <python-version>[-<variant(ext|perf)>][-<base-image-ref>].

⁠Standard Images

⁠Hardened Images

⁠Quick reference (cont.)

• Source Dockerfile:
  github.com/stairwaytowonderland/cpython/blob/main/docker/Dockerfile⁠

• GitHub Repository:
  github.com/stairwaytowonderland/cpython⁠

• Docker Hub:
  stairwaytowonderland/cpython⁠

• Base Images:
  All images are built on top of Debian-based base images. The default base is ubuntu:latest.

  ℹ️ Note: The Dockerfile requires a Debian-based image. Other Debian-derived distributions may be used via the IMAGE_NAME and VARIANT build arguments.

  Base Image	Variant
  dhi	bookworm-debian12-dev
  ubuntu	latest
  debian	bookworm-slim

• Supported architectures:
  linux/amd64, linux/arm64

• Source of this description:
  docs⁠

⁠What is this project?

A self-maintained Python Docker image that builds CPython⁠ from source on top of a Debian-based (Debian or Ubuntu) base image. Designed for use as a lightweight, customizable Python runtime in container-based workflows.

Inspired by a personal desire for a production-grade, Ubuntu-based Python "base" image.

⁠How to use this image

⁠Using in a Dockerfile

Use one of the published images as a base for your own application image:

FROM stairwaytowonderland/cpython:3

WORKDIR /usr/src/myapp

COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY . .

CMD [ "python", "./your-daemon-or-script.py" ]

⁠Building the image

Clone the repository and use the provided build script from the project root:

# Build with the default Python version (latest) targeting the base stage
./docker/bin/build.sh cpython .

# Build a specific Python version
./docker/bin/build.sh cpython \
  --build-arg PYTHON_VERSION=3.14 \
  .

# Build with PGO optimizations enabled
./docker/bin/build.sh cpython \
  --build-arg PYTHON_VERSION=3.14 \
  --build-arg ENABLE_OPTIMIZATIONS=true \
  .

Or build directly with docker build:

docker build \
  --build-arg PYTHON_VERSION=3.14 \
  --target base \
  -t cpython:3.14-ubuntu \
  -f docker/Dockerfile \
  .

⁠Running a Python command

Run a one-off Python command using the image:

docker run --rm stairwaytowonderland/cpython:3.14-ubuntu python3 --version

Run an interactive Python shell:

docker run -it --rm stairwaytowonderland/cpython:3.14-ubuntu python3

⁠Running a single Python script

docker run --rm \
  -v "$(pwd)":/usr/src/myapp \
  -w /myapp \
  stairwaytowonderland/cpython:3.14-ubuntu \
  python3 your-daemon-or-script.py

⁠Image Variants - Standard

⁠cpython:<version>-ubuntu

This is the defacto image. Built on ubuntu:latest⁠. Ubuntu is a widely used, well-supported Debian-based distribution with a large package ecosystem. This is the default base image and a good general-purpose choice for most workloads.

⁠cpython:<version>-bookworm-slim

Built on debian:bookworm-slim⁠. Debian Bookworm Slim is a minimal Debian 12 image that strips non-essential packages to reduce the image footprint. A good choice when image size is a priority and Ubuntu-specific tooling is not required.

⁠cpython:<version>-perf-<base-image-ref>

A performance-optimized build with Profile-Guided Optimization (PGO)⁠ enabled (ENABLE_OPTIMIZATIONS=true). PGO uses runtime profiling data collected during the build to produce a faster CPython binary. Recommended for production workloads where CPU performance matters. Available for both ubuntu and bookworm-slim base variants.

⁠cpython:<version>-ext-<base-image-ref>

A development-oriented build with extended tooling included (PYTHON_DEV=true). Intended for use in development environments and dev containers where additional build tools and libraries may be needed. Available for both ubuntu and bookworm-slim base variants.

⁠Image Variants - Hardened (DHI)

⁠cpython:<version>-bookworm-debian12-dev

Built on dhi.io/debian-base:bookworm-debian12-dev⁠. This is the default base image for this project — a custom Debian 12 (Bookworm) base image maintained by dhi.io⁠, purpose-built for Debian-based container workflows. It provides a curated, dev-friendly foundation with common tooling pre-installed, making it well-suited for both development and CI environments.

⁠License

This project is licensed under the GPL-3.0 License⁠ — free to use, modify, and distribute with attribution and original copyright notices.

See the LICENSE⁠ file for the full license text.