| --- |
| license: agpl-3.0 |
| language: |
| - en |
| library_name: docker |
| tags: |
| - docker |
| - unsloth |
| - blackwell |
| - fine-tuning |
| - lora |
| - llm |
| - gpu |
| - jupyter |
| --- |
| |
| # Unsloth Blackwell-Compatible Docker Image (Studio + JupyterLab) |
|
|
| Built by Unsloth. Docker images for [Unsloth](https://github.com/unslothai/unsloth) that run on every current NVIDIA datacenter and consumer GPU from Turing through Blackwell, on `linux/amd64`. |
|
|
| This build bundles the work from three in-flight pull requests: |
|
|
| - the Blackwell base + Studio two-image build (`unslothai/unsloth#5748`), |
| - the Colab-grade JupyterLab UX (`unslothai/unsloth#6681`), |
| - the `UNSLOTH_TORCH_INDEX_URL` / `_FAMILY` torch-index override (`unslothai/unsloth#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/CLI only, no web UI. Smaller. | |
|
|
| ## What's in the image |
|
|
| | Component | Version | |
| |---|---| |
| | Base image | `nvidia/cuda:12.8.1-cudnn-runtime-ubuntu24.04` | |
| | PyTorch | `2.10.0+cu128` | |
| | Triton | `3.6.0` | |
| | xformers | `0.0.34` (cu128) | |
| | bitsandbytes | `0.49.2` | |
| | vLLM | `0.19.1` | |
| | flashinfer | `0.6.6` | |
| | Unsloth | `2026.6.9` | |
| | Unsloth Zoo | `2026.6.7` | |
| | transformers | `5.12.1` | |
| | trl | `0.24.0` | |
| | peft | `0.19.1` | |
| | accelerate | `1.14.0` | |
| | JupyterLab | `4.6.0` (notebook `7.6.0`) | |
| | Built-in SASS | `sm_75 sm_80 sm_86 sm_89 sm_90 sm_100 sm_120` | |
|
|
| ## Supported GPUs |
|
|
| | Compute Cap | GPU family | Examples | Status | |
| |---|---|---|---| |
| | sm_75 | Turing | T4, RTX 20-series, Quadro RTX | Works (no bf16, falls back to fp16) | |
| | sm_80 | Ampere DC | A100, A30 | Native SASS | |
| | sm_86 | Ampere | RTX A6000, A40, RTX 30-series | Native SASS | |
| | sm_89 | Ada Lovelace | L4, L40, L40S, RTX 40-series | JIT-PTX from sm_86 | |
| | sm_90 | Hopper | H100, H200, GH200 | Native SASS | |
| | sm_100 | Blackwell DC | B100, B200, GB200 | Native SASS | |
| | sm_103 | Blackwell DC | B300, GB300 | JIT-PTX from sm_100 | |
| | sm_120 | Blackwell consumer | RTX 50-series, RTX PRO 6000 Blackwell | Native SASS | |
| | sm_121 | Blackwell | GB10 (DGX Spark) | JIT-PTX from sm_120 | |
|
|
| DGX Spark (GB10) is an ARM host; this image is `linux/amd64` only. |
|
|
| ## Quick start (full Studio + JupyterLab image) |
|
|
| ```bash |
| pip install -U huggingface_hub |
| hf auth login |
| |
| hf download danielhanchen/unsloth-blackwell-docker \ |
| unsloth-blackwell-studio.tar.gz --local-dir /tmp |
| |
| gunzip -c /tmp/unsloth-blackwell-studio.tar.gz | docker load |
| docker images unsloth-blackwell:studio |
| |
| # Studio on :8000, JupyterLab on :8888 (a first-boot password is printed in the logs) |
| docker run --gpus all -p 8000:8000 -p 8888:8888 unsloth-blackwell:studio |
| ``` |
|
|
| For a public JupyterLab link over Cloudflare, add `-e UNSLOTH_JUPYTER_CLOUDFLARE=1`. |
|
|
| JupyterLab opens on the categorized `Unsloth Notebooks` view (Main, Gemma, GRPO, Tool Calling, Vision, AMD, and more), refreshed from [unslothai/notebooks](https://github.com/unslothai/notebooks) on each boot while preserving your edits. |
|
|
| ## Quick start (lean base image) |
|
|
| ```bash |
| hf download danielhanchen/unsloth-blackwell-docker \ |
| unsloth-blackwell-base.tar.gz --local-dir /tmp |
| gunzip -c /tmp/unsloth-blackwell-base.tar.gz | docker load |
| |
| # 5-step LoRA smoke test on Llama-3.2-1B-4bit |
| docker run --rm --gpus all unsloth-blackwell:base python /workspace/smoke_test.py |
| ``` |
|
|
| ## Torch-index override (PR #6692) |
|
|
| Pin which PyTorch wheel index the installers use, instead of letting the host GPU decide. Useful for headless / CI / air-gapped builds and custom mirrors. An explicit pin wins verbatim and skips all GPU probing: |
|
|
| ```bash |
| # a CUDA family: cu126, cu128, cu130, ... (or cpu) |
| UNSLOTH_TORCH_INDEX_FAMILY=cu128 ... |
| # an AMD ROCm family (native install on AMD hosts): rocm7.2, gfx1151, gfx120X-all, ... |
| UNSLOTH_TORCH_INDEX_FAMILY=rocm7.2 ... |
| # or a full custom index URL, used exactly as given |
| UNSLOTH_TORCH_INDEX_URL=https://download.pytorch.org/whl/cu128 ... |
| ``` |
|
|
| The Studio installer records the index it installed from, so a later `unsloth studio update` that changes the pin reinstalls torch from the new index instead of keeping the old wheel. |
|
|
| ## CPU-only hosts |
|
|
| Training needs an NVIDIA GPU, but JupyterLab, the GGUF tooling (baked llama.cpp) and Studio chat work on CPU: |
|
|
| ```bash |
| docker run -e UNSLOTH_ALLOW_CPU=1 -p 8000:8000 -p 8888:8888 unsloth-blackwell:studio |
| ``` |
|
|
| ## License |
|
|
| GNU AGPLv3. The image surfaces its license and attribution in JupyterLab (Help > About Unsloth Docker Studio) and on the login screen. Copyright 2026-Present the Unsloth team. |
|
|
