docker: Colab-grade JupyterLab and Studio UX for the Unsloth image

.github/workflows/docker-publish.yml

@@ -181,7 +181,7 @@ jobs:
       - name: Upload digest
         uses: actions/upload-artifact@v4
         with:
-          name: digests-base-${{ matrix.platform == 'linux/amd64' && 'amd64' || 'arm64' }}
+          name: digests-core-${{ matrix.platform == 'linux/amd64' && 'amd64' || 'arm64' }}
           path: /tmp/digests/*
           if-no-files-found: error
           retention-days: 1
@@ -208,7 +208,7 @@ jobs:
       - uses: actions/download-artifact@v4
         with:
           path: /tmp/digests
-          pattern: digests-base-*
+          pattern: digests-core-*
           merge-multiple: true
 
       - uses: docker/setup-buildx-action@v3
@@ -225,17 +225,17 @@ jobs:
         with:
           images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
           tags: |
-            # The lean training image publishes under the base- prefix; the
+            # The lean training image publishes under the core- prefix; the
             # full Studio image (build-studio/merge-studio below) owns
             # :latest, matching what the previous production image shipped.
-            # Only tag :base when the workflow ran on the default branch
+            # Only tag :core when the workflow ran on the default branch
             # AND the operator did NOT override unsloth_ref on dispatch.
             # Without the second condition a maintainer testing a feature
-            # SHA from main could overwrite :base with non-main source.
-            type=raw,value=base,enable=${{ github.ref == format('refs/heads/{0}', github.event.repository.default_branch) && github.event.inputs.unsloth_ref == '' }}
-            type=ref,event=tag,prefix=base-
-            type=schedule,pattern=base-nightly
-            type=sha,prefix=base-sha-,format=short
+            # SHA from main could overwrite :core with non-main source.
+            type=raw,value=core,enable=${{ github.ref == format('refs/heads/{0}', github.event.repository.default_branch) && github.event.inputs.unsloth_ref == '' }}
+            type=ref,event=tag,prefix=core-
+            type=schedule,pattern=core-nightly
+            type=sha,prefix=core-sha-,format=short
 
       - name: Create multi-arch manifest
         working-directory: /tmp/digests
@@ -380,8 +380,10 @@ jobs:
           images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
           tags: |
             # The full Studio image owns the unprefixed namespace, headed by
-            # :latest. Same :latest gating rationale as the base job.
+            # :latest, with a stable :studio alias. Same gating rationale as
+            # the core job.
             type=raw,value=latest,enable=${{ github.ref == format('refs/heads/{0}', github.event.repository.default_branch) && github.event.inputs.unsloth_ref == '' }}
+            type=raw,value=studio,enable=${{ github.ref == format('refs/heads/{0}', github.event.repository.default_branch) && github.event.inputs.unsloth_ref == '' }}
             type=ref,event=tag
             type=schedule,pattern=nightly
             type=sha,prefix=sha-,format=short
@@ -429,19 +431,19 @@ jobs:
         with:
           images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
           tags: |
-            type=raw,value=base,enable=${{ github.ref == format('refs/heads/{0}', github.event.repository.default_branch) && github.event.inputs.unsloth_ref == '' }}
-            type=ref,event=tag,prefix=base-
-            type=schedule,pattern=base-nightly
-            type=sha,prefix=base-sha-,format=short
+            type=raw,value=core,enable=${{ github.ref == format('refs/heads/{0}', github.event.repository.default_branch) && github.event.inputs.unsloth_ref == '' }}
+            type=ref,event=tag,prefix=core-
+            type=schedule,pattern=core-nightly
+            type=sha,prefix=core-sha-,format=short
 
       - name: Pull and smoke-test the base image
         run: |
           # Use the first tag from the metadata output -- that is the image we
-          # just published. Falls back to :base only when the metadata is
+          # just published. Falls back to :core only when the metadata is
           # empty (defensive; should not happen on default-branch runs).
           TAG="$(jq -r '.tags[0] // ""' <<<"$STEPS_META_BASE_JSON")"
           if [ -z "$TAG" ]; then
-              TAG="${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:base"
+              TAG="${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:core"
           fi
           echo "smoke-testing $TAG"
           docker pull "$TAG"
@@ -456,6 +458,7 @@ jobs:
           images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
           tags: |
             type=raw,value=latest,enable=${{ github.ref == format('refs/heads/{0}', github.event.repository.default_branch) && github.event.inputs.unsloth_ref == '' }}
+            type=raw,value=studio,enable=${{ github.ref == format('refs/heads/{0}', github.event.repository.default_branch) && github.event.inputs.unsloth_ref == '' }}
             type=ref,event=tag
             type=schedule,pattern=nightly
             type=sha,prefix=sha-,format=short

docker/.dockerignore

@@ -14,3 +14,20 @@
 !unsloth_run.py
 !unsloth_sync_notebooks.sh
 !unsloth_nb_content_sig.py
+!unsloth_nb_view.py
+!unsloth_nb_strip_colab.py
+!unsloth_colab_compat.py
+!jupyter
+!jupyter/overrides.json
+!jupyter/favicon.ico
+!jupyter/logo.png
+!jupyter/login.html
+!jupyter/install_sloth_stickers.py
+!jupyter/unsloth_labext
+!jupyter/unsloth_labext/package.json
+!jupyter/unsloth_labext/tsconfig.json
+!jupyter/unsloth_labext/.yarnrc.yml
+!jupyter/unsloth_labext/src
+!jupyter/unsloth_labext/src/**
+!jupyter/unsloth_labext/style
+!jupyter/unsloth_labext/style/**

docker/Dockerfile

@@ -285,18 +285,35 @@ RUN set -eux \
 #   omegaconf  TTS families + both NeMo-Gym RL notebooks' config objects
 #   einx  TTS codec tensor-rearrange (Llasa / Oute / Spark TTS)
 #   librosa  Whisper audio feature extraction (pairs with soundfile + torchcodec)
-#   decord  ERNIE-VL vision notebook video decode
 #   ftfy  Oute TTS text normalisation
+# decord (ERNIE-VL video decode) is installed separately below: it ships no
+# aarch64 wheel, so a hard install here would break the arm64 build.
 # librosa pulls numba/soxr/audioread; numba is already pinned >=0.65 (numpy 2.4
 # compatible) by the vLLM pass, so the resolve must NOT move torch/numpy/numba --
 # the assertion below fails the build loudly if it did.
+# Pinned (==) to the resolved, tested versions for reproducible rebuilds -- the
+# same convention as the cu128 core (torch/torchvision/torchaudio). Bump these
+# deliberately, not silently on the next build. Transitive deps of these are
+# captured by the full venv lockfile (docker/freeze.sh -> requirements.lock.txt).
 RUN ${VENV}/bin/uv pip install \
         --python ${VENV}/bin/python \
-        jupyterlab notebook ipywidgets matplotlib \
-        soundfile evaluate jiwer tensorboard langid easydict protobuf \
-        omegaconf einx librosa decord ftfy \
+        "jupyterlab==4.6.0" "notebook==7.6.0" "ipywidgets==8.1.8" "matplotlib==3.11.0" \
+        "soundfile==0.14.0" "evaluate==0.4.6" "jiwer==4.0.0" "tensorboard==2.20.0" \
+        "langid==1.1.6" "easydict==1.13" "protobuf==6.33.6" \
+        "omegaconf==2.3.1" "einx==0.4.3" "librosa==0.11.0" "ftfy==6.3.1" \
  && ${VENV}/bin/python -c "import torch, numpy, numba; from packaging.version import Version; assert torch.__version__.startswith('2.10.0'), torch.__version__; assert Version(numpy.__version__) >= Version('2.3'), numpy.__version__; assert Version(numba.__version__) >= Version('0.65'), numba.__version__; print('notebook-deps pins OK:', torch.__version__, numpy.__version__, numba.__version__)"
 
+# decord (ERNIE-VL video decode) publishes wheels only for x86_64 / win_amd64.
+# Install it on its own: HARD on amd64 (a missing/incompatible wheel is a real
+# regression there and must fail the build), fail-soft on arm64/other (no wheel
+# exists, so drop the ERNIE-VL video path rather than break the image build).
+RUN if [ "${TARGETARCH:-amd64}" = "amd64" ]; then \
+        ${VENV}/bin/uv pip install --python ${VENV}/bin/python "decord==0.6.0"; \
+    else \
+        ${VENV}/bin/uv pip install --python ${VENV}/bin/python "decord==0.6.0" \
+        || echo ">> decord skipped (no matching wheel for ${TARGETARCH:-}); ERNIE-VL video decode unavailable"; \
+    fi
+
 # Audio decode out of the box: the TTS/STT notebooks feed datasets' Audio
 # features, which decode through torchcodec. Three traps, all defended:
 #   * version pairing: torchcodec 0.10 pairs with torch 2.10 (newer builds
@@ -647,19 +664,22 @@ RUN mkdir -p ${HF_HOME} ${TRITON_CACHE_DIR}
 #   * unsloth-run: headless `unsloth-run <notebook|url>` that auto-picks the
 #     sidecar and executes every cell -- the robust driven path.
 # ---------------------------------------------------------------------------
-COPY unsloth_nb_compat.py unsloth_pip_shim.py unsloth_ipython_startup.py unsloth_run.py unsloth_sync_notebooks.sh unsloth_nb_content_sig.py /opt/unsloth-nb/
+COPY unsloth_nb_compat.py unsloth_pip_shim.py unsloth_ipython_startup.py unsloth_run.py unsloth_sync_notebooks.sh unsloth_nb_content_sig.py unsloth_nb_view.py unsloth_nb_strip_colab.py unsloth_colab_compat.py /opt/unsloth-nb/
 RUN set -eux \
  && SP=/opt/unsloth-venv/lib/python${PYTHON_VERSION}/site-packages \
  && cp /opt/unsloth-nb/unsloth_nb_compat.py "$SP/unsloth_nb_compat.py" \
- && chmod +x /opt/unsloth-nb/unsloth_pip_shim.py /opt/unsloth-nb/unsloth_run.py /opt/unsloth-nb/unsloth_sync_notebooks.sh /opt/unsloth-nb/unsloth_nb_content_sig.py \
+ && cp /opt/unsloth-nb/unsloth_colab_compat.py "$SP/unsloth_colab_compat.py" \
+ && chmod +x /opt/unsloth-nb/unsloth_pip_shim.py /opt/unsloth-nb/unsloth_run.py /opt/unsloth-nb/unsloth_sync_notebooks.sh /opt/unsloth-nb/unsloth_nb_content_sig.py /opt/unsloth-nb/unsloth_nb_view.py /opt/unsloth-nb/unsloth_nb_strip_colab.py \
  && mkdir -p /opt/unsloth-nb/bin \
  && for t in pip pip3 uv; do ln -sf /opt/unsloth-nb/unsloth_pip_shim.py /opt/unsloth-nb/bin/$t; done \
  && ln -sf /opt/unsloth-nb/unsloth_run.py /usr/local/bin/unsloth-run \
  && ln -sf /opt/unsloth-nb/unsloth_sync_notebooks.sh /usr/local/bin/unsloth-sync-notebooks \
  && ln -sf /opt/unsloth-nb/unsloth_nb_content_sig.py /usr/local/bin/unsloth-nb-content-sig \
+ && ln -sf /opt/unsloth-nb/unsloth_nb_view.py /usr/local/bin/unsloth-nb-view \
+ && ln -sf /opt/unsloth-nb/unsloth_nb_strip_colab.py /usr/local/bin/unsloth-nb-strip-colab \
  && mkdir -p /root/.ipython/profile_default/startup \
  && cp /opt/unsloth-nb/unsloth_ipython_startup.py /root/.ipython/profile_default/startup/00-unsloth-nb.py \
- && /opt/unsloth-venv/bin/python -c "import sys, glob; sys.path.insert(0, '$SP'); import unsloth_nb_compat; print('nb-compat OK; baked sidecars:', sorted(glob.glob('/opt/unsloth-venv/tf-sidecars/t_*')))"
+ && /opt/unsloth-venv/bin/python -c "import sys, glob; sys.path.insert(0, '$SP'); import unsloth_nb_compat, unsloth_colab_compat; print('nb-compat OK; baked sidecars:', sorted(glob.glob('/opt/unsloth-venv/tf-sidecars/t_*')))"
 # Shim dir AHEAD of the venv bin so `!pip`/`!uv` resolve to the shim, not the real tool.
 ENV PATH=/opt/unsloth-nb/bin:${PATH}
 

docker/Dockerfile.studio

@@ -1,8 +1,9 @@
 # Full Unsloth image: base training stack + Studio + JupyterLab + sshd.
 #
-# This is the image published as docker.io/unsloth/unsloth:latest. It layers
-# Unsloth Studio on top of the lean base image (Dockerfile, published under
-# the `base` tags) and runs the same service trio as the previous production
+# This is the image published as docker.io/unsloth/unsloth:studio (and the
+# default :latest). It layers Unsloth Studio on top of the lean core image
+# (Dockerfile, published under the `core` tags) and runs the same service trio
+# as the previous production
 # image: Studio on 8000, JupyterLab on 8888, key-only sshd on 22.
 #
 # Build (local):
@@ -28,6 +29,27 @@
 # images always ship the same stack.
 
 ARG BASE_IMAGE=unsloth-blackwell:test
+
+# --- builder stage: prebuild the Unsloth JupyterLab extension -----------------
+# Builds the named "Unsloth Dark" (Monokai) theme + the Colab-style Down/Up
+# cell-navigation keymap. Node lives ONLY in this throwaway stage; the final
+# image copies just the prebuilt static labextension, so the runtime stays
+# Node-free. Uses the base image's bundled jlpm + jupyterlab (version-matched).
+FROM ${BASE_IMAGE} AS labext-builder
+ENV DEBIAN_FRONTEND=noninteractive
+# JupyterLab 4.6's build tooling declares a Node >=20 engine; Ubuntu 24.04's
+# distro nodejs is 18, so pull Node 20 LTS from NodeSource (it bundles npm).
+# This stage is thrown away, so the extra apt sources never reach the runtime.
+RUN apt-get update \
+ && apt-get install -y --no-install-recommends ca-certificates curl gnupg git \
+ && curl -fsSL https://deb.nodesource.com/setup_20.x | bash - \
+ && apt-get install -y --no-install-recommends nodejs \
+ && rm -rf /var/lib/apt/lists/*
+COPY jupyter/unsloth_labext /opt/labext-src
+RUN cd /opt/labext-src \
+ && /opt/unsloth-venv/bin/jlpm install \
+ && /opt/unsloth-venv/bin/jlpm build:prod
+
 FROM ${BASE_IMAGE}
 
 # Studio source ref to clone. Defaults to `main`, but a CI publish pipeline
@@ -170,6 +192,46 @@ COPY fetch_llama_prebuilt.py /usr/local/lib/unsloth/fetch_llama_prebuilt.py
 # Optional public Cloudflare tunnel for JupyterLab (UNSLOTH_JUPYTER_CLOUDFLARE=1,
 # or `unsloth-jupyter-tunnel --force`); supervisord runs it as jupyter-cloudflare.
 COPY unsloth_jupyter_tunnel.sh /usr/local/bin/unsloth-jupyter-tunnel
+# JupyterLab defaults baked for every container: the named "Unsloth Dark"
+# (Monokai) theme with adaptive light/dark by system preference, a per-cell run
+# button that does NOT auto-advance, a labeled "Restart & Run All", windowing
+# disabled so collapsing a long output does not snap to the cell top,
+# ArrowDown/Up jumping to the TOP of the next/previous cell, and the official
+# Jupyter "get notified about news" prompt suppressed (fetchNews/checkForUpdates
+# off). overrides.json is the system-wide settings override (read from the base
+# venv's share/jupyter/lab/settings); the theme + keymap + Unsloth top-bar logo
+# ship as the prebuilt labextension built in the labext-builder stage above.
+COPY jupyter/overrides.json /opt/unsloth-venv/share/jupyter/lab/settings/overrides.json
+COPY --from=labext-builder /opt/labext-src/unsloth-jupyterlab/labextension /opt/unsloth-venv/share/jupyter/labextensions/unsloth-jupyterlab
+# Unsloth branding (all served by jupyter_server, so applied to its site-packages
+# the same way): replace the browser-tab favicon and the page logo with the
+# Unsloth logo, and brand the login screen (dark Unsloth-themed login.html).
+# Also disable + lock the stock top-left Jupyter logo plugin so the Unsloth logo
+# widget shipped by the labextension is the only one rendered in the top bar
+# (lock keeps users from re-enabling it in the UI).
+COPY jupyter/favicon.ico /tmp/unsloth-branding/favicon.ico
+COPY jupyter/logo.png /tmp/unsloth-branding/logo.png
+COPY jupyter/login.html /tmp/unsloth-branding/login.html
+COPY jupyter/install_sloth_stickers.py /tmp/unsloth-branding/install_sloth_stickers.py
+RUN JS="$(/opt/unsloth-venv/bin/python -c 'import os, jupyter_server; print(os.path.dirname(jupyter_server.__file__))')" \
+ && for n in favicon.ico favicon-notebook.ico favicon-file.ico favicon-terminal.ico; do \
+        cp /tmp/unsloth-branding/favicon.ico "${JS}/static/favicons/${n}"; \
+    done \
+ && cp /tmp/unsloth-branding/logo.png "${JS}/static/logo/logo.png" \
+ && cp /tmp/unsloth-branding/login.html "${JS}/templates/login.html" \
+    # Copy the curated Studio sloth stickers the login page rotates through into
+    # jupyter_server's static dir (sloth/NN.png). Fail-soft -- but scoped to ONLY
+    # the sticker step via the { ...; } group so a failure in a REQUIRED branding
+    # step above (JS resolve, favicon/logo/login copy) still fails the build
+    # instead of being swallowed by this fallback. If the Studio public folder
+    # ever moves, login.html's onerror falls back to the logo.
+ && { /opt/unsloth-venv/bin/python /tmp/unsloth-branding/install_sloth_stickers.py \
+        --src "${UNSLOTH_STUDIO_HOME}/src/studio/frontend/public/Sloth emojis" \
+        --dest "${JS}/static/sloth" \
+      || echo ">> sloth stickers not installed (login falls back to the Unsloth logo)"; } \
+ && rm -rf /tmp/unsloth-branding \
+ && /opt/unsloth-venv/bin/jupyter labextension disable @jupyterlab/application-extension:logo \
+ && /opt/unsloth-venv/bin/jupyter labextension lock @jupyterlab/application-extension:logo
 RUN chmod +x /usr/local/bin/unsloth-studio-launch \
              /usr/local/bin/unsloth-studio-update \
              /usr/local/bin/unsloth-llama-update \

docker/docker_confirm.ps1

@@ -21,7 +21,7 @@
 
 $ErrorActionPreference = "Continue"
 $IMAGE        = if ($env:IMAGE)        { $env:IMAGE }        else { "unsloth/unsloth:latest" }
-$BASE_IMAGE   = if ($env:BASE_IMAGE)   { $env:BASE_IMAGE }   else { "unsloth/unsloth:base" }
+$BASE_IMAGE   = if ($env:BASE_IMAGE)   { $env:BASE_IMAGE }   else { "unsloth/unsloth:core" }
 $GPUS         = if ($env:GPUS)         { $env:GPUS }         else { "auto" }
 $PORT_STUDIO  = if ($env:PORT_STUDIO)  { $env:PORT_STUDIO }  else { 18000 }
 $PORT_JUPYTER = if ($env:PORT_JUPYTER) { $env:PORT_JUPYTER } else { 18888 }

docker/docker_confirm.sh

@@ -23,7 +23,7 @@
 #     Studio chat / Jupyter / GGUF tooling still validate.
 #
 # Env overrides: IMAGE (default unsloth/unsloth:latest)
-#                BASE_IMAGE (default unsloth/unsloth:base)
+#                BASE_IMAGE (default unsloth/unsloth:core)
 #                GPUS=all|none|0|0,1   (default: auto-detect)
 #                PORT_STUDIO=18000  PORT_JUPYTER=18888
 #                WORK=~/unsloth_docker_test   (logs)
@@ -33,7 +33,7 @@
 set -uo pipefail
 
 IMAGE="${IMAGE:-unsloth/unsloth:latest}"
-BASE_IMAGE="${BASE_IMAGE:-unsloth/unsloth:base}"
+BASE_IMAGE="${BASE_IMAGE:-unsloth/unsloth:core}"
 GPUS="${GPUS:-auto}"
 PORT_STUDIO="${PORT_STUDIO:-18000}"
 PORT_JUPYTER="${PORT_JUPYTER:-18888}"

docker/fetch_llama_prebuilt.py

@@ -51,7 +51,9 @@ def resolve_latest_tag(repo: str) -> str:
         final_url = response.geturl()
     marker = "/releases/tag/"
     if marker not in final_url:
-        raise SystemExit(f"FAIL: could not resolve latest release of {repo} (landed on {final_url})")
+        raise SystemExit(
+            f"FAIL: could not resolve latest release of {repo} (landed on {final_url})"
+        )
     return final_url.rsplit(marker, 1)[1].strip("/")