Docker

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

Switch to the -uv images

Each image below ships a uv variant that uses uv with a relocatable venv (/workspace/axolotl-venv) instead of Miniconda + pip. Append -uv to the image name (e.g. axolotlai/axolotl-uv, axolotlai/axolotl-base-uv, axolotlai/axolotl-cloud-uv). Tags follow the same format as their non-uv counterparts.

We recommend switching to the -uv images early. In the near future we will publish the uv-based build to the non-uv tags as well. The non-uv names will continue to work, but they will start serving the uv image.

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

Variant	Image	Docker Hub
pip	`axolotlai/axolotl-base`	Link
uv	`axolotlai/axolotl-base-uv`	Link

Tags format

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

Tags examples:

main-base-py3.11-cu128-2.9.1
main-base-py3.12-cu128-2.10.0
main-base-py3.12-cu130-2.9.1
main-base-py3.12-cu130-2.10.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

Variant	Image	Docker Hub
pip	`axolotlai/axolotl`	Link
uv	`axolotlai/axolotl-uv`	Link

Tags format

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

# latest main (currently torch 2.9.1, python 3.11, cuda 12.8)
main-latest

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

# tagged release
{version}

Tip

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

Tags examples:

main-py3.11-cu128-2.9.1
main-py3.12-cu128-2.10.0
main-py3.12-cu130-2.9.1
main-py3.12-cu130-2.10.0
main-latest
main-20260315-py3.11-cu128-2.9.1
0.16.1

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

Variant	Image	Docker Hub
pip	`axolotlai/axolotl-cloud`	Link
uv	`axolotlai/axolotl-cloud-uv`	Link

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. /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.

Tags format

This uses the same tags as the cloud image.