Local UI to run and train LLMs and diffusion models. Supports GGUF, MLX, Qwen3.8, DeepSeek-V4.1, MiniMax-H3, Gemma 4, FLUX and more.
Python agentaichatgptdeepseekfine-tuninggemmaimage-generationllamallmllmsopenaipythonqwenreinforcement-learningself-hostedstable-diffusiontext-to-speechttsuiunsloth
Docker: describe the shipped images on Docker Hub and in the README (#10334)
Daniel Han6a5a644ce595
diff --git a/.github/workflows/docker-publish.yml b/.github/workflows/docker-publish.ymlindex e15c9b54736..c0acab2c82a 100644--- a/.github/workflows/docker-publish.yml+++ b/.github/workflows/docker-publish.yml@@ -525,6 +525,51 @@ jobs:echo "digest=${DIGEST}" >> "$GITHUB_OUTPUT"echo "studio manifest: ${TAG} @ ${DIGEST}"+ # The Docker Hub page is not written by any push: it is repository metadata that+ # only the Hub API changes, so without this it stays whatever was pasted in by+ # hand. Synced from docker/DOCKERHUB.md whenever :latest moved, i.e. the same+ # condition as the stable tags above. Verified by reading it back, and a token+ # that cannot edit the description fails the job rather than warning.+ hub-readme:+ needs: merge-studio+ if: ${{ github.ref == format('refs/heads/{0}', github.event.repository.default_branch) && github.event.inputs.unsloth_ref == '' && (github.event.inputs.unsloth_zoo_ref == '' || github.event.inputs.unsloth_zoo_ref == 'main') && (github.event.inputs.notebooks_ref == '' || github.event.inputs.notebooks_ref == 'main') && github.event.inputs.llama_prebuilt_tag == '' }}+ runs-on: ubuntu-latest+ timeout-minutes: 5+ permissions:+ contents: read+ steps:+ - uses: actions/checkout@v4++ - name: Sync docker/DOCKERHUB.md to the Docker Hub page+ run: |+ README=docker/DOCKERHUB.md+ test -s "$README"+ # Organization access tokens are exchanged at /v2/auth/token, not+ # /v2/users/login/, which rejects organization accounts.+ TOKEN="$(curl -sS -X POST https://hub.docker.com/v2/auth/token \+ -H 'Content-Type: application/json' \+ -d "{\"identifier\": \"${REGISTRY_USERNAME}\", \"secret\": \"${{ secrets.DOCKER_API_KEY }}\"}" \+ | python3 -c 'import json,sys; print(json.load(sys.stdin).get("access_token",""))')"+ if [ -z "$TOKEN" ]; then+ echo "::error::Could not exchange DOCKER_API_KEY for a Hub API token; the Hub page was not updated."+ exit 1+ fi+ BODY="$(python3 -c 'import json,sys; print(json.dumps({"full_description": open(sys.argv[1], encoding="utf-8").read()}))' "$README")"+ CODE="$(curl -sS -o /tmp/hub_patch.json -w '%{http_code}' -X PATCH \+ "https://hub.docker.com/v2/repositories/${IMAGE_NAME}/" \+ -H "Authorization: Bearer ${TOKEN}" -H 'Content-Type: application/json' \+ --data-binary "$BODY")"+ echo "PATCH returned HTTP ${CODE}"+ # Read it back rather than trusting the status code.+ LIVE="$(curl -sS "https://hub.docker.com/v2/repositories/${IMAGE_NAME}/" \+ | python3 -c 'import json,sys; print(json.load(sys.stdin).get("full_description",""))')"+ if [ "$LIVE" != "$(cat "$README")" ]; then+ echo "::error::The Hub page does not match ${README} after PATCH ${CODE}. The token most likely lacks permission to edit the repository description."+ head -c 400 /tmp/hub_patch.json; echo+ exit 1+ fi+ echo "Hub page for ${IMAGE_NAME} now matches ${README}."+smoke-test:needs: [merge, merge-studio]if: ${{ vars.HAS_GPU_RUNNER == 'true' }}diff --git a/README.md b/README.mdindex 13214bdde62..f260e724c3a 100644--- a/README.md+++ b/README.md@@ -151,14 +151,15 @@ unsloth studio --secure```#### Docker-Use our [Docker image](https://hub.docker.com/r/unsloth/unsloth) ```unsloth/unsloth``` container. Run:+Use our [Docker image](https://hub.docker.com/r/unsloth/unsloth) ```unsloth/unsloth``` (needs the [NVIDIA Container Toolkit](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html)). Run:```bash-docker run -d -e JUPYTER_PASSWORD="mypassword" \- -p 8888:8888 -p 8000:8000 -p 2222:22 \- -v $(pwd)/work:/workspace/work \- --gpus all \+docker run -d --gpus all --ipc=host \+ -p 8000:8000 -p 8888:8888 \+ -e JUPYTER_PASSWORD="mypassword" \+ -v "$PWD":/workspace/host \unsloth/unsloth```+Studio is at `http://localhost:8000`, JupyterLab at `http://localhost:8888`. Tags (`unsloth/unsloth:core` for notebooks only), GPU support and options: [Docker Hub](https://hub.docker.com/r/unsloth/unsloth).#### Remote HTTPS & LAN AccessServer-side tools are on by default - so **be careful**! Keep your password safe, or use `--disable-tools` when exposing Unsloth.diff --git a/docker/DOCKERHUB.md b/docker/DOCKERHUB.mdnew file mode 100644index 00000000000..d026153ae39--- /dev/null+++ b/docker/DOCKERHUB.md@@ -0,0 +1,133 @@+# Unsloth Docker Image++Pre-built images for [Unsloth](https://github.com/unslothai/unsloth): fine-tune and run LLMs, vision, audio and diffusion models with no setup. Every image carries the full training stack (PyTorch 2.11 with CUDA 12.8, Unsloth, unsloth-zoo, bitsandbytes, xformers, TRL, PEFT), JupyterLab with the [Unsloth notebooks](https://github.com/unslothai/notebooks) pre-synced, and prebuilt llama.cpp and whisper.cpp for GGUF work.++Source: [`docker/`](https://github.com/unslothai/unsloth/tree/main/docker) in the main repository. Guide: [docs.unsloth.ai](https://docs.unsloth.ai/get-started/install-and-update/docker).++## Tags++| Tag | Contents | Use it for |+|---|---|---|+| `latest`, `studio` | Unsloth Studio web UI + JupyterLab + notebooks + key-only SSH | Most users. Train and chat in the browser. |+| `core` | Training stack + JupyterLab + notebooks, no Studio | Notebooks, scripts, CI, slimmer pulls. |+| `sha-<commit>`, `core-sha-<commit>` | The same two images, pinned to one commit of `main` | Reproducible runs. |+| `<version>`, `core-<version>` | Release builds | Pin a release. |++`latest` and `core` move with every push to `main` and on a daily rebuild. Both images are multi-arch: `linux/amd64` and `linux/arm64` (GH200, DGX Spark).++## Quick start++Requires the [NVIDIA Container Toolkit](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html) and an NVIDIA driver of 570.26 or newer. On Windows use Docker Desktop with the WSL 2 backend.++```bash+docker run -d --gpus all --ipc=host \+ --ulimit memlock=-1 --ulimit stack=67108864 \+ -p 8000:8000 -p 8888:8888 \+ -e JUPYTER_PASSWORD="choose-a-password" \+ -v "$PWD":/workspace/host \+ -v "$HOME/.cache/huggingface":/workspace/.cache/huggingface \+ unsloth/unsloth+```++Then open Studio at `http://localhost:8000` and JupyterLab at `http://localhost:8888`. Studio prints its first-boot admin password in `docker logs <container>`. If `JUPYTER_PASSWORD` is not set, a random one is generated and printed there too.++The `docker/run.sh` helper in the repository sets these flags for you:++```bash+git clone https://github.com/unslothai/unsloth && cd unsloth+UNSLOTH_PORTS="-p 8000:8000 -p 8888:8888" bash docker/run.sh+```++### Notebooks only (`core`)++The `core` image has no service manager. Start JupyterLab on the command line:++```bash+docker run -d --gpus all --ipc=host -p 8888:8888 \+ -v "$PWD":/workspace/host \+ unsloth/unsloth:core \+ jupyter lab --ip 0.0.0.0 --port 8888 --allow-root+```++The login token is printed in `docker logs`. With no command the image runs `python`, so a bare `docker run unsloth/unsloth:core` exits immediately.++### Scripts++```bash+docker run --rm --gpus all --ipc=host -v "$PWD":/workspace/host \+ unsloth/unsloth:core python /workspace/host/train.py+```++### CPU-only hosts++Without a GPU the container refuses to start unless you opt in. Studio chat with GGUF models, JupyterLab and the GGUF tooling work; training does not.++```bash+docker run -d -e UNSLOTH_ALLOW_CPU=1 -p 8000:8000 -p 8888:8888 unsloth/unsloth+```++## Supported GPUs++Compiled for `sm_75 sm_80 sm_86 sm_90 sm_100 sm_120`: Turing (T4, RTX 20), Ampere (A100, A10, RTX 30), Ada (L4, L40, RTX 40), Hopper (H100, H200, GH200), Blackwell (B200, GB200, RTX 50, RTX PRO 6000) and GB10 (DGX Spark). The container prints the detected GPU on start and explains what to do when the driver is too old.++Driver requirements:++- 570.26 or newer for CUDA 12.8 on every GPU.+- 580 or newer for B300, GB300 and GB10.+- On `linux/arm64` the bundled llama.cpp is a CUDA 13 build because upstream ships no CUDA 12 build for that architecture. Training works from driver 570, but GGUF export and Studio chat need 580 or newer.++Turing has no bfloat16; Unsloth falls back to float16 there. AMD GPUs are not supported by these images.++## Ports++| Port | Service | Image |+|---|---|---|+| 8000 | Unsloth Studio | `latest` |+| 8888 | JupyterLab | both |+| 22 | SSH, key only, off unless `SSH_KEY` or `PUBLIC_KEY` is set | `latest` |++## Environment variables++| Variable | Effect |+|---|---|+| `JUPYTER_PASSWORD` | JupyterLab password. Unset: generated once and printed in the logs. |+| `JUPYTER_PORT` | JupyterLab port inside the container. Default `8888`. |+| `SSH_KEY` or `PUBLIC_KEY` | OpenSSH public key for root login. Enables sshd on port 22. Password login is never enabled. |+| `UNSLOTH_ALLOW_CPU=1` | Allow starting without a GPU. |+| `UNSLOTH_JUPYTER_CLOUDFLARE=1` | Publish JupyterLab through a Cloudflare quick tunnel and print the URL. |+| `UNSLOTH_SKIP_NOTEBOOK_SYNC=1` | Do not refresh the notebooks from GitHub on start. |+| `HF_TOKEN`, `WANDB_API_KEY` | Forwarded to Hugging Face and Weights and Biases. |++## Volumes++The working directory is `/workspace`. Mount what you want to keep:++| Container path | What it holds |+|---|---|+| `/workspace/host` | Your files. Mount your project directory here. |+| `/workspace/.cache/huggingface` | Model downloads. Mount your host HF cache to reuse it. |+| `/workspace/.cache/triton` | Compiled kernels. Optional, speeds up restarts. |+| `/workspace/unsloth-notebooks` | The synced notebooks. Your edits are kept across refreshes. |+| `/workspace/Unsloth Notebooks` | The same notebooks grouped by topic, rebuilt on each start. |++The container runs as root by default. `--user <uid>:<gid>` is supported and keeps files on your mounts owned by you.++## Updating inside a running container++On the `latest` image:++- `unsloth-studio-update` upgrades Studio and Unsloth in place.+- `unsloth-llama-update` fetches the newest prebuilt llama.cpp.+- `unsloth-jupyter-tunnel` opens a Cloudflare quick tunnel to JupyterLab.++On both images the notebooks refresh from GitHub on each start unless `UNSLOTH_SKIP_NOTEBOOK_SYNC=1`. Pull a new image tag to update everything else.++## Help++- [Documentation](https://docs.unsloth.ai)+- [r/unsloth](https://reddit.com/r/unsloth)+- [Issues](https://github.com/unslothai/unsloth/issues)++## License++AGPL-3.0, following the main repository. See [LICENSE](https://github.com/unslothai/unsloth/blob/main/LICENSE).diff --git a/docker/Dockerfile.studio b/docker/Dockerfile.studioindex 8c47ffeedae..30c0b0dc151 100644--- a/docker/Dockerfile.studio+++ b/docker/Dockerfile.studio@@ -2,12 +2,12 @@# Published as unsloth/unsloth:studio (and default :latest); layers Studio on the# lean core image and runs Studio:8000, JupyterLab:8888, sshd:22.#-# Build (local):-# docker buildx build --build-arg BASE_IMAGE=unsloth-blackwell:test \-# -f docker/Dockerfile.studio -t unsloth-blackwell:studio docker/+# Build (local, on top of the published base or one built from docker/Dockerfile):+# docker buildx build --build-arg BASE_IMAGE=unsloth/unsloth:core \+# -f docker/Dockerfile.studio -t unsloth/unsloth:studio docker/# Run:# docker run --rm --gpus all -p 8000:8000 -p 8888:8888 \-# -v $HOME/.cache/huggingface:/workspace/.cache/huggingface unsloth-blackwell:studio+# -v $HOME/.cache/huggingface:/workspace/.cache/huggingface unsloth/unsloth:studio## Studio on :8000 (first-boot admin password in the logs, persisted under# /opt/unsloth-studio/auth/); JupyterLab on :8888 (JUPYTER_PASSWORD env, else a@@ -15,7 +15,7 @@# training is unavailable but Studio chat / Data Recipes / GGUF / Jupyter work.# CI pins BASE_IMAGE to the published base digest so both images ship the same stack.-ARG BASE_IMAGE=unsloth-blackwell:test+ARG BASE_IMAGE=unsloth/unsloth:core# Builds the "Unsloth Dark" (Monokai) theme + Colab-style cell-nav keymap. Node# lives only in this throwaway stage; the final image copies just the prebuiltdiff --git a/tests/python/test_docker_hub_readme.py b/tests/python/test_docker_hub_readme.pynew file mode 100644index 00000000000..a0f256693f2--- /dev/null+++ b/tests/python/test_docker_hub_readme.py@@ -0,0 +1,142 @@+# SPDX-License-Identifier: AGPL-3.0-only+# Copyright 2026-Present the Unsloth team. See /studio/LICENSE.AGPL-3.0++"""The Docker Hub page is repository metadata, not something a push writes, so it+only changes when the publish workflow PATCHes it. These pin that the README in the+tree describes the images that actually ship and that the sync step cannot report+success while the page stays stale.+"""++from __future__ import annotations++import json+import os+import shutil+import subprocess+from pathlib import Path++import pytest+import yaml++REPO_ROOT = Path(__file__).resolve().parents[2]+WORKFLOW = REPO_ROOT / ".github" / "workflows" / "docker-publish.yml"+HUB_README = REPO_ROOT / "docker" / "DOCKERHUB.md"+REPO_README = REPO_ROOT / "README.md"+++def test_the_hub_readme_describes_the_shipped_images():+ text = HUB_README.read_text(encoding = "utf-8")+ for needle in (+ "unsloth/unsloth:core",+ "`latest`",+ "linux/arm64",+ "jupyter lab --ip 0.0.0.0 --port 8888 --allow-root",+ "UNSLOTH_ALLOW_CPU=1",+ "/workspace/host",+ "/workspace/.cache/huggingface",+ "sm_75 sm_80 sm_86 sm_90 sm_100 sm_120",+ ):+ assert needle in text, f"the Hub README no longer mentions {needle!r}"+ # the previous image's conventions, none of which exist in this one+ for stale in ("USER_PASSWORD", "/workspace/work", "2222:22", "localhot"):+ assert stale not in text, f"the Hub README still carries {stale!r} from the old image"+++def test_the_repo_readme_run_command_matches_the_image():+ text = REPO_README.read_text(encoding = "utf-8")+ start = text.index("#### Docker")+ section = text[start : text.index("####", start + 1)]+ assert "unsloth/unsloth:core" in section+ assert "/workspace/host" in section+ assert "--ipc=host" in section+ for stale in ("2222:22", "/workspace/work"):+ assert stale not in section, f"the README run command still has {stale!r}"++[email protected](scope = "module")+def sync_job() -> dict:+ doc = yaml.safe_load(WORKFLOW.read_text(encoding = "utf-8"))+ assert "hub-readme" in doc["jobs"], "the Hub README sync job is missing"+ return doc["jobs"]["hub-readme"]+++def test_the_sync_runs_only_when_latest_moved(sync_job: dict):+ doc = yaml.safe_load(WORKFLOW.read_text(encoding = "utf-8"))+ tags = [s for s in doc["jobs"]["merge-studio"]["steps"] if s.get("id") == "meta"][0]["with"][+ "tags"+ ]+ latest = [l for l in tags.splitlines() if "value=latest" in l][0]+ gate = latest.split("enable=", 1)[1].strip()+ assert sync_job["needs"] == "merge-studio"+ assert gate == sync_job["if"].strip(), (+ "the sync must be gated exactly like :latest, or a dispatch that pins refs "+ "would rewrite the public page for an image :latest does not point at"+ )+++def _run_sync(+ step: str,+ tmp_path: Path,+ *,+ live_after_patch: str,+ token: str = "tok",+):+ bin_dir = tmp_path / "bin"+ bin_dir.mkdir()+ log = tmp_path / "curl.log"+ # what the Hub reports after the PATCH; a file, so the README's backticks and+ # dollar signs never pass through the stub's shell+ live = tmp_path / "live.json"+ live.write_text(json.dumps({"full_description": live_after_patch}), encoding = "utf-8")+ (bin_dir / "curl").write_text(+ "#!/usr/bin/env bash\n"+ f"printf '%s\\n' \"$*\" >> {log}\n"+ 'case "$*" in\n'+ f' *auth/token*) printf \'{{"access_token": "{token}"}}\' ;;\n'+ " *-X\\ PATCH*) out=''; while [ $# -gt 0 ]; do [ \"$1\" = -o ] && out=$2; shift; done; : > \"$out\"; printf '200' ;;\n"+ f" *) cat {live} ;;\n"+ "esac\n",+ encoding = "utf-8",+ )+ (bin_dir / "curl").chmod(0o755)+ (tmp_path / "docker").mkdir()+ shutil.copy(HUB_README, tmp_path / "docker" / "DOCKERHUB.md")+ script = step.replace("${{ secrets.DOCKER_API_KEY }}", "not-a-secret")+ assert "${{" not in script, "unexpanded expression in the sync step"+ env = dict(os.environ)+ env["PATH"] = f"{bin_dir}{os.pathsep}" + env["PATH"]+ env["REGISTRY_USERNAME"] = "unsloth"+ env["IMAGE_NAME"] = "unsloth/unsloth"+ res = subprocess.run(+ ["bash", "-e", "-c", script],+ capture_output = True,+ text = True,+ env = env,+ cwd = str(tmp_path),+ timeout = 60,+ )+ return res, log.read_text(encoding = "utf-8") if log.exists() else ""+++def test_the_sync_patches_the_readme_and_confirms_it(sync_job: dict, tmp_path: Path):+ step = sync_job["steps"][-1]["run"]+ res, log = _run_sync(step, tmp_path, live_after_patch = HUB_README.read_text(encoding = "utf-8"))+ assert res.returncode == 0, res.stdout + res.stderr+ assert "-X PATCH https://hub.docker.com/v2/repositories/unsloth/unsloth/" in log+ assert "Authorization: Bearer tok" in log+++def test_the_sync_fails_when_the_page_did_not_change(sync_job: dict, tmp_path: Path):+ """A 200 from PATCH is not proof. The page is read back and compared, so a token+ without description rights cannot leave the job green and the page stale."""+ step = sync_job["steps"][-1]["run"]+ res, _ = _run_sync(step, tmp_path, live_after_patch = "# the old page")+ assert res.returncode != 0, "the sync reported success while the page stayed stale"+ assert "does not match" in res.stdout + res.stderr+++def test_the_sync_fails_without_a_token(sync_job: dict, tmp_path: Path):+ step = sync_job["steps"][-1]["run"]+ res, log = _run_sync(step, tmp_path, live_after_patch = "", token = "")+ assert res.returncode != 0+ assert "PATCH" not in log, "a PATCH was attempted with an empty token"