psyb0t/torchbase repository overview

Source⁠

⁠Torchbase

The heavy part of a PyTorch image, built once so every service does not waste hours rebuilding the same CUDA stack.

Torchbase publishes strict Python, Torch, and CUDA tuples. Pick the exact tuple your service needs. Do not point a production image at latest and hope the ABI works out.

⁠Use it

Published tags include the Torchbase release version. Replace <release> with 0.1.1, for example psyb0t/torchbase:py3.12-torch2.5.1-v0.1.1-cu124.

All images put Torch in /opt/torch-venv, set VIRTUAL_ENV and PATH, and run as UID and GID 1000.

FROM psyb0t/torchbase:py3.12-torch2.14-v<release>-cu126

USER root
COPY --from=ghcr.io/astral-sh/uv:0.11.15@sha256:e590846f4776907b254ac0f44b5b380347af5d90d668138ca7938d1b0c2f98d3 /uv /usr/local/bin/uv
COPY requirements-provider.txt ./
RUN uv pip install --python /opt/torch-venv/bin/python --require-hashes -r requirements-provider.txt
USER 1000:1000

Torchbase owns Python, Torch, CUDA, and compiler bits. Your image owns its provider packages, model files, API, and tests.

The Torch 2.5.1 tuples preserve Audiolla's current Torch version. They do not include Torchaudio. Install Torchaudio 2.5.1 from the matching cpu or cu124 wheel index in the derived image, and keep its dependency install layer before copying application code. The cu124 tuple reports CUDA 12.4 from Torch; its OS base is the same pinned NVIDIA CUDA 12.6.3 runtime used by Audiolla. These compatibility images retain an old Torch release and are not a recommendation to use it for new applications.

Torch 2.5.1 is affected by CVE-2025-32434⁠: loading a malicious checkpoint can execute code even with weights_only=True. Treat model checkpoints as executable code and use only trusted, verified weights. This compatibility tuple does not fix that advisory.

CUDA 12.6 and CUDA 13.0 images need NVIDIA Container Toolkit at runtime. CUDA 12.x needs an NVIDIA driver from the 525 series or newer. CUDA 13.0 needs driver 580 or newer. Python 3.12 CUDA images use NVIDIA CUDA runtime bases. Python 3.13 CUDA images use the CUDA user-space libraries that ship with the hash-locked PyTorch wheel, then receive the host driver through NVIDIA Container Toolkit.

⁠Tuple matrix

tuples.json is the source of truth. Every entry names an exact builder image, runtime image, Python version, Torch backend, lock files, image tag shape, CPU or CUDA platform, and any runtime packages the CUDA base needs.

One generic Dockerfile and one GitHub Actions matrix build every entry. Adding Python, CUDA, or Torch releases means adding one tested tuple and its hash-locked requirements files. It does not mean copying a Dockerfile, a Make target, or a workflow job.

Each tuple's lock file is the dependency layer boundary. Docker and Buildx reuse that layer when the lock is unchanged, so a change outside the lock does not re-download PyTorch or CUDA packages.

⁠Build and verify

Docker and Make are the only host requirements.

make lint
make test
make test-coverage
make build-test
make build-test-cuda-gpu

make build-test builds and imports every registered tuple. make build-test-cuda-gpu builds and runs every CUDA tuple with --gpus all. It needs NVIDIA Container Toolkit and a usable NVIDIA GPU.

Use one tuple when you are working on a new one:

make model-lock TUPLE=py3.12-torch2.14-cpu
make build-test TUPLE=py3.12-torch2.14-cpu

make ci-targets prints the exact matrix consumed by the release workflow.

Build only the Audiolla-compatible tuples:

make build-test TUPLE=py3.12-torch2.5.1-cpu
make build-test-cuda-gpu TUPLE=py3.12-torch2.5.1-cu124

⁠Add a tuple

Add a hash-locked .in and .txt dependency pair, then add one object to tuples.json. Give it a new tag shape. Existing tuples never move in place.

Run the targeted lock and image tests before releasing it:

make model-lock TUPLE=your-tuple-id
make build-test TUPLE=your-tuple-id

CUDA entries also need make build-test-cuda-gpu TUPLE=your-tuple-id on a machine with a compatible driver. A derived service still needs its own image and GPU behavior tests.

⁠License

Torchbase code is WTFPL. PyTorch, CUDA, Python, and every dependency keep their own upstream licenses.