Docker

This section describes the different Docker images that are released by AxolotlAI at Docker Hub.

uv is now the default

All images now use uv with a relocatable venv (/workspace/axolotl-venv) instead of Miniconda + pip. The plain image names are the defaults, and the -uv names are kept as aliases where they exist. Tags follow the same format for both names.

Supported variants

Current Axolotl runtime images target Python 3.12 on CUDA 13.0 with PyTorch 2.11.0 and 2.12.0. The floating main-latest tags point at the Python 3.12 / CUDA 13.0 / PyTorch 2.12.0 build. Bare release tags, such as 0.16.1, point at the same latest matrix entry for that release.

Base images may include additional uv-based tags for build compatibility, and older tags may remain available on Docker Hub for reproducibility. New runtime builds are centered on the CUDA 13.0 matrix.

Base

The base image is the most minimal image that can install Axolotl. It is based on the nvidia/cuda image. It includes python, torch, git, git-lfs, awscli, pydantic, and more.

Image

Image	Notes
`axolotlai/axolotl-base`	Default
`axolotlai/axolotl-base-uv`	Alias

Links: base, base-uv

Tags format

main-base-py{python_version}-cu{cuda_version}-{pytorch_version}

Tags examples:

main-base-py3.12-cu130-2.11.0
main-base-py3.12-cu130-2.12.0

Main

The main image is the image that is used to run Axolotl. It is based on the axolotlai/axolotl-base image and includes the Axolotl codebase, dependencies, and more.

Image

Image	Notes
`axolotlai/axolotl`	Default
`axolotlai/axolotl-uv`	Alias

Links: axolotl, axolotl-uv

Tags format

# on push to main
main-py{python_version}-cu{cuda_version}-{pytorch_version}

# latest stable build from main
main-latest

# nightly build
{branch}-{date_in_YYYYMMDD}-py{python_version}-cu{cuda_version}-{pytorch_version}

# tagged release
{version}
{version}-py{python_version}-cu{cuda_version}-{pytorch_version}
{version}-latest

Tip

There may be some extra tags appended to the image, like -vllm which installs those packages.

Tags examples:

main-py3.12-cu130-2.11.0
main-py3.12-cu130-2.12.0
main-latest
main-20260315-py3.12-cu130-2.12.0
0.16.1
0.16.1-py3.12-cu130-2.12.0
0.16.1-latest

Cloud

The cloud image is the image that is used to run Axolotl in the cloud. It is based on the axolotlai/axolotl image and sets ENV variables like HuggingFace cache directories for volume mounts, tmux, and more for different cloud providers.

Tip

Jupyter lab is run by default. Set JUPYTER_DISABLE=1 in the environment variables to disable it.

Image

Image	Notes
`axolotlai/axolotl-cloud`	Default
`axolotlai/axolotl-cloud-uv`	Alias

Links: cloud, cloud-uv

Tags format

This uses the same tags as the main image.

Environment variables

JUPYTER_DISABLE: Disable Jupyter lab.
JUPYTER_PASSWORD: Set a password for the Jupyter lab.
PUBLIC_KEY / SSH_KEY: Add a public key for the SSH service.

Volume mounts

Tip

We recommend mounting volumes to /workspace/data for data persistence. The cloud images set HF_HOME to /workspace/data/huggingface-cache so HuggingFace Hub and dataset caches are kept under the same persistent mount. /workspace/axolotl contains the source code and is ephemeral.

/workspace/data/axolotl-artifacts: Directory to store Axolotl artifacts.
/workspace/data/huggingface-cache: Directory to store HuggingFace cache.

Cloud-no-tmux

This is the same as the cloud image but without tmux.

Image

axolotlai/axolotl-cloud-term

Link: Docker Hub

Note

The naming may be a bit confusing as it has -term appended to the end. This image is uv-based and does not have a separate -uv alias.

Tags format

This uses the same tags as the cloud image.