Pythonium - improved base container images for Python

Using the image

This image is a basic wrapper layer on top of the standard official Python image.

It adds:

• a pre-made unprivileged user app for the deployed application to use
• a pre-made virtual environment, which is always active in the container and belongs to the unprivileged user

The repo exposes two editions of each tag based on the official Python repository on Docker Hub:

• <PYTHON-VERSION>-alpine-<ALPINE-VERSION> (Alpine Linux)
• <PYTHON-VERSION>-debian-<DEBIAN-VERSION> (Debian)

Each image is also published under an immutable tag: <PYTHON-VERSION>-<FLAVOR>-<FLAVOR-VERSION>-<CREATED-AT>.

Building the images

Building the image

buildah build --file alpine/Containerfile --tag forge.bolzga.net/solid-containers/pythonium:3.14-alpine3.23 .

Available build args

• PYTHONIUM__PYTHON_VERSION: Python version for the base image: (default: 3.14)
  • one of: 3.10, 3.11, 3.12, 3.13, 3.14
• PYTHONIUM__ALPINE_VERSION: Alpine Linux version for the base image (for Alpine Linux—based edition only) (default: 3.23)
• PYTHONIUM__DEBIAN_VERSION: Debian version for the base image (for Debian—based edition only) (default: trixie)
• PYTHONIUM__USER_NAME: name of the unprivileged user to create (default: app)
• PYTHONIUM__USER_GROUP: primary group name for the unprivileged user to create (default: app)
• PYTHONIUM__USER_HOME: path to the home of the unprivileged user (default: /home/${PYTHONIUM__USER_NAME})
• PYTHONIUM__USER_SHELL: shell to assign as default for the unprivileged user (default: /sbin/nologin)
• PYTHONIUM__USER_UID: UID of the unprivileged user (default: 1000)
• PYTHONIUM__USER_GID: GID of the unprivileged user's primary group (default: 1000)
• PYTHONIUM__VIRTUAL_ENV_PATH: path to the globally-available virtual environment (default: ${PYTHONIUM__USER_HOME}/.venv)

Example Containerfile for a Flask app using Pythonium

FROM forge.bolzga.net/solid-containers/pythonium:3.14-alpine3.23

RUN --mount=type=bind,target=/requirements.txt,source=requirements.txt \
    --mount=type=cache,target=~/.cache/pip,sharing=locked \
  pip install -r /requirements.txt

ENV FLASK_APP="package.app"
EXPOSE 8000

ENTRYPOINT [ "python" ]
CMD [ "-m", "flask", "run" ]

For more detailed examples for each edition (e.g. installation of system-wide packages) check out docs for the Alpine Linux—based edition and for the Debian—based edition.