danielhanchen/unsloth-blackwell-docker

Unsloth Docker images (Blackwell and every current NVIDIA arch)

Prebuilt Docker images for Unsloth: training, Unsloth Studio, JupyterLab and llama.cpp GGUF tooling, on any NVIDIA GPU from Turing through Blackwell.

Built from unslothai/unsloth#5748 (the base + Studio two-image build), with the Colab-grade JupyterLab UX (#6681) and the UNSLOTH_TORCH_INDEX_URL / _FAMILY torch-index override (#6692).

All images and outputs in this repository are licensed under the GNU AGPLv3. Copyright 2026-Present the Unsloth team. Source: https://github.com/unslothai/unsloth Website: https://unsloth.ai

Two images

Tarball	Image	Use
unsloth-blackwell-studio.tar.gz	full Studio + JupyterLab + sshd	the default. Unsloth Studio on :8000, JupyterLab (Unsloth Dark theme, the unslothai/notebooks collection) on :8888.
unsloth-blackwell-base.tar.gz	lean base	training and CLI only, no web UI. Smaller.

What is in the image

Component	Version
Base image	nvidia/cuda:12.8.1-cudnn-runtime-ubuntu24.04
Ubuntu	24.04.1 LTS
CUDA toolkit	12.8 (V12.8.93)
Python	3.12
PyTorch	2.11.0+cu128
torchvision / torchaudio	0.26.0+cu128 / 2.11.0+cu128
Triton	3.6.0
xformers	0.0.35 (cu128, amd64 only)
bitsandbytes	0.50.0
unsloth / unsloth-zoo	2026.7.5 / 2026.7.6
transformers / trl / peft / accelerate	5.14.1 / 0.24.0 / 0.19.1 / 1.14.0
vLLM	0.26.0
flashinfer	0.6.14
numpy / numba	2.4.6 / 0.66.0
JupyterLab	4.6.0
llama.cpp prebuilt	b10079-mix-fb3d4ca (portable CUDA 12 bundle)

GPU coverage: the cu128 wheels carry native SASS for sm_75, sm_80, sm_86, sm_90, sm_100 and sm_120, and SASS is forward compatible within a major, so every non-Jetson GPU on NVIDIA's current list runs precompiled code. Source builds use TORCH_CUDA_ARCH_LIST="7.5;8.0;8.6;8.9;9.0;10.0;12.0+PTX".

Load and run

# Studio (default): Studio on :8000, JupyterLab on :8888
curl -L -O https://huggingface.co/danielhanchen/unsloth-blackwell-docker/resolve/main/unsloth-blackwell-studio.tar.gz
docker load -i unsloth-blackwell-studio.tar.gz

docker run --rm --gpus all --ipc=host --ulimit memlock=-1 \
    -p 127.0.0.1:8000:8000 -p 127.0.0.1:8888:8888 \
    -v "$HOME/.cache/huggingface:/workspace/.cache/huggingface" \
    unsloth-blackwell:studio

The first-boot admin password is printed in the logs and saved to /opt/unsloth-studio/auth/.bootstrap_password. Studio shuts itself down an hour after boot until you change that password.

Publish the ports on 127.0.0.1 as shown unless you intend the machine to serve the internet: the raw port is otherwise reachable by anyone who can route to the host, and server-side tools are enabled by default.

# Base image: training and CLI only
docker load -i unsloth-blackwell-base.tar.gz
docker run --rm --gpus all --ipc=host --ulimit memlock=-1 \
    unsloth-blackwell:base python /workspace/smoke_test.py

Verified on this build

Measured on a B200 (sm_100) with these images:

Check	Result
smoke_test.py (arch list, imports, 5-step LoRA train)	pass, loss 4.10 to 3.75
10-step LoRA finetune of unsloth/Qwen3.5-2B in 4-bit	pass, loss 1.25 to 0.92
16-bit merged export, reloaded and compared against the adapter	pass, 4.55 GB bf16
torch.compile and the Inductor CUDA path	pass
vLLM engine start and generation (the GRPO fast_inference path)	pass, vLLM 0.26.0
GGUF inference, unsloth/gemma-4-E2B-it-GGUF UD-Q4_K_XL	229 tok/s (llama-cli), 193 tok/s (llama-server)
llama.cpp CUDA backend	CUDA0: NVIDIA B200
whisper.cpp CUDA backend (voice dictation)	loads
unsloth-llama-update (check, pinned downgrade, latest, repeat)	pass
Studio: GGUF chat, multi-thread history, tool calling, web search	pass
Studio: all 11 settings tabs, the HTTP API, the update surface	pass
JupyterLab: branded login, notebook categories, Unsloth Dark theme	pass

Four bugs were found and fixed by running these images rather than reading them. Each fix carries a build-time guard, so none of them can regress silently:

• llama.cpp's libggml-cuda.so could not resolve libcublas, so the CUDA backend failed to load silently and every GGUF request ran on the CPU at 1.6 tok/s instead of 229. whisper.cpp links the same libraries, so voice dictation was affected too. ggml_backend_dl dlopens its backends, so a missing dependency is silent by design: nothing is printed, --list-devices simply comes back without the CUDA entry.
• The base venv was missing structlog, so unsloth train, unsloth export, unsloth chat and unsloth list-checkpoints all died on ModuleNotFoundError. It is a Studio backend requirement rather than an unsloth[huggingface] one, so nothing pulled it in.
• flashinfer-jit-cache was pinned to a literal version while vLLM resolved a newer flashinfer-python. flashinfer raises at import when the two disagree, and that exception is thrown inside the vLLM EngineCore, so GRPO with fast_inference=True failed at engine start. The pin is now derived from whatever vLLM actually resolved.
• The Jupyter notebook helpers activated a bundled transformers build that the image's vLLM cannot import, which broke import unsloth in most of the shipped notebooks; the pip shim also let notebooks silently downgrade the tested trl / peft / datasets versions.

Notes

• --ipc=host matters: the default 64 MB /dev/shm crashes DataLoader workers.
• Without a GPU, pass -e UNSLOTH_ALLOW_CPU=1. Training is unavailable, but Studio chat, Data Recipes, Jupyter and the GGUF tooling work.
• bash docker/run.sh in the unsloth repo wraps the easily-forgotten flags.