Docker

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

Important

For Blackwell GPUs, please use the tags with PyTorch 2.9.1 and CUDA 12.8.

Tip

Each image below is available in 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-base-uv). Tags follow the same format. We recommend the uv images for new deployments.

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

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.