Hardened, reproducible Python base images: runtime, development, builder and cli. Non-root.
10K+
Hardened, reproducible Python base images. One Dockerfile per upstream version ships four targets: the production
runtime, its development variant, the builder for a project's production build, and a cli tooling image a
project Makefile invokes.
ghcr.io/gustavofreze/pythonlinux/amd64, linux/arm64| Tag | Alias | Purpose |
|---|---|---|
3.14-runtime-1.0.12 | 3.14-runtime | Production interpreter. No compiler, no installer, no Poetry. |
3.14-development-1.0.12 | 3.14-development | Local development: runtime plus Poetry, debugpy, bash, git. |
3.14-builder-1.0.12 | 3.14-builder | Poetry and the C toolchain for the builder stage of an image. |
3.14-cli-1.0.12 | 3.14-cli | Makefile tooling: Poetry, git, bash, curl. |
Every tag is <upstream-minor>-<target>-<version>. There is no bare tag and latest is forbidden.
3.14-runtime stays on 3.14. It moves only when the client re-pulls, which suits cli and local
development.All four are built from one multi-target
Dockerfile, pinned to
python:3.14.10-alpine3.24. The tools it installs are pinned in
requirements.txt, and
the whole tree they resolve to in the constraints file beside it.
| Target | Runs as | On top of the base |
|---|---|---|
runtime | app (uid 1000) | Nothing. pip is uninstalled, and there is no compiler and no Poetry. |
development | app (uid 1000) | runtime plus pip, Poetry 2, debugpy, bash, git. |
builder | app (uid 1000) | pip, Poetry 2, git, and a C toolchain for packages with no musl wheel. |
cli | root | builder plus bash and curl. |
development is built FROM runtime. It runs on a developer machine and is never deployed.builder keeps the C toolchain (build-base, libffi-dev, openssl-dev, linux-headers) on purpose. It is the
stage a project compiles its wheels in, and the multi-stage application build discards it.cli stays root so it can write into a bind mount owned by the caller.HEALTHCHECK or exposes a port. These are language bases, not services, so the application that
inherits the runtime declares the health check for the process it actually runs.Every image provides, and no consuming Dockerfile re-declares:
app user (uid 1000), whose home is the /app working directory it owns.PATH. /app/.venv/bin with VIRTUAL_ENV set, so a stage that ran poetry install
reaches its dependencies with no activation step and the runtime resolves the very same path.PYTHONUNBUFFERED so a crash loses no log line,
PYTHONDONTWRITEBYTECODE so nothing is written into a bind mount or a read-only layer, and PYTHONFAULTHANDLER in
the runtime so a fatal signal prints a traceback.runtime uninstalls pip, the largest dependency tree the base image carries,
which an application running a virtual environment never reaches. The ensurepip wheel stays in place, so
python3 -m ensurepip restores the installer for the rare consumer that needs it.PIP_NO_CACHE_DIR, PIP_DISABLE_PIP_VERSION_CHECK).POETRY_VIRTUALENVS_IN_PROJECT), in builder, cli, and development.A project consumes the base in two thin files and adds only its own dependencies, code, and tuning:
# syntax=docker/dockerfile:1
FROM gustavofreze/python:3.14-development-1.0.12
COPY ./ /app
# syntax=docker/dockerfile:1
FROM gustavofreze/python:3.14-builder-1.0.12 AS builder
COPY pyproject.toml poetry.lock ./
RUN poetry install --no-root --only main
COPY ./ ./
FROM gustavofreze/python:3.14-runtime-1.0.12
COPY --from=builder --chown=app:app /app /app
CMD ["python3", "-m", "your_application"]
The virtual environment is already on PATH, so the runtime stage runs python3 and every console script the lock file
installed without activating anything.
The cli image is invoked directly and never appears in a Dockerfile.
To install the project dependencies, run:
docker run --rm -v "$(pwd)":/app gustavofreze/python:3.14-cli-1.0.12 poetry install
To execute a script, run:
docker run --rm -v "$(pwd)":/app gustavofreze/python:3.14-cli-1.0.12 python3 your-script.py
The rules that hold across every family live in the usage contract.
No tag is published before it passes the full
gate, on a native linux/amd64 runner and a native
linux/arm64 one:
| Stage | Tool | What it checks |
|---|---|---|
| Lint | hadolint, ShellCheck | Every Dockerfile and every RUN body. |
| Scan | Trivy and Grype | Fixable HIGH and CRITICAL vulnerabilities. |
| Audit | Dockle | The CIS Docker Benchmark. |
| Efficiency | dive | Wasted layer space. |
| Smoke | throwaway containers | The runtime contract, in throwaway containers. |
The smoke suite asserts the non-root user, the interpreter defaults, the virtual environment on PATH, the pinned tool
versions, and the absence of an installer or a compiler in the production surface.
Every tag also carries an OpenVEX analysis as a cosign attestation, stating per CVE whether the image is genuinely affected. A scanner that reads it applies the analysis on its own.
To scan a tag with the analysis applied, run:
trivy image --vex oci gustavofreze/python:3.14-runtime-1.0.12
affected statements are reported, not silenced, which is the point: the risk is disclosed rather than hidden. The
document is also versioned at
vex/python.openvex.json, so it can be
passed as a file or a URL.
Content type
Image
Digest
sha256:401324daf…
Size
62.4 MB
Last updated
3 days ago
docker pull gustavofreze/python:3.14-development