Skip to content

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.

Docker publish: verify the Studio image env, and stop telling latest users to opt in to CPU (#11071)

Daniel Han87cb503f391a
diff --git a/.github/workflows/docker-publish.yml b/.github/workflows/docker-publish.yml
index 61f0dde1152..98824510f14 100644
--- a/.github/workflows/docker-publish.yml
+++ b/.github/workflows/docker-publish.yml
@@ -469,6 +469,22 @@ jobs:
UNSLOTH_STUDIO_ZOO_REF=${{ needs.prepare.outputs.zoo_ref }}
LLAMA_PREBUILT_TAG=${{ needs.prepare.outputs.llama_tag }}
+ # A GPU-free check on the artifact the registry serves, not on the Dockerfile
+ # text: an image-wide UNSLOTH_ALLOW_CPU reaches every process and turns off
+ # Unsloth's TRL trainer patches on GPU hosts (#10825), and the smoke-test job
+ # below needs a GPU runner this repo does not have. The image opts in to CPU
+ # hosts through UNSLOTH_IMAGE_ALLOW_CPU=1 instead; entrypoint.sh translates it.
+ - name: Assert the Studio image env cannot disable training
+ run: |
+ REF='${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}@${{ steps.build.outputs.digest }}'
+ ENV_JSON="$(docker buildx imagetools inspect "$REF" --format '{{json .Image}}' \
+ | jq -c '[.. | objects | select(has("config")) | .config.Env // []] | add')"
+ echo "$ENV_JSON" | jq -r '.[] | select(startswith("UNSLOTH_"))'
+ echo "$ENV_JSON" | jq -e 'index("UNSLOTH_IMAGE_ALLOW_CPU=1") != null' >/dev/null \
+ || { echo "::error::Studio image env lacks UNSLOTH_IMAGE_ALLOW_CPU=1"; exit 1; }
+ echo "$ENV_JSON" | jq -e 'map(select(startswith("UNSLOTH_ALLOW_CPU="))) | length == 0' >/dev/null \
+ || { echo "::error::Studio image env carries UNSLOTH_ALLOW_CPU, which disables Unsloth's TRL patches on GPU hosts"; exit 1; }
+
- name: Export digest
run: |
mkdir -p /tmp/digests
diff --git a/docker/DOCKERHUB.md b/docker/DOCKERHUB.md
index 970d832e189..3f3c38cb7c3 100644
--- a/docker/DOCKERHUB.md
+++ b/docker/DOCKERHUB.md
@@ -68,10 +68,11 @@ docker run --rm --gpus all --ipc=host -v "$PWD":/workspace/host \
### 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.
+`latest` starts without a GPU on its own. Studio chat with GGUF models, JupyterLab and the GGUF tooling work; training does not. `core` refuses to start without a GPU unless you opt in:
```bash
-docker run -d -e UNSLOTH_ALLOW_CPU=1 -p 8000:8000 -p 8888:8888 unsloth/unsloth
+docker run -d -p 8000:8000 -p 8888:8888 unsloth/unsloth
+docker run --rm -e UNSLOTH_ALLOW_CPU=1 unsloth/unsloth:core python -c "import unsloth"
```
## Supported GPUs
diff --git a/tests/python/test_docker_cpu_fallback.py b/tests/python/test_docker_cpu_fallback.py
index 033ec46d681..68f3d8e1deb 100644
--- a/tests/python/test_docker_cpu_fallback.py
+++ b/tests/python/test_docker_cpu_fallback.py
@@ -275,6 +275,24 @@ class TestStudioImageAllowsCpu:
re.M,
), "Dockerfile.studio does not bundle its own entrypoint"
+ def test_the_studio_image_keeps_the_base_entrypoint_directive(self):
+ """The bundled file replaces the base's copy at the SAME path and the base's
+ ENTRYPOINT directive stays: a second ENTRYPOINT or a different destination
+ would let the two images drift apart again."""
+ studio = open(_STUDIO_DF, encoding = "utf-8").read()
+ base = open(_BASE_DF, encoding = "utf-8").read()
+ dest = re.findall(r"^COPY\s+entrypoint\.sh\s+(\S+)\s*$", base, re.M)
+ assert dest == ["/usr/local/bin/unsloth-entrypoint"], dest
+ assert re.findall(r"^COPY\s+entrypoint\.sh\s+(\S+)\s*$", studio, re.M) == dest
+ # The copy alone proves nothing: the base must still RUN that file, or the
+ # inherited ENTRYPOINT no longer translates UNSLOTH_IMAGE_ALLOW_CPU.
+ assert re.findall(r"^\s*ENTRYPOINT\s+(.+?)\s*$", base, re.M) == [
+ '["/usr/local/bin/unsloth-entrypoint"]'
+ ], "base Dockerfile no longer runs the bundled entrypoint"
+ assert not re.search(
+ r"^\s*ENTRYPOINT\b", studio, re.M
+ ), "Dockerfile.studio must inherit the base ENTRYPOINT, not declare its own"
+
def test_the_base_training_image_keeps_the_strict_check(self):
"""FastLanguageModel genuinely needs a GPU, so :core must NOT default it."""
body = open(_BASE_DF, encoding = "utf-8").read()