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.

Add Unsloth Docker images (base + Studio) for any NVIDIA GPU host, Ampere through Blackwell (#5748)

Daniel Han58255747fece
diff --git a/.github/workflows/docker-publish.yml b/.github/workflows/docker-publish.yml
new file mode 100644
index 00000000000..a05eaaa1432
--- /dev/null
+++ b/.github/workflows/docker-publish.yml
@@ -0,0 +1,552 @@
+# Builds and publishes the Blackwell-compatible Unsloth Docker image.
+#
+# No GPU runner needed: cu128 wheels are fat binaries, the build-time check uses
+# torch._C._cuda_getArchFlags(), and UNSLOTH_COMPILE_DISABLE=1 blocks GPU-keyed JIT.
+#
+# Required secret: DOCKER_API_KEY, a Docker Hub ORGANIZATION access token for the
+# unsloth org. It logs in as REGISTRY_USERNAME below, which is the org name.
+# Optional variable HAS_GPU_RUNNER='true' gates the smoke-test job.
+
+name: Publish Blackwell Docker image
+
+on:
+ push:
+ branches: [main]
+ tags: ['v*']
+ schedule:
+ # Daily. Actions cron is UTC with no DST handling, so this is 11:17 in San
+ # Francisco under PDT and drifts to 10:17 under PST; no expression holds
+ # 11:00 local all year. Minute is off-the-hour on purpose: runs scheduled on
+ # the hour queue behind the platform-wide peak and can be dropped.
+ - cron: '17 18 * * *'
+ workflow_dispatch:
+ inputs:
+ unsloth_ref:
+ # The stable-tag gates require this EMPTY, so a non-blank default would make
+ # every UI-default dispatch publish SHA tags only.
+ description: 'unsloth git ref override (blank = dispatched branch + stable tags)'
+ required: false
+ default: ''
+ unsloth_zoo_ref:
+ description: 'unsloth-zoo git ref to bake in'
+ required: false
+ default: 'main'
+ llama_prebuilt_tag:
+ description: 'unslothai/llama.cpp prebuilt release tag to bake (blank = newest)'
+ required: false
+ default: ''
+ notebooks_ref:
+ description: 'unslothai/notebooks git ref to bake (resolved to one commit)'
+ required: false
+ default: 'main'
+
+env:
+ REGISTRY: docker.io
+ IMAGE_NAME: unsloth/unsloth
+ # DOCKER_API_KEY is an ORGANIZATION access token, and Docker Hub authenticates an
+ # OAT as the ORGANISATION, not as whoever created it. So this is the org name and
+ # must stay that way: putting a person's account here fails every login, which is
+ # why it is spelled out rather than left to look like an arbitrary owner field.
+ # Not a secret, and named once so the four login steps cannot drift apart.
+ REGISTRY_USERNAME: unsloth
+
+# Serialise per-ref runs, EXCEPT on main where each commit gets its own group: a
+# shared group does not queue a main burst, it DISCARDS it (GitHub cancels any PENDING
+# run the moment a newer one is queued), so the earlier commit would publish no image
+# at all. The accepted cost is that two main commits can race to retag :core/:latest,
+# which is self-correcting on the next push, where a cancelled run leaves that commit
+# with no image at all. Each published image is still internally coherent: the digest
+# handoff and the smoke test resolve a :core-sha-/:sha- tag rather than tags[0], and
+# then verify that the manifest behind it holds the arches THIS run pushed. That last
+# step is the load-bearing one, because the sha tag is only immutable across COMMITS:
+# a branch push and a lightweight v* tag push at one commit produce the same short
+# sha, and the concurrency group is keyed on the ref, so those two runs never wait for
+# each other and both write that name.
+# tests/studio/test_main_runs_survive_merge_bursts.py enforces this shape.
+concurrency:
+ group: docker-publish-${{ github.ref }}-${{ github.ref == 'refs/heads/main' && github.sha || '' }}
+ cancel-in-progress: false
+
+# Pushes use Docker Hub registry creds, not GITHUB_TOKEN, so read is enough.
+permissions:
+ contents: read
+
+jobs:
+ # Resolve every upstream ref ONCE, so both arch legs and Studio bake identical bits.
+ prepare:
+ runs-on: ubuntu-latest
+ timeout-minutes: 5
+ permissions:
+ contents: read
+ outputs:
+ llama_tag: ${{ steps.llama.outputs.tag }}
+ unsloth_ref: ${{ steps.unsloth_ref.outputs.ref }}
+ zoo_ref: ${{ steps.zoo_ref.outputs.ref }}
+ notebooks_commit: ${{ steps.notebooks.outputs.commit }}
+ steps:
+ - name: Resolve llama.cpp prebuilt tag
+ id: llama
+ env:
+ INPUT_TAG: ${{ github.event.inputs.llama_prebuilt_tag }}
+ run: |
+ TAG="$INPUT_TAG"
+ if [ -z "$TAG" ]; then
+ # No explicit `shell:`, so `bash -e` runs WITHOUT pipefail and a failing
+ # curl inside `curl | sed` is lost: the step exits 0 with the MUTABLE
+ # tag=latest, which every consumer then resolves again.
+ if ! REDIRECT="$(curl -fsSL -o /dev/null -w '%{url_effective}' \
+ https://github.com/unslothai/llama.cpp/releases/latest)"; then
+ echo "::error::unslothai/llama.cpp unreachable; cannot resolve the newest prebuilt tag"
+ exit 1
+ fi
+ TAG="$(printf '%s\n' "$REDIRECT" | sed -n 's#.*/releases/tag/##p')"
+ if [ -z "$TAG" ]; then
+ echo "::error::/releases/latest did not redirect to a release tag (landed on ${REDIRECT})"
+ exit 1
+ fi
+ fi
+ echo "tag=${TAG}" >> "$GITHUB_OUTPUT"
+ echo "llama.cpp prebuilt tag: ${TAG}"
+
+ # Precedence: dispatch input, else pushed tag, else trigger sha, else main.
+ - name: Resolve unsloth ref
+ id: unsloth_ref
+ env:
+ INPUT_REF: ${{ github.event.inputs.unsloth_ref }}
+ TAG_REF: ${{ startsWith(github.ref, 'refs/tags/') && github.ref_name || '' }}
+ PUSH_SHA: ${{ github.sha }}
+ run: |
+ REF="$INPUT_REF"
+ [ -n "$REF" ] || REF="$TAG_REF"
+ [ -n "$REF" ] || REF="$PUSH_SHA"
+ REF="${REF:-main}"
+ if printf '%s' "$REF" | grep -Eq '^[0-9a-f]{40}$'; then
+ SHA="$REF"
+ else
+ # ls-remote exits 0 whether or not a ref matched, so a non-zero exit means
+ # the remote was never reached and the fallback would hand a MUTABLE name
+ # to three builds that each resolve it again.
+ if ! LS_OUT="$(git ls-remote https://github.com/unslothai/unsloth "$REF")"; then
+ echo "::error::unslothai/unsloth unreachable; cannot freeze ref '${REF}' to a sha"
+ exit 1
+ fi
+ SHA="$(printf '%s\n' "$LS_OUT" | awk 'NR==1{print $1}')"
+ [ -n "$SHA" ] || SHA="$REF"
+ fi
+ echo "ref=${SHA}" >> "$GITHUB_OUTPUT"
+ echo "unsloth ref: ${SHA}"
+
+ # only when the tag exists there: unsloth's v* tags are Studio releases
+ - name: Resolve unsloth-zoo ref
+ id: zoo_ref
+ run: |
+ REF="${{ github.event.inputs.unsloth_zoo_ref }}"
+ if [ -z "$REF" ] && [ "${{ startsWith(github.ref, 'refs/tags/') }}" = "true" ]; then
+ # git documents status 2 as "reached the remote, no matching ref"; any
+ # other non-zero means the lookup never happened, so swallowing both
+ # lets a transport blip pair the unsloth tag with zoo main.
+ _rc=0
+ git ls-remote --exit-code --tags https://github.com/unslothai/unsloth-zoo \
+ "refs/tags/${{ github.ref_name }}" >/dev/null 2>&1 || _rc=$?
+ if [ "$_rc" = "0" ]; then
+ REF="${{ github.ref_name }}"
+ elif [ "$_rc" != "2" ]; then
+ echo "::error::unslothai/unsloth-zoo unreachable (git ls-remote exit ${_rc}); cannot tell whether it carries tag '${{ github.ref_name }}'"
+ exit 1
+ fi
+ fi
+ REF="${REF:-main}"
+ if printf '%s' "$REF" | grep -Eq '^[0-9a-f]{40}$'; then
+ SHA="$REF"
+ else
+ if ! LS_OUT="$(git ls-remote https://github.com/unslothai/unsloth-zoo "$REF")"; then
+ echo "::error::unslothai/unsloth-zoo unreachable; cannot freeze ref '${REF}' to a sha"
+ exit 1
+ fi
+ SHA="$(printf '%s\n' "$LS_OUT" | awk 'NR==1{print $1}')"
+ [ -n "$SHA" ] || SHA="$REF"
+ fi
+ echo "ref=${SHA}" >> "$GITHUB_OUTPUT"
+ echo "unsloth-zoo ref: ${SHA}"
+
+ # one commit, so baked templates + .unsloth_template_commit match across legs
+ - name: Resolve unsloth/notebooks commit
+ id: notebooks
+ env:
+ INPUT_REF: ${{ github.event.inputs.notebooks_ref }}
+ run: |
+ REF="${INPUT_REF:-main}"
+ if printf '%s' "$REF" | grep -Eq '^[0-9a-f]{40}$'; then
+ SHA="$REF"
+ else
+ if ! LS_OUT="$(git ls-remote https://github.com/unslothai/notebooks "$REF")"; then
+ echo "::error::unslothai/notebooks unreachable; cannot freeze ref '${REF}' to a sha"
+ exit 1
+ fi
+ SHA="$(printf '%s\n' "$LS_OUT" | awk 'NR==1{print $1}')"
+ [ -n "$SHA" ] || SHA="$REF"
+ fi
+ echo "commit=${SHA}" >> "$GITHUB_OUTPUT"
+ echo "notebooks commit: ${SHA}"
+
+ build:
+ needs: prepare
+ strategy:
+ fail-fast: false
+ matrix:
+ include:
+ - platform: linux/amd64
+ runner: ubuntu-latest
+ - platform: linux/arm64
+ runner: ubuntu-24.04-arm
+ runs-on: ${{ matrix.runner }}
+ timeout-minutes: 90
+ permissions:
+ contents: read
+ packages: write
+
+ steps:
+ - uses: actions/checkout@v4
+
+ - name: Reclaim disk
+ run: |
+ # unused toolchains; paths differ across runners, hence `|| true`
+ sudo rm -rf /usr/share/dotnet /usr/local/lib/android /opt/ghc \
+ /opt/hostedtoolcache "$AGENT_TOOLSDIRECTORY" \
+ /usr/local/.ghcup /usr/share/swift \
+ /usr/local/share/powershell /usr/local/lib/node_modules \
+ /usr/local/julia* /opt/microsoft /usr/share/miniconda \
+ /opt/az /usr/local/share/boost /usr/local/share/chromium || true
+ sudo docker image prune -af >/dev/null 2>&1 || true
+ df -h /
+
+ - uses: docker/setup-buildx-action@v3
+
+ - name: Log in to Docker Hub
+ uses: docker/login-action@v3
+ with:
+ username: ${{ env.REGISTRY_USERNAME }}
+ password: ${{ secrets.DOCKER_API_KEY }}
+
+ - name: Resolve labels
+ id: meta
+ uses: docker/metadata-action@v5
+ with:
+ images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
+
+ - name: Build and push (per-arch by digest)
+ id: build
+ uses: docker/build-push-action@v6
+ with:
+ context: ./docker
+ file: ./docker/Dockerfile
+ platforms: ${{ matrix.platform }}
+ labels: ${{ steps.meta.outputs.labels }}
+ cache-from: type=gha,scope=build-${{ matrix.platform }}
+ cache-to: type=gha,scope=build-${{ matrix.platform }},mode=max
+ outputs: type=image,name=${{ env.REGISTRY }}/${{ env.IMAGE_NAME }},push-by-digest=true,name-canonical=true,push=true
+ # Keep prose OUT of build-args: build-push-action forwards every non-empty
+ # line verbatim, so a #-line becomes a bogus --build-arg.
+ build-args: |
+ CUDA_VERSION=12.8.1
+ UBUNTU_VERSION=24.04
+ PYTHON_VERSION=3.12
+ UNSLOTH_REF=${{ needs.prepare.outputs.unsloth_ref }}
+ UNSLOTH_ZOO_REF=${{ needs.prepare.outputs.zoo_ref }}
+ LLAMA_PREBUILT_TAG=${{ needs.prepare.outputs.llama_tag }}
+ UNSLOTH_NOTEBOOKS_REF=${{ needs.prepare.outputs.notebooks_commit }}
+
+ - name: Export digest
+ run: |
+ mkdir -p /tmp/digests
+ digest='${{ steps.build.outputs.digest }}'
+ touch "/tmp/digests/${digest#sha256:}"
+
+ - name: Upload digest
+ uses: actions/upload-artifact@v4
+ with:
+ name: digests-core-${{ matrix.platform == 'linux/amd64' && 'amd64' || 'arm64' }}
+ path: /tmp/digests/*
+ if-no-files-found: error
+ retention-days: 1
+
+ merge:
+ runs-on: ubuntu-latest
+ needs: build
+ timeout-minutes: 15
+ permissions:
+ contents: read
+ packages: write
+ outputs:
+ digest: ${{ steps.manifest_digest.outputs.digest }}
+ steps:
+ - uses: actions/download-artifact@v4
+ with:
+ path: /tmp/digests
+ pattern: digests-core-*
+ merge-multiple: true
+
+ - uses: docker/setup-buildx-action@v3
+
+ - name: Log in to Docker Hub
+ uses: docker/login-action@v3
+ with:
+ username: ${{ env.REGISTRY_USERNAME }}
+ password: ${{ secrets.DOCKER_API_KEY }}
+
+ - name: Resolve tags
+ id: meta
+ uses: docker/metadata-action@v5
+ with:
+ images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
+ # latest=auto would tag :latest on a v* push, colliding with the Studio image
+ flavor: latest=false
+ tags: |
+ # only on the default branch AND with no baked input overridden on
+ # dispatch, else a feature ref overwrites :core with non-main bits
+ type=raw,value=core,enable=${{ 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 == '' }}
+ 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
+ run: |
+ docker buildx imagetools create \
+ $(jq -cr '.tags | map("-t " + .) | join(" ")' <<<"$DOCKER_METADATA_OUTPUT_JSON") \
+ $(printf '${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}@sha256:%s ' *)
+
+ - name: Inspect the result
+ run: |
+ for tag in $(jq -r '.tags[]' <<<"$DOCKER_METADATA_OUTPUT_JSON"); do
+ echo "=== $tag ==="
+ docker buildx imagetools inspect "$tag"
+ done
+
+ - name: Export manifest digest
+ id: manifest_digest
+ working-directory: /tmp/digests
+ run: |
+ # NOT tags[0]: metadata-action sorts by priority (raw=200 above sha=100), so
+ # on a main push that is the mutable :core, which an unserialised second run
+ # can retag between the manifest creation and this inspection.
+ TAG="$(jq -r '([.tags[] | select(contains(":core-sha-"))] | first) // .tags[0]' <<<"$DOCKER_METADATA_OUTPUT_JSON")"
+ DIGEST="$(docker buildx imagetools inspect "$TAG" --format '{{json .Manifest.Digest}}' | tr -d '"')"
+ test -n "$DIGEST"
+ # :core-sha- is immutable across COMMITS, which is the only case the tag
+ # choice above defends against. It is NOT unique across REFS: a branch push
+ # and a lightweight v* tag push at the same commit produce the same short
+ # sha, and the concurrency group is keyed on the ref, so the two runs are
+ # never serialised against each other and both write this name. Confirm the
+ # manifest we are about to hand to build-studio really is the one this run
+ # pushed, because baking another run's base image is silent otherwise.
+ REF="${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}@${DIGEST}"
+ CHILDREN="$(docker buildx imagetools inspect --raw "$REF" | jq -r '.manifests[]?.digest')"
+ missing=0
+ for d in *; do
+ grep -qxF "sha256:$d" <<<"$CHILDREN" || {
+ echo "::error::${TAG} resolved to ${DIGEST}, which does not contain the sha256:${d} this run pushed; another ref at this commit retagged it"
+ missing=1
+ }
+ done
+ test "$missing" = 0
+ echo "digest=${DIGEST}" >> "$GITHUB_OUTPUT"
+ echo "base manifest: ${TAG} @ ${DIGEST}"
+
+ # Full image (:latest). The arm64 leg builds Studio's vite frontend natively.
+ build-studio:
+ needs: [prepare, merge]
+ strategy:
+ fail-fast: false
+ matrix:
+ include:
+ - platform: linux/amd64
+ runner: ubuntu-latest
+ - platform: linux/arm64
+ runner: ubuntu-24.04-arm
+ runs-on: ${{ matrix.runner }}
+ timeout-minutes: 150
+ permissions:
+ contents: read
+ packages: write
+ steps:
+ - uses: actions/checkout@v4
+
+ - name: Reclaim disk
+ run: |
+ # unused toolchains; paths differ across runners, hence `|| true`
+ sudo rm -rf /usr/share/dotnet /usr/local/lib/android /opt/ghc \
+ /opt/hostedtoolcache "$AGENT_TOOLSDIRECTORY" \
+ /usr/local/.ghcup /usr/share/swift \
+ /usr/local/share/powershell /usr/local/lib/node_modules \
+ /usr/local/julia* /opt/microsoft /usr/share/miniconda \
+ /opt/az /usr/local/share/boost /usr/local/share/chromium || true
+ sudo docker image prune -af >/dev/null 2>&1 || true
+ df -h /
+
+ - uses: docker/setup-buildx-action@v3
+
+ - name: Log in to Docker Hub
+ uses: docker/login-action@v3
+ with:
+ username: ${{ env.REGISTRY_USERNAME }}
+ password: ${{ secrets.DOCKER_API_KEY }}
+
+ - name: Resolve labels
+ id: meta
+ uses: docker/metadata-action@v5
+ with:
+ images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
+
+ - name: Build and push (per-arch by digest)
+ id: build
+ uses: docker/build-push-action@v6
+ with:
+ context: ./docker
+ file: ./docker/Dockerfile.studio
+ platforms: ${{ matrix.platform }}
+ labels: ${{ steps.meta.outputs.labels }}
+ # mode=max here would blow the 10GB GHA quota and evict the base build's cache
+ cache-from: type=gha,scope=studio-${{ matrix.platform }}
+ cache-to: type=gha,scope=studio-${{ matrix.platform }},mode=min
+ outputs: type=image,name=${{ env.REGISTRY }}/${{ env.IMAGE_NAME }},push-by-digest=true,name-canonical=true,push=true
+ # the same values the base build baked, so Studio matches it even if upstream
+ # moved mid-run (build-args must be KEY=VALUE only)
+ build-args: |
+ BASE_IMAGE=${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}@${{ needs.merge.outputs.digest }}
+ UNSLOTH_STUDIO_REF=${{ needs.prepare.outputs.unsloth_ref }}
+ UNSLOTH_STUDIO_ZOO_REF=${{ needs.prepare.outputs.zoo_ref }}
+ LLAMA_PREBUILT_TAG=${{ needs.prepare.outputs.llama_tag }}
+
+ - name: Export digest
+ run: |
+ mkdir -p /tmp/digests
+ digest='${{ steps.build.outputs.digest }}'
+ touch "/tmp/digests/${digest#sha256:}"
+
+ - name: Upload digest
+ uses: actions/upload-artifact@v4
+ with:
+ name: digests-studio-${{ matrix.platform == 'linux/amd64' && 'amd64' || 'arm64' }}
+ path: /tmp/digests/*
+ if-no-files-found: error
+ retention-days: 1
+
+ merge-studio:
+ runs-on: ubuntu-latest
+ needs: build-studio
+ timeout-minutes: 15
+ permissions:
+ contents: read
+ packages: write
+ outputs:
+ digest: ${{ steps.studio_manifest_digest.outputs.digest }}
+ steps:
+ - uses: actions/download-artifact@v4
+ with:
+ path: /tmp/digests
+ pattern: digests-studio-*
+ merge-multiple: true
+
+ - uses: docker/setup-buildx-action@v3
+
+ - name: Log in to Docker Hub
+ uses: docker/login-action@v3
+ with:
+ username: ${{ env.REGISTRY_USERNAME }}
+ password: ${{ secrets.DOCKER_API_KEY }}
+
+ - name: Resolve tags
+ id: meta
+ uses: docker/metadata-action@v5
+ with:
+ images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
+ # latest=false disables the implicit latest=auto, which would emit :latest on
+ # a v* tag push and bypass the default-branch-only gate below
+ flavor: latest=false
+ tags: |
+ type=raw,value=latest,enable=${{ 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 == '' }}
+ type=raw,value=studio,enable=${{ 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 == '' }}
+ type=ref,event=tag
+ type=schedule,pattern=nightly
+ type=sha,prefix=sha-,format=short
+
+ - name: Create multi-arch manifest
+ working-directory: /tmp/digests
+ run: |
+ docker buildx imagetools create \
+ $(jq -cr '.tags | map("-t " + .) | join(" ")' <<<"$DOCKER_METADATA_OUTPUT_JSON") \
+ $(printf '${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}@sha256:%s ' *)
+
+ - name: Inspect the result
+ run: |
+ for tag in $(jq -r '.tags[]' <<<"$DOCKER_METADATA_OUTPUT_JSON"); do
+ echo "=== $tag ==="
+ docker buildx imagetools inspect "$tag"
+ done
+
+ - name: Export manifest digest
+ id: studio_manifest_digest
+ working-directory: /tmp/digests
+ run: |
+ # Same reasoning as the base merge: :sha- is shared by every ref sitting on
+ # this commit, so resolve it once here and hand the smoke test an immutable
+ # digest rather than a name another run can retag under it.
+ TAG="$(jq -r '([.tags[] | select(contains(":sha-"))] | first) // .tags[0]' <<<"$DOCKER_METADATA_OUTPUT_JSON")"
+ DIGEST="$(docker buildx imagetools inspect "$TAG" --format '{{json .Manifest.Digest}}' | tr -d '"')"
+ test -n "$DIGEST"
+ REF="${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}@${DIGEST}"
+ CHILDREN="$(docker buildx imagetools inspect --raw "$REF" | jq -r '.manifests[]?.digest')"
+ missing=0
+ for d in *; do
+ grep -qxF "sha256:$d" <<<"$CHILDREN" || {
+ echo "::error::${TAG} resolved to ${DIGEST}, which does not contain the sha256:${d} this run pushed; another ref at this commit retagged it"
+ missing=1
+ }
+ done
+ test "$missing" = 0
+ echo "digest=${DIGEST}" >> "$GITHUB_OUTPUT"
+ echo "studio manifest: ${TAG} @ ${DIGEST}"
+
+ smoke-test:
+ needs: [merge, merge-studio]
+ if: ${{ vars.HAS_GPU_RUNNER == 'true' }}
+ runs-on: [self-hosted, gpu]
+ timeout-minutes: 30
+ steps:
+ - uses: actions/checkout@v4
+
+ # Both images are pulled by the digest their merge job resolved and verified, so
+ # there is no tag to re-derive here and no `enable=` expression to keep in step
+ # with the merge jobs' gates.
+ - name: Pull and smoke-test the base image
+ run: |
+ # By digest, not by name. Every ref sitting on this commit publishes the
+ # same :core-sha- tag, and those runs are in different concurrency groups,
+ # so a name resolved here can be another run's image. merge already had to
+ # resolve this digest to hand build-studio a base, and it verified that the
+ # manifest is the one it pushed.
+ REF="${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}@${{ needs.merge.outputs.digest }}"
+ echo "smoke-testing $REF"
+ docker pull "$REF"
+ docker run --rm --gpus all "$REF" python /workspace/smoke_test.py
+
+ - name: Boot the full image and probe Studio + Jupyter
+ run: |
+ REF="${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}@${{ needs.merge-studio.outputs.digest }}"
+ echo "booting $REF"
+ docker pull "$REF"
+ CID="$(docker run -d --gpus all -p 18000:8000 -p 18888:8888 "$REF")"
+ trap 'docker logs --tail 100 "$CID"; docker rm -f "$CID"' EXIT
+ ok_studio=0; ok_jupyter=0
+ for i in $(seq 1 60); do
+ if curl -fsS http://localhost:18000/api/health >/dev/null 2>&1; then ok_studio=1; fi
+ # /api returns 403 (the launcher sets a password hash); /login is
+ # unauthenticated and 200s once up
+ if curl -fsS http://localhost:18888/login >/dev/null 2>&1; then ok_jupyter=1; fi
+ [ "$ok_studio" = 1 ] && [ "$ok_jupyter" = 1 ] && break
+ sleep 5
+ done
+ [ "$ok_studio" = 1 ] || { echo "Studio /api/health never went healthy"; exit 1; }
+ [ "$ok_jupyter" = 1 ] || { echo "Jupyter /login never responded"; exit 1; }
+ echo "Studio + Jupyter healthy"
diff --git a/.github/workflows/studio-backend-ci.yml b/.github/workflows/studio-backend-ci.yml
index a7bd72242e1..23b7cc1d0da 100644
--- a/.github/workflows/studio-backend-ci.yml
+++ b/.github/workflows/studio-backend-ci.yml
@@ -30,6 +30,9 @@ on:
- 'unsloth/**'
- 'unsloth_cli/**'
- 'tests/**'
+ # The validate_studio_features.py step below guards docker/jupyter and the
+ # docker notebook helpers, so a docker-only change must trigger this CI.
+ - 'docker/**'
# The root installers: tests/sh/*.sh and tests/studio/install/* assert
# against these two files, so a change here must run the suite that
# covers it. Without them an install-only edit (the shape most AMD/ROCm
@@ -537,6 +540,11 @@ jobs:
[ "$found" -gt 0 ] || { echo "::error::no shell tests discovered under tests/sh"; exit 1; }
echo "ran $found shell installer test files"
+ - name: Docker JupyterLab/notebook feature validation
+ # Named validate_studio_features.py (not test_*.py) so pytest skips it;
+ # run explicitly so notebook/Colab/branding regressions fail CI.
+ run: python tests/validate_studio_features.py
+
- name: Save the pip cache
if: always()
uses: ./.github/actions/pip-cache-save
diff --git a/.gitignore b/.gitignore
index 0a3a767b9b6..5f406be9fae 100644
--- a/.gitignore
+++ b/.gitignore
@@ -237,6 +237,8 @@ package-lock.json
!studio/backend/core/data_recipe/oxc-validator/package-lock.json
!studio/package-lock.json
llama.cpp/
+async_task_outputs/
+individual_reviews/
# Stray "~" dir some tools create from a literal ~ TMPDIR; never part of the repo.
~/
diff --git a/docker/.dockerignore b/docker/.dockerignore
new file mode 100644
index 00000000000..18ff6a52eb6
--- /dev/null
+++ b/docker/.dockerignore
@@ -0,0 +1,37 @@
+**
+!Dockerfile
+!entrypoint.sh
+!smoke_test.py
+!fetch_llama_prebuilt.py
+!supervisord.conf
+!studio_launch.sh
+!unsloth_studio_update.sh
+!unsloth_llama_update.sh
+!unsloth_jupyter_tunnel.sh
+!unsloth_nb_compat.py
+!unsloth_pip_shim.py
+!unsloth_nb_pip_magic.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
+!jupyter
+!jupyter/unsloth_branding.py
+!jupyter/jupyter_server_config.d
+!jupyter/jupyter_server_config.d/**
+!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/**
diff --git a/docker/Dockerfile b/docker/Dockerfile
new file mode 100644
index 00000000000..7af952b7e61
--- /dev/null
+++ b/docker/Dockerfile
@@ -0,0 +1,635 @@
+# syntax=docker/dockerfile:1.7
+# -----------------------------------------------------------------------------
+# Unsloth + unsloth-zoo for every current NVIDIA arch (Turing -> Blackwell),
+# on linux/amd64 and linux/arm64.
+#
+# Why it works:
+# * cu128 wheels ship native SASS (no PTX), verified via `cuobjdump --list-elf`:
+# amd64: sm_70 sm_75 sm_80 sm_86 sm_90 sm_100 sm_120
+# arm64: sm_80 sm_90 sm_90a sm_100 sm_100a sm_120 sm_120a
+# * SASS is forward-compatible within a major: sm_86->sm_89 (Ada),
+# sm_100->sm_103 (B300/GB300), sm_120->sm_121 (DGX Spark/GB10), so every
+# non-Jetson GPU on https://developer.nvidia.com/cuda/gpus runs precompiled
+# SASS (torch, llama.cpp, source-built ops).
+# * Triton kernels JIT per-device at first run; the bundled cu12.8 ptxas/NVRTC
+# cannot emit compute_103/compute_121, so the cu13 override below handles
+# amd64 sm_103 and arm64 sm_121 (SASS still runs there via forward-compat, so
+# only JIT-heavy paths need it).
+# * Rare source builds compile against
+# TORCH_CUDA_ARCH_LIST="7.5;8.0;8.6;8.9;9.0;10.0;12.0+PTX"; the host GPU is
+# irrelevant, nvcc emits whatever the arch list says.
+#
+# Cross-arch build (arm64 / sm_121): built via QEMU binfmt on an x86_64 host
+# (`docker run --privileged --rm tonistiigi/binfmt --install all` once, then
+# `docker buildx build --platform linux/arm64 ...`). QEMU is build-time only;
+# the image runs natively on aarch64. xformers has no cu128 aarch64 wheel, so
+# arm64 falls back to Unsloth's SDPA (~5-10% slower, functionally complete).
+#
+# Build host needs Docker buildkit + buildx, and QEMU binfmt for arm64-on-x86_64;
+# nvidia-container-toolkit only for test-time `--gpus all`. No GPU at build time.
+# -----------------------------------------------------------------------------
+
+ARG CUDA_VERSION=12.8.1
+ARG UBUNTU_VERSION=24.04
+ARG PYTHON_VERSION=3.12
+
+# Stage 1: builder -- toolkit + dev headers, builds any source extensions.
+FROM nvidia/cuda:${CUDA_VERSION}-cudnn-devel-ubuntu${UBUNTU_VERSION} AS builder
+
+# TARGETARCH (buildx: amd64/arm64) selects the unsloth extras matching the
+# wheels available for the platform (xformers aarch64 gap -- see header).
+ARG TARGETARCH
+ARG PYTHON_VERSION
+ENV DEBIAN_FRONTEND=noninteractive \
+ PIP_NO_CACHE_DIR=1 \
+ PIP_DISABLE_PIP_VERSION_CHECK=1 \
+ PYTHONDONTWRITEBYTECODE=1 \
+ PYTHONUNBUFFERED=1 \
+ # Cross-compile for every current NVIDIA arch (developer.nvidia.com/cuda/gpus):
+ # sm_75 Turing (T4, RTX 20xx) | sm_80 A100/A30 | sm_86 A40/RTX 30xx
+ # sm_89 Ada (L4/L40/RTX 40xx) | sm_90 Hopper (H100/H200/GH200)
+ # sm_100 Blackwell DC (B100/B200/GB200) | sm_120 Blackwell (RTX 50xx, RTX PRO 6000)
+ # sm_103 (B300/GB300) and sm_121 (GB10) omitted: CUDA 12.8 nvcc can't compile
+ # them; sm_100/sm_120 SASS covers them via forward-compat. +PTX lets future
+ # revisions JIT. Same list on both arches.
+ TORCH_CUDA_ARCH_LIST="7.5;8.0;8.6;8.9;9.0;10.0;12.0+PTX" \
+ MAX_JOBS=4 \
+ CUDA_HOME=/usr/local/cuda \
+ # Build-host-independence guards: the build must NEVER introspect a GPU so all
+ # hosts yield byte-identical images.
+ # 1) no JIT-compiled sm_NNN blob into unsloth_compiled_cache/ at import.
+ UNSLOTH_COMPILE_DISABLE=1 \
+ UNSLOTH_COMPILE_OVERWRITE=0 \
+ # 2) don't probe torch.cuda.is_available() at setup (would silently skip wheels).
+ UNSLOTH_DISABLE_GPU_PROBE=1 \
+ # 3) empty CUDA_VISIBLE_DEVICES so stray torch.cuda calls see no devices
+ # (re-enabled at runtime via `docker run --gpus all`).
+ CUDA_VISIBLE_DEVICES=""
+
+RUN apt-get update && apt-get install -y --no-install-recommends \
+ software-properties-common ca-certificates curl git build-essential \
+ ninja-build cmake pkg-config \
+ && add-apt-repository -y ppa:deadsnakes/ppa \
+ && apt-get update && apt-get install -y --no-install-recommends \
+ python${PYTHON_VERSION} python${PYTHON_VERSION}-venv python${PYTHON_VERSION}-dev \
+ && ln -sf /usr/bin/python${PYTHON_VERSION} /usr/local/bin/python \
+ && ln -sf /usr/bin/python${PYTHON_VERSION} /usr/local/bin/python3 \
+ && rm -rf /var/lib/apt/lists/*
+
+# Isolated prefix; never touch the system Python (PEP 668 externally-managed).
+# The venv bootstraps pip via ensurepip and gets uv a few lines below.
+ENV VENV=/opt/unsloth-venv
+RUN python -m venv ${VENV} && ${VENV}/bin/pip install -U pip wheel setuptools
+
+# Unified install: torch + triton + bitsandbytes + unsloth + unsloth_zoo in a
+# SINGLE uv pass. Mandatory -- splitting it lets bnb's transitive `cuda-toolkit`
+# silently upgrade torch to 2.12.0+cu130, breaking the pinned cu128 xformers wheel.
+#
+# Flags:
+# --index-strategy unsafe-best-match: the PyTorch index serves an old
+# requests==2.28.1 conflicting with datasets>=2.32.2; both indexes are equally
+# trusted, so override uv's first-wins.
+# --extra-index-url .../cu128: torch +cu128 wheels + the xformers/cu128 URLs.
+#
+# Plain `huggingface` extra + explicit xformers pin (amd64): the cu128 extras on
+# main stop at torch2100, conflicting with the torch 2.11.0 held below. Pinning
+# xformers==0.0.35 (untied to torch) keeps this self-contained; arm64 stays
+# xformers-less (no cu128 aarch64 wheel).
+#
+# No flash-attn: FA3 is hard-refused on Blackwell (Dao-AILab/flash-attention#1810);
+# FA2 has no cu128+torch2.11+cp312 wheel and Unsloth falls back to xformers/SDPA.
+# Ampere/Ada/Hopper users can `pip install flash-attn` at deploy time.
+ARG UNSLOTH_REF=main
+ARG UNSLOTH_ZOO_REF=main
+RUN set -eux \
+ && case "${TARGETARCH:-amd64}" in \
+ amd64) UNSLOTH_EXTRA="huggingface"; XFORMERS_PIN="xformers==0.0.35" ;; \
+ arm64) UNSLOTH_EXTRA="huggingface"; XFORMERS_PIN="" ;; \
+ *) echo "ERROR: unsupported TARGETARCH=${TARGETARCH}" >&2; exit 1 ;; \
+ esac \
+ && echo ">> TARGETARCH=${TARGETARCH:-amd64}, unsloth extra=[${UNSLOTH_EXTRA}], xformers=[${XFORMERS_PIN}]" \
+ && ${VENV}/bin/pip install uv \
+ && ${VENV}/bin/uv pip install \
+ --python ${VENV}/bin/python \
+ --index-strategy unsafe-best-match \
+ --extra-index-url https://download.pytorch.org/whl/cu128 \
+ "torch==2.11.0" "torchvision==0.26.0" "torchaudio==2.11.0" \
+ ${XFORMERS_PIN} \
+ "triton>=3.6.0" \
+ "bitsandbytes>=0.49.2,!=0.46.0,!=0.48.0" \
+ "unsloth_zoo @ git+https://github.com/unslothai/unsloth-zoo@${UNSLOTH_ZOO_REF}" \
+ "unsloth[${UNSLOTH_EXTRA}] @ git+https://github.com/unslothai/unsloth@${UNSLOTH_REF}" \
+ `# structlog is a studio backend dep, not an unsloth[huggingface] dep,` \
+ `# but unsloth_cli's train / export / chat / list-checkpoints all import` \
+ `# studio.backend.core.*, so without it every one of them dies on` \
+ `# ModuleNotFoundError. The last builder stage imports it as a guard.` \
+ "timm>=1.0.11" "addict" "structlog"
+
+# vLLM: required by Unsloth's GRPO path (fast_inference=True). A SECOND uv pass so
+# torch 2.11.0 settles first; with torch held, uv picks the newest compatible vLLM
+# (0.20+ pins torch 2.11.0). PyPI ships x86_64 + aarch64 wheels since 0.17. amd64
+# failures abort, arm64 is fail-soft (aarch64 kernels validated on Spark, not CI).
+# https://docs.vllm.ai/en/latest/getting_started/installation/gpu/
+# https://wheels.vllm.ai/nightly
+ARG INSTALL_VLLM=auto
+RUN set -eux \
+ && WANT_VLLM=0 \
+ && case "${INSTALL_VLLM}" in \
+ auto|1|true|yes) WANT_VLLM=1 ;; \
+ 0|false|no) WANT_VLLM=0 ;; \
+ *) echo "ERROR: invalid INSTALL_VLLM=${INSTALL_VLLM}" >&2; exit 1 ;; \
+ esac \
+ && if [ "${WANT_VLLM}" = "1" ]; then \
+ echo ">> installing vLLM (TARGETARCH=${TARGETARCH:-amd64})"; \
+ # Explicit && chain, not `set -e` -- POSIX shells disable errexit inside a
+ # condition context (verified on dash), masking install failures.
+ # 1: uv resolves vLLM's deps with torch==2.11.0 held (fails loudly if none).
+ # 2: vLLM pulls numpy down to 2.2.6 with a broken numpy.testing that breaks
+ # `import unsloth`; upgrade numpy back to a self-consistent release.
+ # 3: vLLM pins numba 0.61.2 (refuses numpy>=2.3); lift numba to one
+ # supporting numpy 2.4 (0.65 imports cleanly, vllm still imports).
+ { ${VENV}/bin/uv pip install \
+ --python ${VENV}/bin/python \
+ --pre \
+ --index-strategy unsafe-best-match \
+ --extra-index-url https://wheels.vllm.ai/nightly \
+ --extra-index-url https://download.pytorch.org/whl/cu128 \
+ "torch==2.11.0" \
+ vllm \
+ && ${VENV}/bin/uv pip install \
+ --python ${VENV}/bin/python \
+ --upgrade "numpy>=2.4" \
+ && ${VENV}/bin/uv pip install \
+ --python ${VENV}/bin/python \
+ --upgrade "numba>=0.62" \
+ && ${VENV}/bin/python -c "import vllm; print('vllm', vllm.__version__)" \
+ && ${VENV}/bin/python -c "import numpy.testing, numpy; print('numpy', numpy.__version__, 'testing ok')" \
+ && ${VENV}/bin/python -c "import numba; print('numba', numba.__version__, 'imports ok')" \
+ # flashinfer-jit-cache: precompiled cubins so flashinfer ops skip the JIT
+ # path (standalone `vllm serve` dies there for fmha_gen on sm_100a). ~1.5 GB.
+ # The version MUST equal the flashinfer-python vLLM resolved: flashinfer
+ # raises at import when the two disagree, which takes the vLLM EngineCore
+ # down with it and breaks Unsloth's GRPO fast_inference path. So read the
+ # resolved version instead of pinning a literal that drifts.
+ && FI_VER="$(${VENV}/bin/python -c 'from importlib.metadata import version; print(version("flashinfer-python"))')" \
+ && echo ">> flashinfer-python ${FI_VER}, matching flashinfer-jit-cache" \
+ && { ${VENV}/bin/uv pip install \
+ --python ${VENV}/bin/python \
+ --index-url https://flashinfer.ai/whl/cu128 \
+ "flashinfer-jit-cache==${FI_VER}" \
+ || echo ">> flashinfer-jit-cache ${FI_VER} unavailable for ${TARGETARCH:-amd64}; vllm serve may require nvcc for uncached ops"; } \
+ # Whatever happened above, flashinfer has to import: a version mismatch
+ # here is silent until the first vLLM engine start.
+ && ${VENV}/bin/python -c \
+ "import flashinfer; print('OK: flashinfer', flashinfer.__version__, 'imports')" \
+ && echo ">> vLLM installed (numpy + numba re-upgraded post-vllm)"; \
+ } || { \
+ if [ "${TARGETARCH:-amd64}" != "amd64" ]; then \
+ echo ">> vLLM skipped on ${TARGETARCH}: install or import check failed (fail-soft on non-amd64)"; \
+ # A partial install must not poison the base stack: drop vllm and
+ # restore the numpy/numba floor it may have moved. arm64 staging CI
+ # re-verifies `import unsloth` after this.
+ ${VENV}/bin/uv pip uninstall --python ${VENV}/bin/python vllm || true; \
+ ${VENV}/bin/uv pip install --python ${VENV}/bin/python \
+ --upgrade "numpy>=2.4" "numba>=0.62"; \
+ ${VENV}/bin/python -c "import numpy.testing, numba; print('numpy/numba restored')"; \
+ else \
+ echo "ERROR: vLLM install failed on amd64" >&2; exit 1; \
+ fi; \
+ }; \
+ else \
+ echo ">> vLLM skipped (INSTALL_VLLM=${INSTALL_VLLM}, TARGETARCH=${TARGETARCH:-amd64})"; \
+ fi
+
+# JupyterLab so the image runs unslothai/notebooks out of the box:
+# docker run --gpus all -p 8888:8888 unsloth/unsloth \
+# jupyter lab --ip 0.0.0.0 --port 8888 --allow-root --no-browser
+# Separate pass AFTER the torch pin: pure-Python, never names torch, so uv can't
+# disturb the cu128 pin set. Declared by notebook install cells, so bake them:
+# matplotlib plotting; some trust_remote_code files import it (DeepSeek-OCR)
+# soundfile TTS audio read/write (bundles libsndfile)
+# evaluate+jiwer Whisper WER metric
+# tensorboard default TrainingArguments report_to backend
+# langid DeepSeek-R1 GRPO reward language-id check
+# easydict some vision trust_remote_code modeling files
+# protobuf slow->fast tokenizer conversion for sentencepiece
+# omegaconf TTS + NeMo-Gym RL notebook configs
+# einx TTS codec tensor-rearrange (Llasa/Oute/Spark)
+# librosa Whisper audio features (pulls numba, already pinned >=0.65)
+# ftfy Oute TTS text normalisation
+# decord is separate below (no aarch64 wheel). Pinned (==) for reproducible
+# rebuilds. The resolve must NOT move torch/numpy/numba (asserted below).
+RUN ${VENV}/bin/uv pip install \
+ --python ${VENV}/bin/python \
+ "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.11.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) has wheels only for x86_64. Installed alone:
+# HARD on amd64 (a missing wheel is a real regression), fail-soft elsewhere.
+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 (torchcodec). Three traps: (1) torchcodec 0.11 must
+# pair with torch 2.11; (2) the wheel must come from cu128, not the PyPI cu13
+# default; (3) its libs dlopen venv torch/NVIDIA libs registered via ld.so.conf.d
+# in the runtime stage. Fail-soft on arches without a matching wheel.
+RUN set -eux \
+ && { ${VENV}/bin/uv pip install \
+ --python ${VENV}/bin/python \
+ --index-url https://download.pytorch.org/whl/cu128 \
+ "torchcodec==0.11.0" \
+ && ${VENV}/bin/uv pip install --python ${VENV}/bin/python nvidia-npp-cu12; } \
+ || echo ">> torchcodec bake skipped (no matching wheel for ${TARGETARCH:-amd64})"
+
+# transformers SIDECARS for per-notebook version activation (see
+# unsloth_nb_compat.py). Each sidecar is transformers==X + matched
+# huggingface_hub/tokenizers/safetensors, --no-deps into its own --target under
+# ${VENV}/tf-sidecars. Prepending one to sys.path swaps transformers without
+# touching the cu128 base. Candidate versions mirror Studio's tiers (4.57.6 +
+# 5.3.0/5.5.0/5.10.2). Fail-soft per arch/wheel.
+#
+# Every candidate is then VERIFIED against the baked vLLM and dropped if it does
+# not survive, because vLLM is version-locked to transformers and a sidecar it
+# cannot import does not give the notebook an older transformers -- it gives it
+# an ImportError at `import unsloth`, before the first model cell. Measured on
+# this image (vLLM 0.26.0): 4.57.6 raises "Support for Transformers v4 ... was
+# removed in vLLM v0.24.0" and 5.3.0 raises "cannot import name
+# 'ALLOWED_LAYER_TYPES'", between them breaking 254 of the 433 shipped notebooks,
+# whose transformers pins select exactly those two. 5.5.0 and 5.10.2 pass.
+#
+# vllm.transformers_utils.config is the gate because it is the vLLM module that
+# reads the transformers API, it reproduces BOTH failures, and it imports without
+# a GPU (the build host has none, so `import unsloth` cannot be used here).
+# Deriving the kept set instead of hardcoding it means a later vLLM bump that
+# widens or narrows the supported range re-tunes the image by itself. The lowest
+# survivor is recorded as the selection FLOOR read by unsloth_nb_compat.
+RUN set -eux \
+ && if ${VENV}/bin/python -c "import vllm" >/dev/null 2>&1; then HAVE_VLLM=1; else HAVE_VLLM=0; fi \
+ && echo ">> sidecar verification: baked vLLM importable=${HAVE_VLLM}" \
+ && KEPT="" \
+ && for TFV in 4.57.6 5.3.0 5.5.0 5.10.2; do \
+ SCRATCH="$(mktemp -d)"; \
+ if ! ${VENV}/bin/uv pip install --python ${VENV}/bin/python \
+ --target "$SCRATCH" "transformers==${TFV}" >/dev/null 2>&1; then \
+ echo ">> sidecar resolve failed for ${TFV}; skipping"; rm -rf "$SCRATCH"; continue; \
+ fi; \
+ pin() { ls -d "$SCRATCH/$1"-*.dist-info 2>/dev/null \
+ | sed -E "s@.*/$1-([0-9][0-9A-Za-z.]*)\.dist-info@\1@" | head -1; }; \
+ HFV="$(pin huggingface_hub)"; TKV="$(pin tokenizers)"; SFV="$(pin safetensors)"; \
+ rm -rf "$SCRATCH"; \
+ DEST="${VENV}/tf-sidecars/t_$(echo "${TFV}" | tr . _)"; \
+ ${VENV}/bin/uv pip install --python ${VENV}/bin/python --target "$DEST" --no-deps \
+ "transformers==${TFV}" \
+ ${HFV:+"huggingface_hub==${HFV}"} \
+ ${TKV:+"tokenizers==${TKV}"} \
+ ${SFV:+"safetensors==${SFV}"}; \
+ if [ "$HAVE_VLLM" = "1" ] && ! PYTHONPATH="$DEST" ${VENV}/bin/python \
+ -c "import vllm.transformers_utils.config" >/dev/null 2>&1; then \
+ echo ">> sidecar transformers==${TFV} DROPPED -- the baked vLLM cannot import under it:"; \
+ PYTHONPATH="$DEST" ${VENV}/bin/python \
+ -c "import vllm.transformers_utils.config" 2>&1 | tail -2 || true; \
+ rm -rf "$DEST"; \
+ continue; \
+ fi; \
+ KEPT="${KEPT} ${TFV}"; \
+ echo ">> sidecar transformers==${TFV} kept (hf_hub=${HFV} tokenizers=${TKV} safetensors=${SFV})"; \
+ done \
+ && if [ -z "$KEPT" ]; then \
+ echo ">> FATAL: no transformers sidecar survived vLLM verification"; exit 1; \
+ fi \
+ && if [ "$HAVE_VLLM" = "1" ]; then \
+ printf '%s\n' $KEPT | sort -V | head -1 > ${VENV}/tf-sidecars/.vllm_min_transformers; \
+ fi \
+ && echo ">> sidecars kept:${KEPT} floor=$(cat ${VENV}/tf-sidecars/.vllm_min_transformers 2>/dev/null || echo '(none)')" \
+ && { du -sh ${VENV}/tf-sidecars || true; }
+
+# Informational pin record (NOT byte-reproducible: pip freeze omits wheel hashes
+# and unsloth/vllm --pre float from VCS/nightly).
+RUN ${VENV}/bin/pip freeze --exclude-editable > ${VENV}/requirements.lock.txt \
+ && head -50 ${VENV}/requirements.lock.txt
+
+# Strip pip cache & __pycache__ to shrink the runtime layer. The `-name tests`
+# strip excludes numpy's tests dirs (numpy 2.4 needs numpy/_core/tests/ or
+# `import numpy` breaks). Other verified-safe cuts:
+# * npp: torchcodec dlopens only libnppicc + libnppc; drop the rest (~388MB).
+# * static .a archives (~143MB): link-time only.
+# * nvshmem device .bc (~30MB): device-relink only; host .so kept.
+# Do NOT strip headers (torch/include): causal-conv1d / mamba-ssm build against
+# them at notebook time with --no-build-isolation.
+RUN set -eux \
+ && find ${VENV} -depth -type d -name __pycache__ -exec rm -rf {} + \
+ && find ${VENV} -depth -type d -name tests \
+ ! -path "*numpy/_core/tests*" \
+ ! -path "*numpy/tests*" \
+ ! -path "*numpy/ma/tests*" \
+ -exec rm -rf {} + \
+ && rm -rf /root/.cache/pip /root/.cache/uv \
+ && SP=${VENV}/lib/python${PYTHON_VERSION}/site-packages \
+ && if [ -d "$SP/nvidia/npp/lib" ]; then \
+ find "$SP/nvidia/npp/lib" -maxdepth 1 -name 'libnpp*.so.*' \
+ ! -name 'libnppicc.so.*' ! -name 'libnppc.so.*' -delete; \
+ fi \
+ && find ${VENV} -name '*.a' -delete \
+ && rm -f "$SP"/nvidia/nvshmem/lib/libnvshmem_device.bc \
+ && echo "venv size after prune:" && du -sh ${VENV}
+
+# Build-time verification.
+# (1) arch-list check uses the RAW C++ accessor: torch.cuda.get_arch_list()
+# returns [] with no GPU visible (CUDA_VISIBLE_DEVICES is empty here).
+# (2) required packages verified via metadata only -- we do NOT import unsloth/
+# unsloth_zoo (their __init__ needs a real CUDA device). Import correctness is
+# exercised at deploy time by smoke_test.py with --gpus all.
+RUN TARGETARCH="${TARGETARCH:-amd64}" ${VENV}/bin/python - <<'PY'
+import os, platform
+target = os.environ.get("TARGETARCH", "amd64")
+mach = platform.machine()
+print(f"build target: TARGETARCH={target} platform.machine()={mach}")
+
+import torch
+arches = torch._C._cuda_getArchFlags().split()
+print("torch", torch.__version__, "cuda", torch.version.cuda)
+print("arches:", arches)
+assert torch.__version__.startswith("2.11.0"), f"torch silently moved: {torch.__version__}"
+assert "+cu128" in torch.__version__, f"cu build silently changed: {torch.__version__}"
+assert "sm_100" in arches, f"sm_100 (B200/GB200) missing: {arches}"
+# cu128 wheels ship sm_120 native SASS on both amd64 and aarch64. On arm64 DGX
+# Spark (sm_121) runs it via forward-compat; sm_121 is never in a cu128 wheel.
+assert "sm_120" in arches, f"sm_120 missing: {arches}"
+print(f"OK: torch 2.11.0+cu128 with sm_100 + sm_120 native SASS intact ({target})")
+
+from importlib.metadata import version, PackageNotFoundError
+# xformers is amd64-only (aarch64 wheel gap -- see header).
+REQUIRED = ["torch", "triton", "bitsandbytes", "unsloth",
+ "unsloth_zoo", "transformers", "trl", "peft", "accelerate"]
+if target == "amd64":
+ REQUIRED.insert(2, "xformers")
+missing = []
+for pkg in REQUIRED:
+ try:
+ v = version(pkg.replace("_", "-"))
+ print(f" {pkg:14s} {v}")
+ except PackageNotFoundError:
+ missing.append(pkg)
+if missing:
+ raise SystemExit(f"FAIL: missing wheels: {missing}")
+print("OK: all required wheels present")
+
+# Lightweight imports: these init without touching CUDA, unlike unsloth.
+import importlib
+LIGHT_IMPORTS = ["bitsandbytes", "triton"]
+if target == "amd64":
+ LIGHT_IMPORTS.insert(0, "xformers")
+for pkg in LIGHT_IMPORTS:
+ importlib.import_module(pkg)
+print(f"OK: {' + '.join(LIGHT_IMPORTS)} import cleanly on no-GPU host")
+
+# Guard for the studio.backend.core.* closure the unsloth CLI needs (structlog,
+# plus starlette via the logging handlers). Runs last in the builder, after vLLM,
+# because that is what pulls starlette in.
+from studio.backend.core.export import ExportBackend # noqa: F401
+print("OK: the unsloth CLI can reach the studio export backend")
+PY
+
+# Stage 2: runtime -- slim, no nvcc, no cuDNN/cuBLAS layers.
+# The "-base-" variant drops ~2.7 GB of system CUDA libs we never load: torch
+# wheels bake their own cuDNN/cuBLAS into torch/lib/ and resolve via RPATH. The
+# base still provides nvidia-smi + libcuda stubs + libnvidia-ml.
+FROM nvidia/cuda:${CUDA_VERSION}-base-ubuntu${UBUNTU_VERSION} AS runtime
+
+# The base manifest is multi-arch; buildx picks the right one for
+# TARGETPLATFORM at this FROM line, no conditional needed.
+ARG TARGETARCH
+ARG PYTHON_VERSION
+ARG CUDA_VERSION
+ENV DEBIAN_FRONTEND=noninteractive \
+ PIP_NO_CACHE_DIR=1 \
+ PYTHONDONTWRITEBYTECODE=1 \
+ PYTHONUNBUFFERED=1 \
+ PATH=/opt/unsloth-venv/bin:${PATH} \
+ HF_HOME=/workspace/.cache/huggingface \
+ TRITON_CACHE_DIR=/workspace/.cache/triton \
+ # Keep the arch list at runtime so an in-container source build gets the same
+ # SASS coverage as the builder (10.3 omitted; cu12.8 can't emit it).
+ TORCH_CUDA_ARCH_LIST="7.5;8.0;8.6;8.9;9.0;10.0;12.0+PTX"
+
+# System packages needed by the notebooks:
+# zstd Ollama installer (`curl ollama.com/install.sh | sh`) extracts a zstd tarball
+# ffmpeg torchcodec dlopens system FFmpeg libs (not bundled in the wheel)
+# wget notebooks fetch assets with `!wget URL`
+# ninja-build flashinfer cpp_ext JIT shells out to ninja
+# cuda-nvcc + cudart-dev flash-linear-attention TileLang JIT-compiles CUDA
+# kernels via nvcc, absent from the -base image
+RUN CUDA_PKG="$(echo "${CUDA_VERSION}" | awk -F. '{print $1"-"$2}')" \
+ && apt-get update && apt-get install -y --no-install-recommends \
+ software-properties-common ca-certificates curl wget git libgomp1 \
+ gcc g++ zstd ffmpeg ninja-build \
+ "cuda-nvcc-${CUDA_PKG}" "cuda-cudart-dev-${CUDA_PKG}" \
+ && add-apt-repository -y ppa:deadsnakes/ppa \
+ && apt-get update && apt-get install -y --no-install-recommends \
+ python${PYTHON_VERSION} python${PYTHON_VERSION}-venv python${PYTHON_VERSION}-dev \
+ && ln -sf /usr/bin/python${PYTHON_VERSION} /usr/local/bin/python \
+ && ln -sf /usr/bin/python${PYTHON_VERSION} /usr/local/bin/python3 \
+ && test -x /usr/local/cuda/bin/nvcc \
+ && rm -rf /var/lib/apt/lists/*
+# gcc + g++ + python3.12-dev in runtime: Triton's nvidia backend compiles a C
+# extension (CudaUtils) on first GPU access; without a compiler + headers the
+# first forward pass dies with "Failed to find C compiler". ~250MB.
+
+COPY --from=builder /opt/unsloth-venv /opt/unsloth-venv
+
+# Blackwell JIT fix for sm_103 (amd64) and sm_121 (arm64) -- the cu12.8 JIT gap.
+# Two JIT paths need the cu13 override:
+# (1) torch's bundled libnvrtc.so.12 errors on sm_103/sm_121. Fix: stage a cu13
+# NVRTC alias beside the cu12.8 default.
+# (2) Triton's bundled ptxas (12.8) rejects sm_103, downgrades sm_121 to sm_80
+# (triton-lang/triton#8335). Fix: cu13 ptxas via TRITON_PTXAS_PATH.
+# Both cu13 tools are CPU-side compilers, but their cubin needs a >=580 driver to
+# LOAD, so neither is a global default (would break 570-579 drivers).
+# select_cuda_jit_tools in entrypoint.sh activates them per device, only for
+# sm_103/sm_121 (>=580 drivers). Both arches carry the ~400 MB.
+RUN set -eux; \
+ # The base already configures the CUDA apt repo with its own Signed-By
+ # keyring; a second cuda-keyring would make apt-get update refuse the repo.
+ # The base repo serves 13.x too, so install cu13 packages directly.
+ apt-get update; \
+ apt-get install -y --no-install-recommends \
+ cuda-nvrtc-13-0 \
+ cuda-nvcc-13-0; \
+ # cu13's postinst flips /usr/local/cuda to cuda-13.0; pin it back (cpp
+ # builds resolve /usr/local/cuda/bin/nvcc, and cu13 cubins need driver
+ # >= 580 while this image supports 570+). The cu13 tools stay reachable by
+ # absolute path; --set also stops later apt ops flipping it again.
+ update-alternatives --set cuda /usr/local/cuda-12.8; \
+ rm -rf /var/lib/apt/lists/*; \
+ # (1) NVRTC staging: keep the wheel's cu12.8 lib as .cu128.orig, point
+ # libnvrtc.so.12 at it, stage .cu13 -> the cu13 lib;
+ # select_cuda_jit_tools retargets the symlink only on sm_103/sm_121.
+ NVRTC_DIR=/opt/unsloth-venv/lib/python${PYTHON_VERSION}/site-packages/nvidia/cuda_nvrtc/lib; \
+ if [ -f "${NVRTC_DIR}/libnvrtc.so.12" ] && [ ! -L "${NVRTC_DIR}/libnvrtc.so.12" ]; then \
+ mv "${NVRTC_DIR}/libnvrtc.so.12" "${NVRTC_DIR}/libnvrtc.so.12.cu128.orig"; \
+ ln -s libnvrtc.so.12.cu128.orig "${NVRTC_DIR}/libnvrtc.so.12"; \
+ ln -s /usr/local/cuda-13.0/lib64/libnvrtc.so.13 "${NVRTC_DIR}/libnvrtc.so.12.cu13"; \
+ fi
+# (2) ptxas: the cu13 nvcc package above provides it; TRITON_PTXAS_PATH is set
+# per device at boot (select_cuda_jit_tools) for the same driver-floor reason.
+
+# Register the venv's torch + NVIDIA lib dirs with the loader so torchcodec can
+# dlopen them. ld.so.conf.d, NOT LD_LIBRARY_PATH: the cache is consulted after
+# DT_RUNPATH, so llama.cpp keeps resolving its own $ORIGIN libs first.
+# cublas/lib and cu13/lib are here for llama.cpp's libggml-cuda.so, which links
+# against libcublas but does not ship it (see the guard after the fetch below).
+RUN set -eux \
+ && SP=/opt/unsloth-venv/lib/python${PYTHON_VERSION}/site-packages \
+ && printf "%s\n" "$SP/torch/lib" "$SP/nvidia/cuda_nvrtc/lib" \
+ "$SP/nvidia/cuda_runtime/lib" "$SP/nvidia/npp/lib" \
+ "$SP/nvidia/cublas/lib" "$SP/nvidia/cu13/lib" \
+ > /etc/ld.so.conf.d/zz-unsloth-venv.conf \
+ && ldconfig \
+ && { /opt/unsloth-venv/bin/python -c \
+ "import torchcodec; print('torchcodec', torchcodec.__version__)" \
+ || echo ">> torchcodec unavailable on this arch (audio decode falls back)"; }
+
+# Prebuilt llama.cpp so GGUF export works out of the box; without it the first
+# export hits install_llama_cpp()'s prompt + slow source build.
+#
+# NOT studio/install_llama_prebuilt.py: it selects a bundle for the CURRENT host,
+# but the build must never introspect the host, so release + asset are pinned by
+# build target instead (see fetch_llama_prebuilt.py).
+#
+# /opt (not /root) so it survives `docker run --user`. Default "latest" resolves
+# the newest release; build.sh pins a concrete tag so the cache busts only on new
+# releases. --build-arg LLAMA_PREBUILT_TAG=<tag> for a frozen build.
+ARG LLAMA_PREBUILT_TAG=latest
+COPY fetch_llama_prebuilt.py /tmp/fetch_llama_prebuilt.py
+RUN /opt/unsloth-venv/bin/python /tmp/fetch_llama_prebuilt.py \
+ "${LLAMA_PREBUILT_TAG}" "${TARGETARCH:-amd64}" /opt/unsloth/llama.cpp \
+ && rm -f /tmp/fetch_llama_prebuilt.py \
+ && cat /opt/unsloth/llama.cpp/UNSLOTH_PREBUILT_INFO.json
+
+# libggml-cuda.so is loaded with dlopen (ggml_backend_dl), links against
+# libcublas, and does not ship it; the CUDA runtime base only carries libcudart.
+# A missing libcublas therefore makes the backend fail to load SILENTLY and
+# llama.cpp runs on the CPU: measured 1.6 tok/s instead of 222 tok/s for
+# gemma-4-E2B UD-Q4_K_XL on a B200, with `--list-devices` printing nothing.
+# torch's wheels already ship libcublas for their own CUDA major (registered
+# with the loader above); install the bundle's major when it differs. Then fail
+# the build on any dependency that is still unresolved, so a silent CPU fallback
+# can never ship again. libcuda.so.1 is exempt: that is the driver stub, injected
+# by nvidia-container-toolkit at `docker run --gpus`, never present in the image.
+# ldd needs no GPU, so this keeps the build host-independent.
+RUN set -eux \
+ && CUDA_SO=/opt/unsloth/llama.cpp/libggml-cuda.so \
+ && if [ -f "$CUDA_SO" ]; then \
+ want="$(ldd "$CUDA_SO" | sed -n 's/^[[:space:]]*\(libcublas\.so\.[0-9]*\)[[:space:]]*=> not found$/\1/p' | head -n1)"; \
+ if [ -n "$want" ]; then \
+ major="${want##*.}"; \
+ echo ">> $want missing, installing nvidia-cublas-cu${major}"; \
+ /opt/unsloth-venv/bin/uv pip install --python /opt/unsloth-venv/bin/python \
+ "nvidia-cublas-cu${major}"; \
+ ldconfig; \
+ fi; \
+ missing="$(ldd "$CUDA_SO" | grep 'not found' | grep -v 'libcuda\.so\.1 ' || true)"; \
+ if [ -n "$missing" ]; then \
+ echo "ERROR: llama.cpp CUDA backend has unresolved libraries:"; \
+ echo "$missing"; \
+ echo "GGUF inference would silently fall back to the CPU."; \
+ exit 1; \
+ fi; \
+ echo "OK: llama.cpp CUDA backend dependencies all resolve"; \
+ else \
+ echo ">> no libggml-cuda.so in this bundle (CPU-only build)"; \
+ fi
+ENV UNSLOTH_LLAMA_CPP_PATH=/opt/unsloth/llama.cpp
+
+WORKDIR /workspace
+# World-writable so `docker run --user <uid>` (documented non-root use) can
+# create notebooks and populate the default caches without a bind mount.
+RUN mkdir -p ${HF_HOME} ${TRITON_CACHE_DIR} \
+ && chmod -R a+rwX /workspace
+
+# Per-notebook transformers version activation -- run unslothai/notebooks
+# UNCHANGED (see unsloth_nb_compat.py). Pieces:
+# * unsloth_nb_compat.py: tier detection + sidecar resolution + IPython hook.
+# * pip/uv shim on a PATH dir AHEAD of the venv bin: makes `!pip install` cells
+# safe + idempotent (keeps the baked stack, records requested transformers).
+# * unsloth_nb_pip_magic.py: re-points `%pip`/`%uv` and `!python -m pip` at the
+# same shim so in-process installs can't bypass PATH.
+# * IPython startup hook: activates the right sidecar before the first model cell.
+# * unsloth-run: headless `unsloth-run <notebook|url>`, the robust driven path.
+COPY unsloth_nb_compat.py unsloth_pip_shim.py unsloth_nb_pip_magic.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" \
+ && cp /opt/unsloth-nb/unsloth_nb_pip_magic.py "$SP/unsloth_nb_pip_magic.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 /opt/unsloth-nb/ipython/profile_default/startup \
+ && cp /opt/unsloth-nb/unsloth_ipython_startup.py /opt/unsloth-nb/ipython/profile_default/startup/00-unsloth-nb.py \
+ && chmod -R a+rX /opt/unsloth-nb/ipython \
+ && chmod 1777 /opt/unsloth-nb/ipython /opt/unsloth-nb/ipython/profile_default \
+ && /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_*')))" \
+ && /opt/unsloth-venv/bin/python /opt/unsloth-nb/unsloth_pip_shim.py --unsloth-selfcheck-value-flags
+# 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}
+# Load the notebook startup hook for EVERY kernel, any uid: IPYTHONDIR points
+# IPython at this shared profile, so it loads under `--user <uid>` too (unlike
+# /root/.ipython).
+#
+# The profile has to be WRITABLE by that uid, which is what the 1777 above is for.
+# IPython.paths.get_ipython_dir() discards an IPYTHONDIR it cannot write to and
+# silently substitutes tempfile.mkdtemp(), and an empty temp profile has no
+# startup/ -- so a root-owned 0755 profile did not merely lose history.sqlite, it
+# dropped the hook entirely and every kernel under `--user <uid>` ran with no
+# sidecar activation, no %pip/%uv magic and no colab-compat. ProfileDir then also
+# creates security/, log/, pid/ and db/ INSIDE profile_default, so making only the
+# top dir writable is worse still: the kernel dies on PermissionError. The sticky
+# bit keeps the shared hook read-only -- 00-unsloth-nb.py and its startup/ dir stay
+# a+rX and no other uid can unlink or rename them.
+ENV IPYTHONDIR=/opt/unsloth-nb/ipython
+
+# Pre-clone unslothai/notebooks so JupyterLab opens with them present. Baked as a
+# READ-ONLY template (~206MB, .git stripped); on boot the entrypoint copies it to
+# /workspace/unsloth-notebooks and best-effort refreshes from GitHub, never
+# overwriting a user-touched notebook (see unsloth_sync_notebooks.sh).
+#
+# UNSLOTH_NOTEBOOKS_REF pins ONE commit/branch/tag so a multi-arch publish bakes
+# identical templates into both legs; default "main" tracks the tip.
+ARG UNSLOTH_NOTEBOOKS_REF=main
+RUN set -eux \
+ && git init -q /opt/unsloth-notebooks \
+ && git -C /opt/unsloth-notebooks remote add origin https://github.com/unslothai/notebooks \
+ && git -C /opt/unsloth-notebooks fetch -q --depth 1 origin "${UNSLOTH_NOTEBOOKS_REF}" \
+ && git -C /opt/unsloth-notebooks checkout -q FETCH_HEAD \
+ && git -C /opt/unsloth-notebooks rev-parse HEAD > /opt/unsloth-notebooks/.unsloth_template_commit \
+ && rm -rf /opt/unsloth-notebooks/.git \
+ && du -sh /opt/unsloth-notebooks
+
+# Mount a volume on /workspace to persist the notebooks and caches.
+EXPOSE 8888
+
+COPY smoke_test.py /workspace/smoke_test.py
+COPY entrypoint.sh /usr/local/bin/unsloth-entrypoint
+RUN chmod +x /usr/local/bin/unsloth-entrypoint
+
+# Fast GPU pre-flight checks before user code, each with an actionable error (see
+# entrypoint.sh). Bypass for offline tooling: docker run -e UNSLOTH_SKIP_GPU_CHECK=1
+ENTRYPOINT ["/usr/local/bin/unsloth-entrypoint"]
+
+# Override examples:
+# docker run --gpus all unsloth/unsloth:latest python /workspace/smoke_test.py
+# docker run --gpus all -it unsloth/unsloth:latest bash
+CMD ["python"]
diff --git a/docker/Dockerfile.studio b/docker/Dockerfile.studio
new file mode 100644
index 00000000000..8c47ffeedae
--- /dev/null
+++ b/docker/Dockerfile.studio
@@ -0,0 +1,219 @@
+# Full Unsloth image: base training stack + Studio + JupyterLab + sshd.
+# 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/
+# Run:
+# docker run --rm --gpus all -p 8000:8000 -p 8888:8888 \
+# -v $HOME/.cache/huggingface:/workspace/.cache/huggingface unsloth-blackwell: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
+# random one is printed). Without GPU passthrough add -e UNSLOTH_ALLOW_CPU=1:
+# 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
+
+# Builds the "Unsloth Dark" (Monokai) theme + Colab-style cell-nav keymap. Node
+# lives only in this throwaway stage; the final image copies just the prebuilt
+# labextension (runtime stays Node-free). Uses the base's bundled jlpm+jupyterlab.
+FROM ${BASE_IMAGE} AS labext-builder
+ENV DEBIAN_FRONTEND=noninteractive
+# JupyterLab 4.6 needs Node >=20; Ubuntu 24.04 ships 18, so pull Node 20 LTS from
+# NodeSource. This stage is thrown away, so the apt sources never reach 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; CI pins it (same UNSLOTH_REF as
+# the base) so the published image is reproducible.
+ARG UNSLOTH_STUDIO_REF=main
+# unsloth-zoo ref overlaid into the Studio venv by install.sh --local. The publish
+# workflow passes ONE zoo ref to both builds, so Studio runs the same zoo as base.
+ARG UNSLOTH_STUDIO_ZOO_REF=main
+# The SAME llama.cpp tag the base baked. setup.sh honours UNSLOTH_LLAMA_TAG;
+# without the pin the Studio build could re-resolve "latest" and diverge.
+ARG LLAMA_PREBUILT_TAG=latest
+ARG TARGETARCH
+
+# Services run as root here (non-root parity is a follow-up). sshd is key-only,
+# disabled unless PUBLIC_KEY/SSH_KEY is set (see studio_launch.sh). The
+# JUPYTER_PORT / UNSLOTH_ENABLE_SSHD defaults let supervisord's %(ENV_*)s resolve.
+USER root
+# UNSLOTH_ALLOW_CPU defaults to 1 on THIS image only. It publishes as :latest, so a
+# plain `docker run unsloth/unsloth` on a CPU-only, AMD or Docker-Desktop host would
+# otherwise exit 1 from entrypoint.sh before Studio ever starts. Most of what this
+# image offers (Studio chat over llama.cpp/GGUF, Data Recipes, JupyterLab, GGUF
+# tooling) needs no GPU. The entrypoint only takes the CPU path when no GPU is
+# visible, so this does not weaken the checks on a GPU host, and `-e
+# UNSLOTH_ALLOW_CPU=0` restores the strict behaviour. The base/training image keeps
+# the strict check: FastLanguageModel genuinely requires a GPU there.
+ENV UNSLOTH_STUDIO_HOME=/opt/unsloth-studio \
+ UNSLOTH_ALLOW_CPU=1 \
+ JUPYTER_PORT=8888 \
+ UNSLOTH_ENABLE_SSHD=false \
+ DEBIAN_FRONTEND=noninteractive
+
+# install.sh needs curl + git; supervisor + openssh-server run the service
+# trio. The base image already has python + uv + pip.
+RUN apt-get update \
+ && apt-get install -y --no-install-recommends \
+ curl git ca-certificates supervisor openssh-server \
+ && rm -rf /var/lib/apt/lists/*
+
+# Clone + install Studio into a dedicated venv under $UNSLOTH_STUDIO_HOME.
+# --local is editable, so the source MUST persist -- keep it at $STUDIO_HOME/src,
+# strip .git (~120MB).
+#
+# The llama.cpp symlink BEFORE install.sh points Studio's prebuilt dir at the
+# base's baked bundle so the installer skips a second ~400MB download; the
+# .unsloth-studio-owned marker satisfies setup.sh's ownership assertion.
+#
+# UNSLOTH_TORCH_INDEX_FAMILY pins the Studio venv's torch index (no nvidia-smi at
+# build time would land on cpu/cu126). cu128 on both arches, mirroring the base.
+# Blackwell JIT (sm_103/sm_121) comes from the same cu13 NVRTC swap, repeated below.
+#
+# UNSLOTH_PYTHON=3.12 pins the Studio venv to the base's Python minor so the
+# nvidia-*-cu12 wheels are byte-identical and the dedup below can symlink them.
+#
+# fetch+checkout FETCH_HEAD, not `clone --branch`: CI passes a commit SHA.
+RUN set -eux \
+ && case "${TARGETARCH:-amd64}" in \
+ amd64|arm64) TORCH_FAMILY="cu128" ;; \
+ *) echo "ERROR: unsupported TARGETARCH=${TARGETARCH}" >&2; exit 1 ;; \
+ esac \
+ && mkdir -p "${UNSLOTH_STUDIO_HOME}" \
+ && ln -s /opt/unsloth/llama.cpp "${UNSLOTH_STUDIO_HOME}/llama.cpp" \
+ && touch /opt/unsloth/llama.cpp/.unsloth-studio-owned \
+ && git init -q "${UNSLOTH_STUDIO_HOME}/src" \
+ && cd "${UNSLOTH_STUDIO_HOME}/src" \
+ && git remote add origin https://github.com/unslothai/unsloth \
+ && git fetch -q --depth 1 origin "${UNSLOTH_STUDIO_REF}" \
+ && git checkout -q FETCH_HEAD \
+ && UNSLOTH_STUDIO_HOME="${UNSLOTH_STUDIO_HOME}" \
+ UNSLOTH_TORCH_INDEX_FAMILY="${TORCH_FAMILY}" \
+ UNSLOTH_ZOO_REF="${UNSLOTH_STUDIO_ZOO_REF}" \
+ UNSLOTH_LLAMA_TAG="${LLAMA_PREBUILT_TAG}" \
+ UNSLOTH_PYTHON=3.12 \
+ bash install.sh --local \
+ # Fail loud unless the Studio venv torch EXACTLY matches the base (version AND
+ # CUDA family) before the dedup symlinks their CUDA libs. Compare to the base's
+ # own torch (no hardcoded version); metadata only (QEMU arm64 can't import torch).
+ && BASE_TORCH="$(/opt/unsloth-venv/bin/python -c "from importlib.metadata import version; print(version('torch'))")" \
+ && "${UNSLOTH_STUDIO_HOME}/unsloth_studio/bin/python" -c "import sys; from importlib.metadata import version; assert sys.version_info[:2] == (3, 12), 'Studio venv python %d.%d is not 3.12 (UNSLOTH_PYTHON pin ignored) -- CUDA dedup below depends on it' % sys.version_info[:2]; v = version('torch'); assert v == '${BASE_TORCH}', 'Studio venv torch ' + v + ' does not match base venv torch ${BASE_TORCH} (CUDA dedup would link mismatched libs)'; print('Studio venv python %d.%d torch' % sys.version_info[:2], v, '== base', '${BASE_TORCH}')" \
+ # setup.sh may relink llama-quantize into build/bin; prove it still resolves its
+ # libraries. Content check, not rc: --help exits nonzero but prints usage.
+ && { "${UNSLOTH_STUDIO_HOME}/llama.cpp/llama-quantize" --help 2>&1 || true; } | grep -q "usage" \
+ && rm -rf "${UNSLOTH_STUDIO_HOME}/src/.git" \
+ "${UNSLOTH_STUDIO_HOME}/src/studio/frontend/node_modules" \
+ /root/.cache \
+ # Stage the Studio venv's NVRTC like the base (.cu128.orig default + .cu13
+ # alias, retargeted per device by select_cuda_jit_tools). Both arches.
+ && for NVRTC_DIR in "${UNSLOTH_STUDIO_HOME}"/unsloth_studio/lib/python*/site-packages/nvidia/cuda_nvrtc/lib; do \
+ if [ -f "${NVRTC_DIR}/libnvrtc.so.12" ] && [ ! -L "${NVRTC_DIR}/libnvrtc.so.12" ]; then \
+ mv "${NVRTC_DIR}/libnvrtc.so.12" "${NVRTC_DIR}/libnvrtc.so.12.cu128.orig"; \
+ ln -s libnvrtc.so.12.cu128.orig "${NVRTC_DIR}/libnvrtc.so.12"; \
+ ln -s /usr/local/cuda-13.0/lib64/libnvrtc.so.13 "${NVRTC_DIR}/libnvrtc.so.12.cu13"; \
+ fi; \
+ done \
+ && BASE_NV=/opt/unsloth-venv/lib/python3.12/site-packages/nvidia \
+ && STU_NV="${UNSLOTH_STUDIO_HOME}/unsloth_studio/lib/python3.12/site-packages/nvidia" \
+ && if [ ! -d "${STU_NV}" ] || [ ! -d "${BASE_NV}" ]; then \
+ echo ">> nvidia dir missing (STU=${STU_NV} BASE=${BASE_NV}); skipping CUDA dedup"; \
+ else \
+ find "${UNSLOTH_STUDIO_HOME}/unsloth_studio" -name '*.a' -delete; \
+ rm -f "${STU_NV}/nvshmem/lib/libnvshmem_device.bc"; \
+ for c in cudnn cublas cusparselt nccl cusolver cusparse cufft curand nvjitlink cuda_cupti nvshmem npp; do \
+ b="${BASE_NV}/${c}/lib"; s="${STU_NV}/${c}/lib"; \
+ { [ -d "$b" ] && [ -d "$s" ]; } || { echo ">> skip ${c} (dir missing)"; continue; }; \
+ if [ "${c}" = "npp" ]; then \
+ rm -rf "$s" && ln -s "$b" "$s" && readlink -e "$s" >/dev/null; \
+ echo ">> deduped npp -> base (pruned)"; \
+ elif [ "$(cd "$s" && ls | sort | tr '\n' ' ')" = "$(cd "$b" && ls | sort | tr '\n' ' ')" ]; then \
+ rm -rf "$s" && ln -s "$b" "$s" && readlink -e "$s" >/dev/null; \
+ echo ">> deduped ${c} -> base"; \
+ else \
+ echo ">> skip ${c} (file set differs base vs studio)"; \
+ fi; \
+ done; \
+ echo "studio venv size after dedup:"; du -sh "${UNSLOTH_STUDIO_HOME}/unsloth_studio"; \
+ fi
+
+COPY supervisord.conf /etc/supervisor/supervisord.conf
+COPY studio_launch.sh /usr/local/bin/unsloth-studio-launch
+# In-place updaters (no image pull):
+# unsloth-studio-update refresh Studio packages (backend + frontend) and restart
+# unsloth-llama-update swap the baked llama.cpp prebuilt to the latest release
+COPY unsloth_studio_update.sh /usr/local/bin/unsloth-studio-update
+COPY unsloth_llama_update.sh /usr/local/bin/unsloth-llama-update
+# unsloth-llama-update reuses the build-time fetcher (redirect-based, not rate-
+# limited; deterministic portable bundle) rather than the host-probing installer.
+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 (theme, non-advancing run button,
+# labeled "Restart & Run All", windowing off, cell-nav keymap, news prompt off).
+# overrides.json is the settings override; theme + keymap + logo ship as the
+# prebuilt labextension from labext-builder 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 (applied to jupyter_server's site-packages): replace favicon +
+# logo, brand login.html, disable+lock the stock top-left logo. Only the
+# sloth-sticker install is fail-soft (`|| echo`); the copies above stay fatal.
+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" \
+ && { /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 \
+ && /opt/unsloth-venv/bin/jupyter labextension disable @jupyterlab/apputils-extension:splash \
+ && /opt/unsloth-venv/bin/jupyter labextension lock @jupyterlab/apputils-extension:splash \
+ && /opt/unsloth-venv/bin/jupyter labextension lock unsloth-jupyterlab
+# Branding integrity guard: the attribution checker (a jupyter_server extension),
+# the AGPLv3 license text, and its enabling config, into the base venv. --verify
+# FAILS the build if any attribution / license asset is missing or altered.
+COPY jupyter/unsloth_branding.py /tmp/unsloth-branding-guard/unsloth_branding.py
+COPY jupyter/jupyter_server_config.d/unsloth_branding_guard.json /tmp/unsloth-branding-guard/unsloth_branding_guard.json
+RUN SP="$(/opt/unsloth-venv/bin/python -c 'import sysconfig; print(sysconfig.get_path("purelib"))')" \
+ && cp /tmp/unsloth-branding-guard/unsloth_branding.py "${SP}/unsloth_branding.py" \
+ && mkdir -p /opt/unsloth-venv/etc/jupyter/jupyter_server_config.d \
+ && cp /tmp/unsloth-branding-guard/unsloth_branding_guard.json \
+ /opt/unsloth-venv/etc/jupyter/jupyter_server_config.d/unsloth_branding_guard.json \
+ && cp "${UNSLOTH_STUDIO_HOME}/src/studio/LICENSE.AGPL-3.0" \
+ /opt/unsloth-venv/share/jupyter/UNSLOTH_LICENSE.AGPL-3.0 \
+ && rm -rf /tmp/unsloth-branding-guard \
+ && /opt/unsloth-venv/bin/python -m unsloth_branding --verify
+RUN chmod +x /usr/local/bin/unsloth-studio-launch \
+ /usr/local/bin/unsloth-studio-update \
+ /usr/local/bin/unsloth-llama-update \
+ /usr/local/bin/unsloth-jupyter-tunnel
+
+# Studio, JupyterLab, sshd. All bind 0.0.0.0 in the container; publish with -p.
+EXPOSE 8000 8888 22
+
+# The base ENTRYPOINT (unsloth-entrypoint) still runs its GPU pre-flight
+# first, then hands off to the service launcher.
+CMD ["/usr/local/bin/unsloth-studio-launch"]
diff --git a/docker/NOTICE b/docker/NOTICE
new file mode 100644
index 00000000000..df23375f7a3
--- /dev/null
+++ b/docker/NOTICE
@@ -0,0 +1,41 @@
+Unsloth Docker Studio and JupyterLab image
+==========================================
+
+This directory builds the Unsloth Docker Studio and JupyterLab image. The image
+bundles Unsloth Studio, which is licensed under the GNU Affero General Public
+License v3.0 (see /studio/LICENSE.AGPL-3.0). Unsloth Core is licensed under the
+Apache License 2.0 (see /LICENSE).
+
+
+Additional terms under AGPLv3 Section 7
+---------------------------------------
+
+As permitted by Section 7(b) of the GNU Affero General Public License v3.0, and
+in support of the "Appropriate Legal Notices" requirement for interactive user
+interfaces, the following author attributions and legal notices are designated
+as required Appropriate Legal Notices for this image. If you convey, modify, or
+make the image (or any work based on it) available to users over a network, you
+must keep these notices intact and displayed to those users:
+
+ * The attribution "Built by the Unsloth team".
+ * The copyright line "Copyright 2026-Present the Unsloth team".
+ * The license notice "Licensed under Apache 2.0 and the GNU AGPLv3".
+ * The Unsloth logo and the "Unsloth Dark" theme shown in the JupyterLab top
+ bar and on the loading splash.
+ * The Help > About dialog, including the following links:
+ - Source: https://github.com/unslothai/unsloth
+ - Website: https://unsloth.ai
+ - License: https://github.com/unslothai/unsloth#license
+ - AGPLv3: https://www.gnu.org/licenses/agpl-3.0.html
+ - Apache: https://www.apache.org/licenses/LICENSE-2.0
+
+These notices are displayed on the JupyterLab login page, the Help > About
+dialog, the loading splash and the top bar. They are enforced at build time and
+at runtime by docker/jupyter/unsloth_branding.py (see docker/jupyter/BRANDING.md
+for details). Removing or altering them, whether by editing the build workflow,
+the branding sources or the integrity guard, does not remove this license
+condition.
+
+"Unsloth" and the Unsloth logo are trademarks of the Unsloth team. This NOTICE
+governs copyright attribution under the AGPLv3 and does not grant any trademark
+license.
diff --git a/docker/build.sh b/docker/build.sh
new file mode 100755
index 00000000000..e7eac3f2df0
--- /dev/null
+++ b/docker/build.sh
@@ -0,0 +1,101 @@
+#!/usr/bin/env bash
+# Build the unsloth-blackwell image on any Linux host with Docker. The build host's
+# GPU is NOT used: nvcc cross-compiles.
+#
+# Usage:
+# ./build.sh # builds unsloth-blackwell:latest pinned to unsloth main
+# TAG=2026.05.1 ./build.sh # custom tag
+# UNSLOTH_REF=v2026.5.6 UNSLOTH_ZOO_REF=v2026.5.4 ./build.sh # pin git refs
+set -euo pipefail
+
+cd "$(dirname "$0")"
+
+IMAGE_NAME="${IMAGE_NAME:-unsloth-blackwell}"
+TAG="${TAG:-latest}"
+CUDA_VERSION="${CUDA_VERSION:-12.8.1}"
+UBUNTU_VERSION="${UBUNTU_VERSION:-24.04}"
+PYTHON_VERSION="${PYTHON_VERSION:-3.12}"
+UNSLOTH_REF="${UNSLOTH_REF:-main}"
+UNSLOTH_ZOO_REF="${UNSLOTH_ZOO_REF:-main}"
+UNSLOTH_NOTEBOOKS_REF="${UNSLOTH_NOTEBOOKS_REF:-main}"
+
+# Frozen to a commit here, for the same reason LLAMA_PREBUILT_TAG is resolved below and
+# the publish workflow freezes both refs with git ls-remote: docker matches a RUN layer
+# on the COMMAND STRING alone, so with the default "main" the pip-install layer is a
+# cache HIT on every rebuild and the image keeps the commits of the first build while
+# reporting success. A sha changes the build arg exactly when the branch moves.
+resolve_git_ref() {
+ local repo="$1" ref="$2" ls_out sha
+ printf '%s' "$ref" | grep -Eq '^[0-9a-f]{40}$' && { printf '%s' "$ref"; return 0; }
+ command -v git >/dev/null 2>&1 || { printf '%s' "$ref"; return 0; }
+ # ls-remote exits 0 whether or not a ref matched, so a non-zero exit means the
+ # remote was never reached; an offline build cannot install from git anyway, so
+ # warn and pass the name through rather than fail before docker has even started.
+ if ! ls_out="$(git ls-remote "$repo" "$ref" 2>/dev/null)"; then
+ echo "warning: ${repo} unreachable; passing mutable ref '${ref}' (docker may reuse a cached layer)" >&2
+ printf '%s' "$ref"
+ return 0
+ fi
+ sha="$(printf '%s\n' "$ls_out" | awk 'NR==1{print $1}')"
+ [ -n "$sha" ] || sha="$ref" # not a branch/tag: a short sha or already-gone ref
+ printf '%s' "$sha"
+}
+UNSLOTH_REF="$(resolve_git_ref https://github.com/unslothai/unsloth "$UNSLOTH_REF")"
+UNSLOTH_ZOO_REF="$(resolve_git_ref https://github.com/unslothai/unsloth-zoo "$UNSLOTH_ZOO_REF")"
+# The baked notebooks are one more RUN layer keyed on a mutable ref, and the publish
+# workflow already freezes this one; leaving it out here meant a rebuild after
+# unslothai/notebooks moved silently kept the old set, and stamped the old commit
+# into .unsloth_template_commit so the image misreported which set it carried.
+UNSLOTH_NOTEBOOKS_REF="$(resolve_git_ref https://github.com/unslothai/notebooks "$UNSLOTH_NOTEBOOKS_REF")"
+
+# Resolved to a concrete tag here, so the build-arg changes only on a new release and
+# layer caching stays correct. Pin with LLAMA_PREBUILT_TAG=... for a frozen build.
+resolve_latest_llama_tag() {
+ curl -fsSL -o /dev/null -w '%{url_effective}' \
+ "https://github.com/unslothai/llama.cpp/releases/latest" 2>/dev/null \
+ | sed -n 's#.*/releases/tag/##p'
+}
+if [ -z "${LLAMA_PREBUILT_TAG:-}" ]; then
+ LLAMA_PREBUILT_TAG="$(resolve_latest_llama_tag || true)"
+ if [ -n "$LLAMA_PREBUILT_TAG" ]; then
+ echo "Resolved latest llama.cpp release: ${LLAMA_PREBUILT_TAG}"
+ else
+ LLAMA_PREBUILT_TAG="latest"
+ echo "Could not resolve latest llama.cpp tag here; passing 'latest' (resolved inside the build)"
+ fi
+fi
+
+echo "Building ${IMAGE_NAME}:${TAG}"
+echo " CUDA ${CUDA_VERSION} Ubuntu ${UBUNTU_VERSION} Python ${PYTHON_VERSION}"
+echo " unsloth @${UNSLOTH_REF}"
+echo " unsloth-zoo @${UNSLOTH_ZOO_REF}"
+echo " llama.cpp ${LLAMA_PREBUILT_TAG}"
+echo " notebooks @${UNSLOTH_NOTEBOOKS_REF}"
+# Read the arch list out of the Dockerfile rather than repeating it: the hand-copied
+# banner had already drifted. Bare filename because the script cd'd to its own dir.
+ARCH_LIST="$(sed -n 's/^[[:space:]]*TORCH_CUDA_ARCH_LIST="\([^"]*\)".*/\1/p' \
+ Dockerfile | head -n1)"
+echo " arch list ${ARCH_LIST:-unknown}"
+echo
+
+DOCKER_BUILDKIT=1 docker build \
+ --progress=plain \
+ --build-arg CUDA_VERSION="${CUDA_VERSION}" \
+ --build-arg UBUNTU_VERSION="${UBUNTU_VERSION}" \
+ --build-arg PYTHON_VERSION="${PYTHON_VERSION}" \
+ --build-arg UNSLOTH_REF="${UNSLOTH_REF}" \
+ --build-arg UNSLOTH_ZOO_REF="${UNSLOTH_ZOO_REF}" \
+ --build-arg LLAMA_PREBUILT_TAG="${LLAMA_PREBUILT_TAG}" \
+ --build-arg UNSLOTH_NOTEBOOKS_REF="${UNSLOTH_NOTEBOOKS_REF}" \
+ -t "${IMAGE_NAME}:${TAG}" \
+ .
+
+echo
+echo "Built ${IMAGE_NAME}:${TAG}"
+echo
+echo "Smoke test on this host (B200, sm_100):"
+echo " docker run --rm --gpus all ${IMAGE_NAME}:${TAG} python /workspace/smoke_test.py"
+echo
+echo "Smoke test on an RTX 5090 host (sm_120):"
+echo " docker pull ${IMAGE_NAME}:${TAG} # or load .tar"
+echo " docker run --rm --gpus all ${IMAGE_NAME}:${TAG} python /workspace/smoke_test.py"
diff --git a/docker/entrypoint.sh b/docker/entrypoint.sh
new file mode 100755
index 00000000000..2da169502d7
--- /dev/null
+++ b/docker/entrypoint.sh
@@ -0,0 +1,193 @@
+#!/usr/bin/env bash
+# Container startup checks for Unsloth. Fails fast with actionable errors when the
+# host GPU isn't reachable, catching the three modes behind ~95% of tickets:
+# 1. nvidia-smi sees no GPU (missing --gpus all or nvidia-container-toolkit)
+# 2. nvidia-smi works but torch.cuda.is_available() is False (driver too old)
+# 3. GPU older than Ampere (sm < 80; Unsloth requires sm_80+)
+# Bypass for offline tooling/docs/CI: docker run -e UNSLOTH_SKIP_GPU_CHECK=1 ...
+set -euo pipefail
+
+# CUDA 13 ptxas + NVRTC are baked only for sm_103 and sm_121, which cu12.8 cannot
+# target and which ship on >=580 drivers; every other arch is cu12.8 on the 570-579
+# floor, where a cu13 cubin cannot load. So the choice is per DEVICE at boot.
+select_cuda_jit_tools() {
+ local caps="" cc nvrtc_dir need_cu13=0
+ if command -v nvidia-smi >/dev/null 2>&1; then
+ caps="$( { nvidia-smi --query-gpu=compute_cap --format=csv,noheader 2>/dev/null || true; } )"
+ fi
+ # scan EVERY visible GPU: an sm_103/sm_121 part can sit behind an H100
+ while IFS= read -r cc || [[ -n "${cc}" ]]; do
+ cc="$(printf '%s' "${cc}" | tr -d '[:space:]')"
+ case "${cc}" in
+ 10.3|12.1) need_cu13=1 ;;
+ esac
+ done <<< "${caps}"
+ # reverse a .cu13 link an earlier sm_103/sm_121 boot left in the writable layer
+ if [[ "${need_cu13}" -ne 1 ]]; then
+ for nvrtc_dir in \
+ /opt/unsloth-venv/lib/python*/site-packages/nvidia/cuda_nvrtc/lib \
+ "${UNSLOTH_STUDIO_HOME:-/opt/unsloth-studio}"/unsloth_studio/lib/python*/site-packages/nvidia/cuda_nvrtc/lib; do
+ [[ -e "${nvrtc_dir}/libnvrtc.so.12.cu128.orig" ]] || continue
+ [[ "$(readlink "${nvrtc_dir}/libnvrtc.so.12" 2>/dev/null)" == "libnvrtc.so.12.cu13" ]] || continue
+ ln -sf libnvrtc.so.12.cu128.orig "${nvrtc_dir}/libnvrtc.so.12" 2>/dev/null || true
+ done
+ return 0
+ fi
+ if [[ -x /usr/local/cuda-13.0/bin/ptxas && -z "${TRITON_PTXAS_PATH:-}" ]]; then
+ export TRITON_PTXAS_PATH=/usr/local/cuda-13.0/bin/ptxas
+ fi
+ for nvrtc_dir in \
+ /opt/unsloth-venv/lib/python*/site-packages/nvidia/cuda_nvrtc/lib \
+ "${UNSLOTH_STUDIO_HOME:-/opt/unsloth-studio}"/unsloth_studio/lib/python*/site-packages/nvidia/cuda_nvrtc/lib; do
+ [[ -e "${nvrtc_dir}/libnvrtc.so.12.cu13" ]] || continue
+ ln -sf libnvrtc.so.12.cu13 "${nvrtc_dir}/libnvrtc.so.12" 2>/dev/null || true
+ done
+}
+select_cuda_jit_tools || true
+
+# best-effort, gated by UNSLOTH_SKIP_NOTEBOOK_SYNC, never blocks the container
+sync_notebooks() {
+ if [[ -x /usr/local/bin/unsloth-sync-notebooks ]]; then
+ /usr/local/bin/unsloth-sync-notebooks || true
+ fi
+}
+
+if [[ "${UNSLOTH_SKIP_GPU_CHECK:-0}" == "1" ]]; then
+ sync_notebooks
+ exec "$@"
+fi
+
+err() { printf "\033[1;31mERROR:\033[0m %s\n" "$*" >&2; }
+warn() { printf "\033[1;33mWARN:\033[0m %s\n" "$*" >&2; }
+
+# CPU mode covers Jupyter, GGUF tooling and Studio chat, but NOT training or loading
+# a model. A visible GPU still runs the checks below.
+if [[ "${UNSLOTH_ALLOW_CPU:-0}" == "1" ]]; then
+ if ! command -v nvidia-smi >/dev/null 2>&1 || ! nvidia-smi -L 2>/dev/null | grep -q '^GPU'; then
+ warn "UNSLOTH_ALLOW_CPU=1 and no GPU visible -- continuing on CPU."
+ warn "CPU mode covers Jupyter, GGUF tooling and llama.cpp (GGUF) Studio chat."
+ warn "Training and loading Unsloth models (FastLanguageModel) still require an NVIDIA GPU."
+ sync_notebooks
+ exec "$@"
+ fi
+fi
+
+# nvidia-smi is injected on a GPU request, not baked in, so a missing binary means
+# "no GPU attached", same as an empty -L
+if ! command -v nvidia-smi >/dev/null 2>&1 || ! nvidia-smi -L 2>/dev/null | grep -q '^GPU'; then
+ err "No GPU visible inside the container."
+ cat >&2 <<'MSG'
+
+Likely causes (in order of frequency):
+
+ 1. You started the container without --gpus all.
+ Re-launch with:
+ docker run --gpus all <other-flags> unsloth/unsloth:latest <cmd>
+ Or use the bundled wrapper:
+ bash docker/run.sh <cmd>
+
+ 2. Host is missing nvidia-container-toolkit.
+ Install: https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/install-guide.html
+ Then: sudo systemctl restart docker
+
+ 3. nvidia-container-toolkit is installed but the Docker daemon was not
+ restarted after install. Run:
+ sudo systemctl restart docker
+
+ 4. You are using Podman / Kubernetes / a managed container service that
+ needs a different GPU flag than --gpus all. See the relevant docs:
+ podman: --device nvidia.com/gpu=all
+ k8s: nvidia.com/gpu resource request + GPU operator
+
+ 5. This host has no NVIDIA GPU at all (Docker Desktop on macOS, Windows
+ without WSL2 GPU support, CPU-only Linux). Training and loading Unsloth
+ models need a GPU, but Jupyter, GGUF tooling and llama.cpp (GGUF) Studio
+ chat work on CPU:
+ docker run -e UNSLOTH_ALLOW_CPU=1 ...
+
+To bypass this check entirely (e.g. offline tooling), set UNSLOTH_SKIP_GPU_CHECK=1.
+MSG
+ exit 1
+fi
+
+python - >&2 <<'PY' || exit 1
+import sys
+import torch
+if torch.cuda.is_available():
+ sys.exit(0)
+print("ERROR: torch.cuda.is_available() is False despite nvidia-smi working.")
+print()
+print("This image bakes in CUDA 12.8, so the host driver MUST be:")
+print(" >= 570.26 (toolkit floor for cu128, applies to every GPU)")
+print()
+print("Two GPUs need an even newer driver because their launch driver was")
+print("released after cu128's:")
+print(" >= 580 B300 / GB300 (sm_103)")
+print(" >= 580 GB10 / DGX Spark (sm_121)")
+print()
+print("Check the host (NOT the container) with: nvidia-smi")
+print("Then upgrade the driver to match.")
+sys.exit(1)
+PY
+
+python - >&2 <<'PY' || exit 1
+import sys
+import torch
+major, minor = torch.cuda.get_device_capability(0)
+name = torch.cuda.get_device_name(0)
+n = torch.cuda.device_count()
+print(f"Unsloth container: {n} GPU(s). Primary: {name} sm_{major}{minor} bf16={torch.cuda.is_bf16_supported()}")
+
+SUPPORTED = (
+ ("sm_75", "Turing", "T4, RTX 20-series, Quadro RTX"),
+ ("sm_80", "Ampere DC", "A100, A30"),
+ ("sm_86", "Ampere", "A40, RTX A6000, RTX 30-series"),
+ ("sm_89", "Ada", "L4, L40, L40S, RTX 40-series"),
+ ("sm_90", "Hopper", "H100, H200, GH200"),
+ ("sm_100", "Blackwell DC", "B100, B200, GB200"),
+ ("sm_103", "Blackwell DC", "B300, GB300"),
+ ("sm_120", "Blackwell", "RTX 50-series, RTX PRO 6000 Blackwell"),
+ ("sm_121", "Blackwell", "GB10 (DGX Spark)"),
+)
+if major < 7 or (major == 7 and minor < 5):
+ print()
+ print(f"ERROR: Unsloth image requires Turing or newer (sm_75+). Got {name} sm_{major}{minor}.")
+ print()
+ print("Supported architectures in this image:")
+ for arch, fam, ex in SUPPORTED:
+ print(f" {arch:7s} {fam:13s} ({ex})")
+ sys.exit(1)
+if major < 8:
+ print(f"NOTE: {name} is Turing (sm_{major}{minor}) -- bfloat16 is not supported.")
+ print(" Unsloth will fall back to fp16. Training works but is slightly slower.")
+
+# an unsupported secondary only surfaces when a job pins to it, so warn now
+for d in range(1, n):
+ dmaj, dmin = torch.cuda.get_device_capability(d)
+ if dmaj < 7 or (dmaj == 7 and dmin < 5):
+ dname = torch.cuda.get_device_name(d)
+ print(f"WARNING: GPU {d} ({dname}, sm_{dmaj}{dmin}) is below this image's sm_75 floor.")
+ print(" Multi-GPU runs that include it, or jobs pinned to it, will fail;")
+ print(" exclude it with CUDA_VISIBLE_DEVICES or --gpus device=<supported>.")
+PY
+
+# Upstream ships no CUDA 12 arm64 llama.cpp, so the arm64 image bakes cu13 while torch
+# runs on 570+: below 580, GGUF export and Studio chat fail even though training works.
+if [ "$(uname -m)" = "aarch64" ]; then
+ _drv="$(nvidia-smi --query-gpu=driver_version --format=csv,noheader 2>/dev/null | head -1)"
+ _drv_major="${_drv%%.*}"
+ case "$_drv_major" in
+ *[!0-9]* | "") ;; # unreadable driver version -> no claim to make
+ *)
+ if [ "$_drv_major" -lt 580 ]; then
+ echo "WARNING: this arm64 image bakes a CUDA 13 llama.cpp (upstream ships no CUDA 12 arm64 build)." >&2
+ echo " Host driver $_drv is < 580, which cannot load CUDA 13 binaries:" >&2
+ echo " training (torch cu128) works, but GGUF export / Studio chat will fail" >&2
+ echo " until the host driver is upgraded to >= 580." >&2
+ fi
+ ;;
+ esac
+fi
+
+sync_notebooks
+exec "$@"
diff --git a/docker/fetch_llama_prebuilt.py b/docker/fetch_llama_prebuilt.py
new file mode 100644
index 00000000000..4a5e1d9b412
--- /dev/null
+++ b/docker/fetch_llama_prebuilt.py
@@ -0,0 +1,227 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-Present the Unsloth team. See /studio/LICENSE.AGPL-3.0
+
+"""Bake a pinned llama.cpp prebuilt into the Docker image, deterministically.
+
+Not studio/install_llama_prebuilt.py: that resolver selects a bundle for the CURRENT
+host, where an image build must produce byte-identical layers everywhere. Pins release
+and asset by build target only:
+
+ amd64 -> app-<tag>-linux-x64-cuda12-portable.tar.gz (sm_70..sm_120)
+ arm64 -> app-<tag>-linux-arm64-cuda13-portable.tar.gz (sm_90..sm_121)
+
+The portable bundles dlopen the CUDA backend, so the same binaries also run CPU-only.
+Every download is sha256-verified, and the converter + gguf-py come from the SAME
+release's source tarball so the tensor mappings match the binaries. A "latest" tag is
+resolved at build time; pass a concrete tag for a reproducible build.
+
+Usage (in the Dockerfile):
+ python fetch_llama_prebuilt.py <tag|latest> <targetarch> <install_dir>
+"""
+
+import hashlib
+import json
+import os
+import re
+import shutil
+import subprocess
+import sys
+import tarfile
+import tempfile
+import urllib.request
+
+RELEASE_REPO = "unslothai/llama.cpp"
+
+
+def base_build_tag(tag: str) -> str:
+ """Normalized upstream build out of a release tag: b10715 from b10715-mix-86bd2d3.
+ Mirrors llama_cpp_freshness.parse_base_build; a tag that is not bNNNN is kept."""
+ match = re.match(r"b(\d+)", tag.strip())
+ return f"b{match.group(1)}" if match else tag.strip()
+
+
+def resolve_latest_tag(repo: str) -> str:
+ url = f"https://github.com/{repo}/releases/latest"
+ request = urllib.request.Request(url, headers = {"User-Agent": "unsloth-docker-build"})
+ with urllib.request.urlopen(request, timeout = 60) as response:
+ 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})"
+ )
+ return final_url.rsplit(marker, 1)[1].strip("/")
+
+
+def fetch(url: str, dest: str) -> None:
+ request = urllib.request.Request(url, headers = {"User-Agent": "unsloth-docker-build"})
+ with urllib.request.urlopen(request, timeout = 600) as response, open(dest, "wb") as f:
+ shutil.copyfileobj(response, f, length = 1 << 20)
+
+
+def sha256_file(path: str) -> str:
+ digest = hashlib.sha256()
+ with open(path, "rb") as f:
+ for chunk in iter(lambda: f.read(1 << 20), b""):
+ digest.update(chunk)
+ return digest.hexdigest()
+
+
+def fetch_verified(base_url: str, name: str, sums: dict, work: str) -> str:
+ path = os.path.join(work, name)
+ fetch(f"{base_url}/{name}", path)
+ expected = sums.get(name, {}).get("sha256")
+ if not expected:
+ raise SystemExit(f"FAIL: {name} not listed in llama-prebuilt-sha256.json")
+ actual = sha256_file(path)
+ if actual != expected:
+ raise SystemExit(f"FAIL: sha256 mismatch for {name}: expected {expected}, got {actual}")
+ print(f"verified {name} sha256={actual[:16]}...")
+ return path
+
+
+def extracted_root(extract_dir: str) -> str:
+ children = os.listdir(extract_dir)
+ if len(children) == 1 and os.path.isdir(os.path.join(extract_dir, children[0])):
+ return os.path.join(extract_dir, children[0])
+ return extract_dir
+
+
+def sanity_check_binaries(install_dir, build_bin):
+ checks = (
+ # exit 0 too: a dynamic-loader failure prints "version `GLIBC_...' not found",
+ # which the substring alone accepts even though it never reached main
+ (os.path.join(install_dir, "llama-server"), "version", True),
+ # no --version, and an unknown flag need not exit 0, so only the banner counts
+ (os.path.join(install_dir, "llama-quantize"), "usage", False),
+ (os.path.join(build_bin, "llama-quantize"), "usage", False),
+ )
+ for binary, expect, require_zero_exit in checks:
+ out = subprocess.run(
+ [binary, "--version"],
+ capture_output = True,
+ text = True,
+ timeout = 120,
+ )
+ banner = (out.stdout + out.stderr).strip()
+ print(
+ os.path.relpath(binary, install_dir),
+ "->",
+ banner.splitlines()[0] if banner else "(no output)",
+ )
+ if expect not in banner:
+ raise SystemExit(
+ f"FAIL: {binary} did not print '{expect}': rc={out.returncode}\n{banner[:400]}"
+ )
+ if require_zero_exit and out.returncode != 0:
+ raise SystemExit(
+ f"FAIL: {binary} --version exited {out.returncode}; the banner text is "
+ f"not enough on its own because a dynamic-loader failure prints "
+ f'"version `GLIBC_...\' not found" too\n{banner[:400]}'
+ )
+
+
+def main() -> None:
+ tag, target_arch, install_dir = sys.argv[1], sys.argv[2] or "amd64", sys.argv[3]
+ if tag in ("", "latest"):
+ tag = resolve_latest_tag(RELEASE_REPO)
+ print(f"resolved latest {RELEASE_REPO} release: {tag}")
+ base_url = f"https://github.com/{RELEASE_REPO}/releases/download/{tag}"
+ assets = {
+ "amd64": f"app-{tag}-linux-x64-cuda12-portable.tar.gz",
+ "arm64": f"app-{tag}-linux-arm64-cuda13-portable.tar.gz",
+ }
+ if target_arch not in assets:
+ raise SystemExit(f"FAIL: unsupported TARGETARCH={target_arch}")
+ bundle_name = assets[target_arch]
+ source_name = f"llama.cpp-source-{tag}.tar.gz"
+
+ with tempfile.TemporaryDirectory() as work:
+ sha_path = os.path.join(work, "llama-prebuilt-sha256.json")
+ fetch(f"{base_url}/llama-prebuilt-sha256.json", sha_path)
+ sums = json.load(open(sha_path))["artifacts"]
+
+ bundle_path = fetch_verified(base_url, bundle_name, sums, work)
+ bundle_dir = os.path.join(work, "bundle")
+ os.makedirs(bundle_dir)
+ with tarfile.open(bundle_path) as tf:
+ tf.extractall(bundle_dir, filter = "tar")
+ os.makedirs(install_dir, exist_ok = True)
+ root = extracted_root(bundle_dir)
+ for entry in os.listdir(root):
+ target = os.path.join(install_dir, entry)
+ shutil.move(os.path.join(root, entry), target)
+ if os.path.isfile(target) and not entry.startswith("lib") and ".so" not in entry:
+ os.chmod(target, 0o755)
+
+ source_path = fetch_verified(base_url, source_name, sums, work)
+ source_dir = os.path.join(work, "source")
+ os.makedirs(source_dir)
+ with tarfile.open(source_path) as tf:
+ tf.extractall(source_dir, filter = "tar")
+ src_root = extracted_root(source_dir)
+ converter = os.path.join(src_root, "convert_hf_to_gguf.py")
+ gguf_py = os.path.join(src_root, "gguf-py")
+ if not (os.path.isfile(converter) and os.path.isdir(gguf_py)):
+ raise SystemExit(f"FAIL: source tarball for {tag} is missing converter files")
+ for script in os.listdir(src_root):
+ if script.startswith("convert_") and script.endswith(".py"):
+ shutil.copy2(os.path.join(src_root, script), os.path.join(install_dir, script))
+ shutil.copytree(gguf_py, os.path.join(install_dir, "gguf-py"), dirs_exist_ok = True)
+ conversion = os.path.join(src_root, "conversion")
+ if os.path.isdir(conversion):
+ shutil.copytree(conversion, os.path.join(install_dir, "conversion"), dirs_exist_ok = True)
+
+ # Studio's freshness check wants the install_llama_prebuilt.py schema: "tag" is the
+ # NORMALIZED BASE build, "release_tag" the full release. No timestamp, so layers
+ # stay identical.
+ marker_path = os.path.join(install_dir, "UNSLOTH_PREBUILT_INFO.json")
+ try:
+ with open(marker_path) as f:
+ marker = json.load(f)
+ except (OSError, ValueError):
+ marker = {}
+ llama_tag = base_build_tag(marker.get("upstream_tag") or tag)
+ marker.setdefault("tag", llama_tag)
+ marker.setdefault("release_tag", tag)
+ marker.setdefault("published_repo", RELEASE_REPO)
+ with open(marker_path, "w") as f:
+ json.dump(marker, f, indent = 2)
+ f.write("\n")
+ print(
+ f"marker augmented for freshness: tag={marker['tag']} "
+ f"release_tag={marker['release_tag']} published_repo={RELEASE_REPO}"
+ )
+
+ # Mirror into build/bin/ so Studio's setup.sh sees a complete local build and skips
+ # its source-build fallback, which would compile CPU-only llama.cpp over the baked
+ # CUDA bundle. Hardlinks keep the $ORIGIN rpath.
+ build_bin = os.path.join(install_dir, "build", "bin")
+ os.makedirs(build_bin, exist_ok = True)
+ for entry in os.listdir(install_dir):
+ source = os.path.join(install_dir, entry)
+ if os.path.isfile(source) and not os.path.islink(source):
+ try:
+ os.link(source, os.path.join(build_bin, entry))
+ except OSError:
+ shutil.copy2(source, os.path.join(build_bin, entry))
+ elif os.path.islink(source):
+ target = os.readlink(source)
+ dest = os.path.join(build_bin, entry)
+ if "/" not in target and not os.path.lexists(dest):
+ os.symlink(target, dest)
+
+ sanity_check_binaries(install_dir, build_bin)
+ for required in (
+ "llama-quantize",
+ "convert_hf_to_gguf.py",
+ "gguf-py",
+ "UNSLOTH_PREBUILT_INFO.json",
+ ):
+ if not os.path.exists(os.path.join(install_dir, required)):
+ raise SystemExit(f"FAIL: {required} missing from {install_dir}")
+ print(f"OK: llama.cpp {tag} ({bundle_name}) installed at {install_dir}")
+
+
+if __name__ == "__main__":
+ main()
diff --git a/docker/jupyter/BRANDING.md b/docker/jupyter/BRANDING.md
new file mode 100644
index 00000000000..66605757366
--- /dev/null
+++ b/docker/jupyter/BRANDING.md
@@ -0,0 +1,50 @@
+# Unsloth Docker Studio branding
+
+The Unsloth Docker Studio and JupyterLab image ships Unsloth attribution across
+several files. Preserving it is a license condition, not just a build check. See
+[../NOTICE](../NOTICE) and [/studio/LICENSE.AGPL-3.0](../../studio/LICENSE.AGPL-3.0).
+
+## What must stay
+
+- `Built by the Unsloth team` (login page and the labextension).
+- `Copyright 2026-Present the Unsloth team`.
+- `Licensed under Apache 2.0 and the GNU AGPLv3`.
+- The Unsloth logo and the `Unsloth Dark` theme in the top bar and on the splash.
+- The Help > About dialog with the Source, Website, License, AGPLv3 and Apache
+ links.
+
+The canonical strings live in `unsloth_branding.py` and its TypeScript mirror
+`unsloth_labext/src/branding.ts`. The `PHRASE` literal must be byte-identical
+between the two, because the guard greps the built labextension bundle for it.
+
+## Where it lives
+
+| File | Carries |
+| --- | --- |
+| `login.html` | JupyterLab login page and attribution line. |
+| `unsloth_labext/src/branding.ts` | Canonical attribution strings (TS mirror). |
+| `unsloth_labext/src/about.ts` | Help > About dialog and the license links. |
+| `unsloth_labext/src/splash.ts` | Loading-splash caption. |
+| `unsloth_labext/src/logo.ts` | Embedded Unsloth logo data URI. |
+| `unsloth_branding.py` | Canonical strings and the integrity guard. |
+
+## How it is enforced
+
+`unsloth_branding.py` verifies the attribution is present and unaltered in three
+places (see [../Dockerfile.studio](../Dockerfile.studio) and
+[../studio_launch.sh](../studio_launch.sh)):
+
+1. **Build time:** `python -m unsloth_branding --verify` fails the image build if
+ any attribution asset is missing or altered.
+2. **Whole image:** `studio_launch.sh` re-runs the same check before starting
+ supervisord; a failure refuses to start the container.
+3. **JupyterLab:** the module is also a `jupyter_server` extension that re-checks
+ on load and refuses to serve JupyterLab if attribution was stripped after the
+ container started.
+
+The guard is a tripwire, not a lock. Anyone who forks the source controls the
+build and can edit any of these files. It exists to make accidental removal fail
+loudly and to make deliberate removal unambiguous. The attribution is protected
+by the AGPLv3 as an Appropriate Legal Notice (see [../NOTICE](../NOTICE)), and
+removing it before conveying or network-serving the image is a license
+violation.
diff --git a/docker/jupyter/favicon.ico b/docker/jupyter/favicon.ico
new file mode 100644
index 00000000000..f922d8df9e3
Binary files /dev/null and b/docker/jupyter/favicon.ico differ
diff --git a/docker/jupyter/install_sloth_stickers.py b/docker/jupyter/install_sloth_stickers.py
new file mode 100644
index 00000000000..97bfb0bad3f
--- /dev/null
+++ b/docker/jupyter/install_sloth_stickers.py
@@ -0,0 +1,73 @@
+#!/usr/bin/env python3
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-Present the Unsloth team. See /studio/LICENSE.AGPL-3.0
+
+"""Install the Unsloth Studio sloth stickers for the JupyterLab login screen.
+
+Copies the curated subset of `studio/frontend/public/Sloth emojis/` into
+jupyter_server's static dir as `sloth/01.png .. sloth/20.png`, so login.html can
+reference stable, space-free, auth-free `static_url(...)` paths.
+
+Usage:
+ install_sloth_stickers.py --src "<Sloth emojis dir>" --dest "<static>/sloth"
+
+Fail-soft: a missing source file is skipped (login.html's onerror falls back to the
+Unsloth logo) and the script still exits 0 if at least one sticker was installed.
+"""
+
+import argparse
+import os
+import shutil
+import sys
+
+# in display order -> NN.png; mirrors Studio's SLOTH_AVATARS, synced by hand
+CURATED = [
+ "large sloth yay.png",
+ "large sloth heart.png",
+ "large sloth wave.png",
+ "large sloth thumbs.png",
+ "large sloth cheeky.png",
+ "large sloth glasses.png",
+ "large sloth fire.png",
+ "large sloth drink.png",
+ "large sloth sad.png",
+ "Large sloth Question mark.png",
+ "sloth shy large.png",
+ "sloth shock large.png",
+ "sloth sir large.png",
+ "sloth huglove large.png",
+ "sloth headphones.png",
+ "sloth pc square.png",
+ "sloth on phone.png",
+ "sloth magnify final.png",
+ "Sloth loca pc.png",
+ "UnSloth GPU Front square.png",
+]
+
+
+def main() -> int:
+ parser = argparse.ArgumentParser(description = __doc__)
+ parser.add_argument("--src", required = True, help = "Studio 'Sloth emojis' dir")
+ parser.add_argument("--dest", required = True, help = "output dir (static/sloth)")
+ args = parser.parse_args()
+
+ os.makedirs(args.dest, exist_ok = True)
+ installed = 0
+ for index, name in enumerate(CURATED, start = 1):
+ source = os.path.join(args.src, name)
+ target = os.path.join(args.dest, "%02d.png" % index)
+ if not os.path.isfile(source):
+ print(" skip (missing): %s" % name)
+ continue
+ try:
+ shutil.copyfile(source, target)
+ installed += 1
+ except OSError as error:
+ print(" skip (%s): %s" % (error, name))
+
+ print("installed %d/%d sloth stickers into %s" % (installed, len(CURATED), args.dest))
+ return 0 if installed else 1
+
+
+if __name__ == "__main__":
+ sys.exit(main())
diff --git a/docker/jupyter/jupyter_server_config.d/unsloth_branding_guard.json b/docker/jupyter/jupyter_server_config.d/unsloth_branding_guard.json
new file mode 100644
index 00000000000..592d6ad6de6
--- /dev/null
+++ b/docker/jupyter/jupyter_server_config.d/unsloth_branding_guard.json
@@ -0,0 +1,7 @@
+{
+ "ServerApp": {
+ "jpserver_extensions": {
+ "unsloth_branding": true
+ }
+ }
+}
diff --git a/docker/jupyter/login.html b/docker/jupyter/login.html
new file mode 100644
index 00000000000..ac029434f74
--- /dev/null
+++ b/docker/jupyter/login.html
@@ -0,0 +1,118 @@
+{# Unsloth-branded JupyterLab login page. Overwrites jupyter_server's default
+ login.html (same overwrite pattern as the favicon/logo). Extends the stock
+ page.html so favicon (already the Unsloth icon) and form plumbing stay intact;
+ we override the title, hide the stock header, and render a dark centered card
+ matching the "Unsloth Dark" (Monokai) theme. The card logo reads
+ static/logo/logo.png, which the image build replaces with the Unsloth logo. #}
+{% extends "page.html" %}
+
+{% block title %}Unsloth{% endblock %}
+
+{% block stylesheet %}
+<style>
+ html, body {
+ background: hsl(70, 8%, 12%) !important;
+ color: hsl(60, 30%, 96%);
+ font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif;
+ }
+ /* Hide the stock top header (jupyter_server's index.css uses a higher-
+ specificity selector, so force it); the centered card carries the brand. */
+ #header, .header-bar { display: none !important; }
+ /* Column, not the flex default row: #site holds two children (the login card
+ and the AGPLv3 attribution). As a row they sat side by side, pushing the card
+ left of centre and the attribution up to the top-right. Stack them so the card
+ is horizontally centred and the attribution sits below it as a footer. */
+ #site { display: flex; flex-direction: column; align-items: center; justify-content: flex-start; }
+ .unsloth-login-card {
+ margin-top: 11vh;
+ background: hsl(70, 8%, 18%);
+ border: 1px solid hsl(70, 8%, 28%);
+ border-radius: 12px;
+ padding: 38px 40px 32px;
+ width: 360px;
+ max-width: 90vw;
+ text-align: center;
+ box-shadow: 0 10px 34px rgba(0, 0, 0, 0.45);
+ }
+ .unsloth-login-card img.logo { height: 72px; width: auto; margin-bottom: 14px; }
+ /* A random Unsloth Studio sloth sticker, shown like the Studio login screen. */
+ .unsloth-login-card img.sloth {
+ height: 104px; width: 104px; object-fit: contain;
+ margin: 2px auto 10px; display: block;
+ }
+ .unsloth-login-card h1 { font-size: 22px; margin: 0 0 4px; font-weight: 700; }
+ .unsloth-login-card p.sub { color: hsl(60, 8%, 64%); margin: 0 0 24px; font-size: 14px; }
+ .unsloth-login-card label {
+ display: block; text-align: left; font-size: 13px;
+ margin-bottom: 6px; color: hsl(60, 8%, 76%);
+ }
+ .unsloth-login-card input[type="password"] {
+ width: 100%; box-sizing: border-box; padding: 10px 12px;
+ border-radius: 8px; border: 1px solid hsl(70, 8%, 32%);
+ background: hsl(70, 8%, 13%); color: inherit; font-size: 14px; margin-bottom: 18px;
+ }
+ .unsloth-login-card input[type="password"]:focus {
+ outline: none; border-color: hsl(160, 55%, 48%);
+ }
+ .unsloth-login-card button {
+ width: 100%; padding: 10px 12px; border-radius: 8px; border: none;
+ background: hsl(160, 55%, 42%); color: #fff; font-weight: 600; font-size: 14px; cursor: pointer;
+ }
+ .unsloth-login-card button:hover { background: hsl(160, 55%, 36%); }
+ .unsloth-login-card .message { margin-top: 16px; font-size: 13px; }
+ .unsloth-login-card .message.error { color: hsl(0, 75%, 68%); }
+ /* License attribution footer. Part of the Unsloth attribution set the image's
+ integrity guard verifies (Built by the Unsloth team + AGPLv3 + copyright +
+ source link). */
+ .unsloth-attrib {
+ margin-top: 18px; text-align: center; font-size: 12px; line-height: 1.6;
+ color: hsl(60, 8%, 58%); width: 360px; max-width: 90vw;
+ }
+ .unsloth-attrib a { color: hsl(160, 45%, 60%); text-decoration: none; }
+ .unsloth-attrib a:hover { text-decoration: underline; }
+</style>
+{% endblock %}
+
+{% block site %}
+{# A different Unsloth Studio sloth sticker each visit (matches Studio's login).
+ The PNGs are copied into static/sloth/NN.png by the image build; if one is
+ missing the onerror handler falls back to the Unsloth logo so the page never
+ shows a broken image. #}
+{% set sloths = [
+ "01.png", "02.png", "03.png", "04.png", "05.png", "06.png", "07.png",
+ "08.png", "09.png", "10.png", "11.png", "12.png", "13.png", "14.png",
+ "15.png", "16.png", "17.png", "18.png", "19.png", "20.png"
+] %}
+<div class="unsloth-login-card">
+ <img class="sloth" src='{{ static_url("sloth/" ~ (sloths | random)) }}'
+ onerror="this.onerror=null;this.className='logo';this.src='{{ static_url('logo/logo.png') }}';"
+ alt='Unsloth' />
+ <h1>Unsloth</h1>
+ <p class="sub">Sign in to JupyterLab</p>
+ {% if login_available %}
+ <form action="{{base_url}}login?next={{next}}" method="post">
+ {{ xsrf_form_html() | safe }}
+ <label for="password_input">
+ {% if token_available %}{% trans %}Password or token{% endtrans %}{% else %}{% trans %}Password{% endtrans %}{% endif %}
+ </label>
+ <input type="password" name="password" id="password_input" autofocus>
+ <button type="submit" id="login_submit">{% trans %}Log in{% endtrans %}</button>
+ </form>
+ {% endif %}
+ {% if message %}
+ {% for key in message %}
+ <div class="message {{key}}">{{ message[key] }}</div>
+ {% endfor %}
+ {% endif %}
+</div>
+<div class="unsloth-attrib">
+ Built by the Unsloth team.
+ <a href="https://github.com/unslothai/unsloth#license" target="_blank" rel="noopener">Apache 2.0, AGPLv3 License Link</a><br/>
+ Copyright 2026-Present the Unsloth team.<br/>
+ <a href="https://github.com/unslothai/unsloth" target="_blank" rel="noopener">github.com/unslothai/unsloth</a>
+ &middot;
+ <a href="https://unsloth.ai" target="_blank" rel="noopener">unsloth.ai</a>
+</div>
+{% endblock %}
+
+{% block script %}{% endblock %}
diff --git a/docker/jupyter/logo.png b/docker/jupyter/logo.png
new file mode 100644
index 00000000000..8fc411695d9
Binary files /dev/null and b/docker/jupyter/logo.png differ
diff --git a/docker/jupyter/overrides.json b/docker/jupyter/overrides.json
new file mode 100644
index 00000000000..4fe9590fdbd
--- /dev/null
+++ b/docker/jupyter/overrides.json
@@ -0,0 +1,40 @@
+{
+ "@jupyterlab/apputils-extension:themes": {
+ "theme": "Unsloth Dark",
+ "theme-scrollbars": true,
+ "adaptive-theme": true,
+ "preferred-light-theme": "JupyterLab Light",
+ "preferred-dark-theme": "Unsloth Dark"
+ },
+ "@jupyterlab/notebook-extension:tracker": {
+ "windowingMode": "none",
+ "scrollPastEnd": true,
+ "codeCellConfig": {
+ "autoClosingBrackets": true
+ }
+ },
+ "@jupyterlab/cell-toolbar-extension:plugin": {
+ "toolbar": [
+ {
+ "name": "run-cell-no-advance",
+ "command": "notebook:run-cell",
+ "icon": "ui-components:run",
+ "rank": 0
+ }
+ ]
+ },
+ "@jupyterlab/notebook-extension:panel": {
+ "toolbar": [
+ {
+ "name": "restart-and-run",
+ "command": "notebook:restart-run-all",
+ "label": "Restart & Run All",
+ "rank": 33
+ }
+ ]
+ },
+ "@jupyterlab/apputils-extension:notification": {
+ "fetchNews": "false",
+ "checkForUpdates": false
+ }
+}
diff --git a/docker/jupyter/unsloth_branding.py b/docker/jupyter/unsloth_branding.py
new file mode 100644
index 00000000000..484a8ca6b13
--- /dev/null
+++ b/docker/jupyter/unsloth_branding.py
@@ -0,0 +1,254 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-Present the Unsloth team. See /studio/LICENSE.AGPL-3.0
+"""Unsloth Docker Studio branding + AGPLv3 attribution integrity guard.
+
+The plain-text source of truth for the attribution strings AND the checker that
+verifies they are still present. The attribution is spread over several independent
+files on purpose, so a shallow find-and-replace cannot white-label the image, and
+everything here is plain readable text: the only base64 blob is the logo data URI.
+
+Runs at image build time, from studio_launch.sh before supervisord, and as a
+jupyter_server extension.
+"""
+
+import json
+import os
+import sys
+
+# keep in sync with unsloth_labext/src/branding.ts: the guard greps the bundle for these
+PRODUCT = "Unsloth Docker Studio"
+SHORT_LABEL = "Built by the Unsloth team"
+SPLASH_LABEL = "Loading Unsloth Docker"
+COPYRIGHT = "Copyright 2026-Present the Unsloth team"
+AGPL_NOTICE = "Licensed under Apache 2.0 and the GNU AGPLv3"
+WEBSITE_URL = "https://unsloth.ai"
+DOCS_URL = "https://unsloth.ai/docs"
+SOURCE_URL = "https://github.com/unslothai/unsloth"
+LICENSE_URL = "https://github.com/unslothai/unsloth#license"
+AGPL_URL = "https://www.gnu.org/licenses/agpl-3.0.html"
+APACHE_URL = "https://www.apache.org/licenses/LICENSE-2.0"
+# ONE literal, byte-identical to PHRASE in unsloth_labext/src/branding.ts
+PHRASE = (
+ "Unsloth Docker Studio and JupyterLab image. Built by the Unsloth team. "
+ "Licensed under Apache 2.0 and the GNU AGPLv3. "
+ "Source: https://github.com/unslothai/unsloth Website: https://unsloth.ai"
+)
+
+THEME_NAME = "Unsloth Dark"
+LABEXT_NAME = "unsloth-jupyterlab"
+ABOUT_PLUGIN_ID = "unsloth-jupyterlab:about"
+SPLASH_PLUGIN_ID = "unsloth-jupyterlab:splash"
+LOGO_DATA_URI_PREFIX = "data:image/png;base64,iVBOR"
+
+
+def resolve_paths(
+ venv_share = None,
+ jupyter_server_dir = None,
+ config_dirs = None,
+):
+ """Installed locations of every checked branding asset; tests pass explicit roots."""
+ if venv_share is None:
+ venv_share = os.path.join(sys.prefix, "share", "jupyter")
+ if jupyter_server_dir is None:
+ import jupyter_server
+ jupyter_server_dir = os.path.dirname(jupyter_server.__file__)
+ labext_dir = os.path.join(venv_share, "labextensions", LABEXT_NAME)
+
+ if config_dirs is None:
+ try:
+ from jupyter_core.paths import jupyter_config_path
+ config_dirs = jupyter_config_path()
+ except Exception:
+ config_dirs = []
+ page_configs = [os.path.join(venv_share, "lab", "settings", "page_config.json")]
+ page_configs += [os.path.join(d, "labconfig", "page_config.json") for d in config_dirs]
+
+ return {
+ "license": os.path.join(venv_share, "UNSLOTH_LICENSE.AGPL-3.0"),
+ "login": os.path.join(jupyter_server_dir, "templates", "login.html"),
+ "overrides": os.path.join(venv_share, "lab", "settings", "overrides.json"),
+ "labext_dir": labext_dir,
+ "labext_pkg": os.path.join(labext_dir, "package.json"),
+ "labext_static": os.path.join(labext_dir, "static"),
+ "favicon": os.path.join(jupyter_server_dir, "static", "favicons", "favicon.ico"),
+ "logo": os.path.join(jupyter_server_dir, "static", "logo", "logo.png"),
+ "page_configs": page_configs,
+ }
+
+
+def _read(path):
+ try:
+ with open(path, encoding = "utf-8", errors = "replace") as f:
+ return f.read()
+ except OSError:
+ return None
+
+
+def _nonempty_file(path):
+ try:
+ return os.path.getsize(path) > 0
+ except OSError:
+ return False
+
+
+def _bundle_text(static_dir):
+ """Every built .js chunk: the production build minifies only identifiers, so the
+ attribution literals survive verbatim in one of them."""
+ if not os.path.isdir(static_dir):
+ return ""
+ parts = []
+ for name in sorted(os.listdir(static_dir)):
+ if name.endswith(".js"):
+ text = _read(os.path.join(static_dir, name))
+ if text:
+ parts.append(text)
+ return "\n".join(parts)
+
+
+def verify_branding(paths = None):
+ if paths is None:
+ paths = resolve_paths()
+ problems = []
+
+ license_text = _read(paths["license"])
+ if license_text is None:
+ problems.append("missing AGPLv3 license file: " + paths["license"])
+ elif "GNU AFFERO GENERAL PUBLIC LICENSE" not in license_text or "Version 3" not in license_text:
+ problems.append("AGPLv3 license file is not the GNU AGPL v3 text: " + paths["license"])
+
+ login = _read(paths["login"])
+ if login is None:
+ problems.append("missing branded login page: " + paths["login"])
+ else:
+ for marker in (SHORT_LABEL, COPYRIGHT, SOURCE_URL, "AGPLv3"):
+ if marker not in login:
+ problems.append("login page missing attribution marker: " + marker)
+
+ overrides = _read(paths["overrides"])
+ if not overrides or THEME_NAME not in overrides:
+ problems.append("overrides.json missing the '" + THEME_NAME + "' theme")
+
+ pkg = _read(paths["labext_pkg"])
+ if pkg is None:
+ problems.append("missing labextension: " + paths["labext_pkg"])
+ else:
+ try:
+ if json.loads(pkg).get("name") != LABEXT_NAME:
+ problems.append("labextension package.json name is not " + LABEXT_NAME)
+ except ValueError:
+ problems.append("labextension package.json is not valid JSON")
+
+ bundle = _bundle_text(paths["labext_static"])
+ if not bundle:
+ problems.append("missing built labextension bundle: " + paths["labext_static"])
+ else:
+ for marker in (
+ PHRASE,
+ SHORT_LABEL,
+ COPYRIGHT,
+ AGPL_URL,
+ ABOUT_PLUGIN_ID,
+ SPLASH_PLUGIN_ID,
+ LOGO_DATA_URI_PREFIX,
+ ):
+ if marker not in bundle:
+ problems.append("labextension bundle missing: " + marker)
+
+ if not _nonempty_file(paths["favicon"]):
+ problems.append("missing or empty favicon: " + paths["favicon"])
+ if not _nonempty_file(paths["logo"]):
+ problems.append("missing or empty logo: " + paths["logo"])
+
+ # disabledExtensions leaves the bundle on disk but strips it at load
+ for pc_path in paths.get("page_configs", []):
+ text = _read(pc_path)
+ if not text:
+ continue
+ try:
+ disabled = json.loads(text).get("disabledExtensions", {})
+ except ValueError:
+ problems.append("page_config.json is not valid JSON: " + pc_path)
+ continue
+ if isinstance(disabled, dict):
+ disabled_ids = [k for k, v in disabled.items() if v]
+ elif isinstance(disabled, (list, tuple)):
+ disabled_ids = list(disabled)
+ else:
+ disabled_ids = []
+ for ident in disabled_ids:
+ if not isinstance(ident, str):
+ continue
+ if ident == LABEXT_NAME or ident.startswith(LABEXT_NAME + ":"):
+ problems.append(
+ "page_config.json disables Unsloth attribution '" + ident + "': " + pc_path
+ )
+
+ return problems
+
+
+def banner(problems):
+ lines = [
+ "",
+ "=" * 72,
+ "ERROR: Unsloth Docker Studio attribution / license integrity check failed.",
+ "",
+ "This image is built by Unsloth and ships under the GNU AGPLv3. It will not",
+ "start because required attribution or license assets are missing or altered:",
+ "",
+ ]
+ for p in problems:
+ lines.append(" - " + p)
+ lines += [
+ "",
+ SHORT_LABEL + ". " + COPYRIGHT + ".",
+ "Website: " + WEBSITE_URL,
+ "Source: " + SOURCE_URL,
+ "License: GNU AGPLv3 (" + AGPL_URL + ")",
+ "=" * 72,
+ "",
+ ]
+ return "\n".join(lines)
+
+
+def _jupyter_server_extension_points():
+ return [{"module": "unsloth_branding"}]
+
+
+def _load_jupyter_server_extension(serverapp):
+ problems = verify_branding()
+ if not problems:
+ return
+ msg = banner(problems)
+ print(msg, file = sys.stderr, flush = True)
+ try:
+ serverapp.log.critical(msg)
+ except Exception:
+ pass
+ # studio_launch.sh refuses the container first; this backstops a direct run
+ try:
+ serverapp.exit(1)
+ except Exception:
+ pass
+ raise SystemExit(1)
+
+
+def main(argv = None):
+ import argparse
+
+ parser = argparse.ArgumentParser(description = "Unsloth branding integrity check")
+ parser.add_argument("--verify", action = "store_true", help = "verify and exit nonzero on failure")
+ parser.add_argument("--venv-share", default = None)
+ parser.add_argument("--jupyter-server-dir", default = None)
+ args = parser.parse_args(argv)
+
+ paths = resolve_paths(args.venv_share, args.jupyter_server_dir)
+ problems = verify_branding(paths)
+ if problems:
+ print(banner(problems), file = sys.stderr, flush = True)
+ return 1
+ print("Unsloth branding integrity check passed (" + PRODUCT + ", AGPLv3).")
+ return 0
+
+
+if __name__ == "__main__":
+ sys.exit(main())
diff --git a/docker/jupyter/unsloth_labext/.gitignore b/docker/jupyter/unsloth_labext/.gitignore
new file mode 100644
index 00000000000..a51e4ca6ca1
--- /dev/null
+++ b/docker/jupyter/unsloth_labext/.gitignore
@@ -0,0 +1,7 @@
+node_modules/
+lib/
+*.tsbuildinfo
+unsloth-jupyterlab/
+.yarn/
+.pnp.*
+yarn.lock
diff --git a/docker/jupyter/unsloth_labext/.yarnrc.yml b/docker/jupyter/unsloth_labext/.yarnrc.yml
new file mode 100644
index 00000000000..3186f3f0795
--- /dev/null
+++ b/docker/jupyter/unsloth_labext/.yarnrc.yml
@@ -0,0 +1 @@
+nodeLinker: node-modules
diff --git a/docker/jupyter/unsloth_labext/package.json b/docker/jupyter/unsloth_labext/package.json
new file mode 100644
index 00000000000..80284ed2bb1
--- /dev/null
+++ b/docker/jupyter/unsloth_labext/package.json
@@ -0,0 +1,54 @@
+{
+ "name": "unsloth-jupyterlab",
+ "version": "0.1.0",
+ "description": "Unsloth Dark (Monokai) theme + Colab-style cell navigation for JupyterLab.",
+ "keywords": [
+ "jupyter",
+ "jupyterlab",
+ "jupyterlab-extension",
+ "theme"
+ ],
+ "license": "AGPL-3.0-only",
+ "author": "Unsloth AI",
+ "private": true,
+ "main": "lib/index.js",
+ "types": "lib/index.d.ts",
+ "style": "style/index.css",
+ "files": [
+ "lib/**/*.{d.ts,js,js.map}",
+ "style/**/*.{css,js,eot,gif,html,jpg,json,png,svg,woff2,ttf}",
+ "schema/*.json"
+ ],
+ "scripts": {
+ "build": "jlpm build:lib && jlpm build:labextension:dev",
+ "build:prod": "jlpm clean && jlpm build:lib:prod && jlpm build:labextension",
+ "build:lib": "tsc --sourceMap",
+ "build:lib:prod": "tsc",
+ "build:labextension": "jupyter labextension build .",
+ "build:labextension:dev": "jupyter labextension build --development True .",
+ "clean": "rimraf lib tsconfig.tsbuildinfo unsloth-jupyterlab/labextension"
+ },
+ "dependencies": {
+ "@codemirror/state": "^6.0.0",
+ "@codemirror/view": "^6.0.0",
+ "@jupyterlab/application": "^4.5.0",
+ "@jupyterlab/apputils": "^4.5.0",
+ "@jupyterlab/cells": "^4.5.0",
+ "@jupyterlab/codemirror": "^4.5.0",
+ "@jupyterlab/mainmenu": "^4.5.0",
+ "@jupyterlab/notebook": "^4.5.0",
+ "@jupyterlab/theme-dark-extension": "^4.5.0",
+ "@lumino/disposable": "^2.0.0",
+ "@lumino/widgets": "^2.0.0"
+ },
+ "devDependencies": {
+ "@jupyterlab/builder": "^4.5.0",
+ "rimraf": "^5.0.0",
+ "typescript": "~5.5.0"
+ },
+ "jupyterlab": {
+ "extension": true,
+ "themePath": "style/index.css",
+ "outputDir": "unsloth-jupyterlab/labextension"
+ }
+}
diff --git a/docker/jupyter/unsloth_labext/src/about.ts b/docker/jupyter/unsloth_labext/src/about.ts
new file mode 100644
index 00000000000..17b50256474
--- /dev/null
+++ b/docker/jupyter/unsloth_labext/src/about.ts
@@ -0,0 +1,91 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-Present the Unsloth team. See /studio/LICENSE.AGPL-3.0
+//
+// "About Unsloth Docker Studio": the AGPLv3 license, copyright and source links.
+
+import {
+ JupyterFrontEnd,
+ JupyterFrontEndPlugin
+} from '@jupyterlab/application';
+import { Dialog, ICommandPalette, showDialog } from '@jupyterlab/apputils';
+import { IMainMenu } from '@jupyterlab/mainmenu';
+import { Widget } from '@lumino/widgets';
+import { UNSLOTH_LOGO_DATA_URI } from './logo';
+import {
+ AGPL_NOTICE,
+ AGPL_URL,
+ APACHE_URL,
+ COPYRIGHT,
+ DOCS_URL,
+ LICENSE_URL,
+ PHRASE,
+ PRODUCT,
+ SHORT_LABEL,
+ SOURCE_URL,
+ WEBSITE_URL
+} from './branding';
+
+const COMMAND_ID = 'unsloth:about';
+
+/**
+ * Trusted branding.ts constants only, so innerHTML has no injection surface, and
+ * PHRASE is stamped as a data attribute so it is bundled verbatim for the guard.
+ */
+function aboutBody(): Widget {
+ const body = new Widget();
+ const el = body.node;
+ el.style.textAlign = 'center';
+ el.style.padding = '4px 10px 10px';
+ el.style.maxWidth = '430px';
+ el.setAttribute('data-unsloth-attribution', PHRASE);
+ el.innerHTML = `
+ <img src="${UNSLOTH_LOGO_DATA_URI}" alt="Unsloth"
+ style="height:64px;width:auto;margin:2px auto 10px;display:block;" />
+ <div style="font-size:16px;font-weight:700;margin-bottom:2px;">${PRODUCT}</div>
+ <div style="opacity:0.8;margin-bottom:10px;">${SHORT_LABEL}</div>
+ <div style="font-size:13px;line-height:1.55;margin-bottom:10px;">${AGPL_NOTICE}.</div>
+ <div style="display:inline-block;text-align:left;font-size:13px;line-height:1.7;">
+ <div>Source: <a href="${SOURCE_URL}" target="_blank" rel="noopener">${SOURCE_URL}</a></div>
+ <div>Website: <a href="${WEBSITE_URL}" target="_blank" rel="noopener">${WEBSITE_URL}</a></div>
+ <div>Unsloth Reference: <a href="${DOCS_URL}" target="_blank" rel="noopener">${DOCS_URL}</a></div>
+ <div style="margin-top:8px;font-weight:600;">Licenses</div>
+ <div style="margin-left:12px;">
+ <div>Unsloth Studio: <a href="${AGPL_URL}" target="_blank" rel="noopener">AGPLv3</a></div>
+ <div>Unsloth Core: <a href="${APACHE_URL}" target="_blank" rel="noopener">Apache 2.0</a></div>
+ <div>Unsloth license: <a href="${LICENSE_URL}" target="_blank" rel="noopener">${LICENSE_URL}</a></div>
+ </div>
+ </div>
+ <div style="font-size:12px;opacity:0.7;margin-top:12px;">${COPYRIGHT}</div>
+ `;
+ return body;
+}
+
+const aboutPlugin: JupyterFrontEndPlugin<void> = {
+ id: 'unsloth-jupyterlab:about',
+ description: 'About Unsloth Docker Studio (AGPLv3 attribution).',
+ autoStart: true,
+ optional: [IMainMenu, ICommandPalette],
+ activate: (
+ app: JupyterFrontEnd,
+ mainMenu: IMainMenu | null,
+ palette: ICommandPalette | null
+ ): void => {
+ app.commands.addCommand(COMMAND_ID, {
+ label: 'About ' + PRODUCT,
+ execute: () =>
+ showDialog({
+ title: 'About ' + PRODUCT,
+ body: aboutBody(),
+ buttons: [Dialog.okButton({ label: 'Close' })]
+ })
+ });
+ if (mainMenu) {
+ mainMenu.helpMenu.addGroup([{ command: COMMAND_ID }], 20);
+ }
+ if (palette) {
+ palette.addItem({ command: COMMAND_ID, category: 'Help' });
+ }
+ }
+};
+
+export default aboutPlugin;
diff --git a/docker/jupyter/unsloth_labext/src/branding.ts b/docker/jupyter/unsloth_labext/src/branding.ts
new file mode 100644
index 00000000000..98d811e9f97
--- /dev/null
+++ b/docker/jupyter/unsloth_labext/src/branding.ts
@@ -0,0 +1,22 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-Present the Unsloth team. See /studio/LICENSE.AGPL-3.0
+//
+// Canonical attribution strings, mirrored from unsloth_branding.py, which greps the
+// built bundle for them. Plain text only, never encoded.
+
+export const PRODUCT = 'Unsloth Docker Studio';
+export const SHORT_LABEL = 'Built by the Unsloth team';
+export const SPLASH_LABEL = 'Loading Unsloth Docker';
+export const COPYRIGHT = 'Copyright 2026-Present the Unsloth team';
+export const AGPL_NOTICE = 'Licensed under Apache 2.0 and the GNU AGPLv3';
+export const WEBSITE_URL = 'https://unsloth.ai';
+export const DOCS_URL = 'https://unsloth.ai/docs';
+export const SOURCE_URL = 'https://github.com/unslothai/unsloth';
+export const LICENSE_URL = 'https://github.com/unslothai/unsloth#license';
+export const AGPL_URL = 'https://www.gnu.org/licenses/agpl-3.0.html';
+export const APACHE_URL = 'https://www.apache.org/licenses/LICENSE-2.0';
+
+// Must equal PHRASE in unsloth_branding.py, which greps the built bundle for it.
+// ONE literal, not a concatenation, so webpack keeps it contiguous.
+export const PHRASE =
+ 'Unsloth Docker Studio and JupyterLab image. Built by the Unsloth team. Licensed under Apache 2.0 and the GNU AGPLv3. Source: https://github.com/unslothai/unsloth Website: https://unsloth.ai';
diff --git a/docker/jupyter/unsloth_labext/src/cellNav.ts b/docker/jupyter/unsloth_labext/src/cellNav.ts
new file mode 100644
index 00000000000..de8ba36e6c3
--- /dev/null
+++ b/docker/jupyter/unsloth_labext/src/cellNav.ts
@@ -0,0 +1,120 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-Present the Unsloth team. See /studio/LICENSE.AGPL-3.0
+
+import {
+ JupyterFrontEnd,
+ JupyterFrontEndPlugin
+} from '@jupyterlab/application';
+import { CodeMirrorEditor } from '@jupyterlab/codemirror';
+import { INotebookTracker } from '@jupyterlab/notebook';
+
+/**
+ * Colab-style cell navigation: at a cell boundary, move to the next cell and align
+ * its TOP to the viewport. JupyterLab centers tall cells instead, dropping the view
+ * mid-output, and no setting changes that.
+ */
+const cellNavPlugin: JupyterFrontEndPlugin<void> = {
+ id: 'unsloth-jupyterlab:cell-nav',
+ description:
+ 'ArrowDown/ArrowUp move to the TOP of the next/previous cell (command + edit mode).',
+ autoStart: true,
+ requires: [INotebookTracker],
+ activate: (app: JupyterFrontEnd, tracker: INotebookTracker): void => {
+ const handler = (event: KeyboardEvent): void => {
+ if (event.key !== 'ArrowDown' && event.key !== 'ArrowUp') {
+ return;
+ }
+ if (event.ctrlKey || event.metaKey || event.altKey || event.shiftKey) {
+ return;
+ }
+ const panel = tracker.currentWidget;
+ if (!panel || !panel.isVisible) {
+ return;
+ }
+ if (!panel.node.contains(event.target as Node)) {
+ return;
+ }
+ const targetEl = event.target as HTMLElement | null;
+ if (targetEl) {
+ if (targetEl.closest('.jp-OutputArea')) {
+ return;
+ }
+ const tag = targetEl.tagName;
+ if (tag === 'INPUT' || tag === 'TEXTAREA' || tag === 'SELECT') {
+ return;
+ }
+ }
+ const notebook = panel.content;
+ const direction = event.key === 'ArrowDown' ? 1 : -1;
+ const editing = notebook.mode === 'edit';
+ if (editing) {
+ const editor = notebook.activeCell?.editor;
+ if (!editor) {
+ return;
+ }
+ if (
+ document.querySelector(
+ '.jp-Completer:not(.lm-mod-hidden), .cm-tooltip-autocomplete'
+ )
+ ) {
+ return;
+ }
+ // `lineCount` counts LOGICAL lines, but JupyterLab wraps markdown and raw
+ // editors by default, so one logical line can own several visual rows and a
+ // logical test makes them unreachable: every arrow leaves the cell.
+ const view = editor instanceof CodeMirrorEditor ? editor.editor : null;
+ if (view) {
+ const range = view.state.selection.main;
+ const moved = view.moveVertically(range, direction === 1);
+ const from = view.coordsAtPos(range.head);
+ const to =
+ moved.head === range.head ? from : view.coordsAtPos(moved.head);
+ // moveVertically returns an unchanged head only at the document edge
+ if (from && to && Math.abs(to.top - from.top) > 1) {
+ return;
+ }
+ } else {
+ const line = editor.getCursorPosition().line;
+ if (direction === 1 && line !== editor.lineCount - 1) {
+ return;
+ }
+ if (direction === -1 && line !== 0) {
+ return;
+ }
+ }
+ }
+ const target = notebook.activeCellIndex + direction;
+ if (target < 0 || target >= notebook.widgets.length) {
+ return;
+ }
+ // stop Lumino re-triggering the centering scroll we replace
+ event.preventDefault();
+ event.stopPropagation();
+ notebook.activeCellIndex = target;
+ const cell = notebook.activeCell;
+ const targetEditor = cell?.editor;
+ if (editing && cell && targetEditor) {
+ notebook.mode = 'edit';
+ const lastLine = Math.max(0, targetEditor.lineCount - 1);
+ targetEditor.setCursorPosition({
+ line: direction === 1 ? 0 : lastLine,
+ column: 0
+ });
+ }
+ if (cell) {
+ const node = cell.node;
+ // defer, so this wins over JupyterLab's own centering scroll
+ requestAnimationFrame(() => {
+ try {
+ node.scrollIntoView({ block: 'start' });
+ } catch {
+ /* no-op */
+ }
+ });
+ }
+ };
+ document.addEventListener('keydown', handler, true);
+ }
+};
+
+export default cellNavPlugin;
diff --git a/docker/jupyter/unsloth_labext/src/colabTitle.ts b/docker/jupyter/unsloth_labext/src/colabTitle.ts
new file mode 100644
index 00000000000..986ad9835f1
--- /dev/null
+++ b/docker/jupyter/unsloth_labext/src/colabTitle.ts
@@ -0,0 +1,147 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-Present the Unsloth team. See /studio/LICENSE.AGPL-3.0
+
+import {
+ JupyterFrontEnd,
+ JupyterFrontEndPlugin
+} from '@jupyterlab/application';
+import { INotebookTracker, NotebookPanel } from '@jupyterlab/notebook';
+import { Cell } from '@jupyterlab/cells';
+
+/**
+ * Colab "#@title" form cells: a clickable title bar that hides the input via a CSS
+ * class, NOT source_hidden, so the notebook metadata is never mutated.
+ */
+
+const TITLE_RE = /^\s*#\s*@title\b[ \t]*(.*)$/;
+const STYLE_ID = 'unsloth-colab-title-style';
+
+function injectStyle(): void {
+ if (document.getElementById(STYLE_ID)) {
+ return;
+ }
+ const style = document.createElement('style');
+ style.id = STYLE_ID;
+ style.textContent = `
+.unsloth-title-bar {
+ display: flex;
+ align-items: center;
+ gap: 8px;
+ cursor: pointer;
+ padding: 4px 8px;
+ /* Indent past the cell collapser + prompt gutter so the title aligns with the
+ cell's input/output content column instead of the far-left edge. */
+ margin: 2px 0 2px var(--jp-cell-prompt-width, 64px);
+ user-select: none;
+ border-radius: 4px;
+ /* Heading-2-sized so a #@title form reads like a section heading (matches the
+ rendered-markdown h2 scale, --jp-content-font-size4); the caret inherits
+ this size so it grows too. */
+ font-size: var(--jp-content-font-size4, 1.728em);
+ color: var(--jp-content-font-color1, inherit);
+}
+.unsloth-title-bar:hover {
+ background: var(--jp-layout-color2, rgba(128, 128, 128, 0.12));
+}
+.unsloth-title-caret {
+ display: inline-block;
+ width: 1em;
+ line-height: 1;
+ opacity: 0.8;
+ transition: transform 0.12s ease;
+}
+.unsloth-title-bar.unsloth-collapsed .unsloth-title-caret {
+ transform: rotate(-90deg);
+}
+.unsloth-title-text {
+ font-weight: 700;
+ line-height: 1.25;
+}
+.jp-Cell.unsloth-code-collapsed > .jp-Cell-inputWrapper {
+ display: none;
+}
+`;
+ document.head.appendChild(style);
+}
+
+function firstLineOf(cell: Cell): string {
+ try {
+ const raw = cell.model.toJSON().source as string | string[];
+ const text = Array.isArray(raw) ? raw.join('') : String(raw || '');
+ return text.split('\n', 1)[0] || '';
+ } catch {
+ return '';
+ }
+}
+
+function applyTitle(cell: Cell): void {
+ let node: HTMLElement;
+ try {
+ node = cell.node;
+ } catch {
+ return;
+ }
+ if (cell.model?.type !== 'code') {
+ return;
+ }
+ const match = TITLE_RE.exec(firstLineOf(cell));
+ let bar = node.querySelector(':scope > .unsloth-title-bar') as HTMLElement | null;
+ if (!match) {
+ if (bar) {
+ bar.remove();
+ }
+ node.classList.remove('unsloth-titled', 'unsloth-code-collapsed');
+ return;
+ }
+ const title =
+ (match[1] || '').replace(/\s*\{[^}]*\}\s*$/, '').trim() || 'Title';
+ if (!bar) {
+ const barEl = document.createElement('div');
+ barEl.className = 'unsloth-title-bar unsloth-collapsed';
+ const caret = document.createElement('span');
+ caret.className = 'unsloth-title-caret';
+ caret.textContent = '▾';
+ const text = document.createElement('span');
+ text.className = 'unsloth-title-text';
+ barEl.appendChild(caret);
+ barEl.appendChild(text);
+ barEl.addEventListener('click', () => {
+ const collapsed = node.classList.toggle('unsloth-code-collapsed');
+ barEl.classList.toggle('unsloth-collapsed', collapsed);
+ });
+ node.insertBefore(barEl, node.firstChild);
+ node.classList.add('unsloth-code-collapsed');
+ bar = barEl;
+ }
+ const label = bar.querySelector('.unsloth-title-text') as HTMLElement | null;
+ if (label) {
+ label.textContent = title;
+ }
+ node.classList.add('unsloth-titled');
+}
+
+const colabTitlePlugin: JupyterFrontEndPlugin<void> = {
+ id: 'unsloth-jupyterlab:colab-title',
+ description: 'Render Colab #@title code cells as collapsed, titled forms.',
+ autoStart: true,
+ requires: [INotebookTracker],
+ activate: (app: JupyterFrontEnd, tracker: INotebookTracker): void => {
+ injectStyle();
+ const decorate = (panel: NotebookPanel): void => {
+ const scan = (): void => {
+ panel.content.widgets.forEach(applyTitle);
+ };
+ panel.revealed.then(scan).catch(() => undefined);
+ // applyTitle never re-collapses an existing bar, so manual expansions survive
+ const model = panel.content.model;
+ if (model) {
+ model.cells.changed.connect(() => window.setTimeout(scan, 0));
+ }
+ panel.content.activeCellChanged.connect(() => window.setTimeout(scan, 0));
+ };
+ tracker.widgetAdded.connect((_, panel) => decorate(panel));
+ tracker.forEach(decorate);
+ }
+};
+
+export default colabTitlePlugin;
diff --git a/docker/jupyter/unsloth_labext/src/index.ts b/docker/jupyter/unsloth_labext/src/index.ts
new file mode 100644
index 00000000000..0f2cf931f02
--- /dev/null
+++ b/docker/jupyter/unsloth_labext/src/index.ts
@@ -0,0 +1,72 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-Present the Unsloth team. See /studio/LICENSE.AGPL-3.0
+
+import {
+ ILabShell,
+ JupyterFrontEnd,
+ JupyterFrontEndPlugin
+} from '@jupyterlab/application';
+import { IThemeManager } from '@jupyterlab/apputils';
+import { Widget } from '@lumino/widgets';
+import { UNSLOTH_LOGO_DATA_URI } from './logo';
+import aboutPlugin from './about';
+import cellNavPlugin from './cellNav';
+import colabTitlePlugin from './colabTitle';
+import outputSelectPlugin from './outputSelect';
+import splashPlugin from './splash';
+import uiChromePlugin from './uiChrome';
+
+/** A NAMED theme, so Settings > Theme and the adaptive light/dark switch see it. */
+const themePlugin: JupyterFrontEndPlugin<void> = {
+ id: 'unsloth-jupyterlab:theme',
+ description: 'Unsloth Dark (Monokai) theme.',
+ autoStart: true,
+ requires: [IThemeManager],
+ activate: (app: JupyterFrontEnd, manager: IThemeManager): void => {
+ const style = 'unsloth-jupyterlab/index.css';
+ manager.register({
+ name: 'Unsloth Dark',
+ isLight: false,
+ themeScrollbars: true,
+ load: () => manager.loadCSS(style),
+ unload: () => Promise.resolve(undefined)
+ });
+ }
+};
+
+/**
+ * The stock logo plugin is disabled + locked at build, so this is the only logo
+ * widget. An <img> with inline styles, not a LabIcon, so it shows in any theme.
+ */
+const logoPlugin: JupyterFrontEndPlugin<void> = {
+ id: 'unsloth-jupyterlab:logo',
+ description: 'Replace the top-left Jupyter logo with the Unsloth logo.',
+ autoStart: true,
+ requires: [ILabShell],
+ activate: (app: JupyterFrontEnd, shell: ILabShell): void => {
+ const logo = new Widget();
+ const img = document.createElement('img');
+ img.src = UNSLOTH_LOGO_DATA_URI;
+ img.alt = 'Unsloth';
+ img.style.height = '24px';
+ img.style.width = 'auto';
+ img.style.margin = '1px 6px 1px 8px';
+ img.style.display = 'block';
+ logo.node.appendChild(img);
+ logo.node.style.display = 'flex';
+ logo.node.style.alignItems = 'center';
+ logo.id = 'jp-MainLogo';
+ shell.add(logo, 'top', { rank: 0 });
+ }
+};
+
+export default [
+ themePlugin,
+ cellNavPlugin,
+ logoPlugin,
+ colabTitlePlugin,
+ outputSelectPlugin,
+ uiChromePlugin,
+ aboutPlugin,
+ splashPlugin
+];
diff --git a/docker/jupyter/unsloth_labext/src/logo.ts b/docker/jupyter/unsloth_labext/src/logo.ts
new file mode 100644
index 00000000000..e73d9a46358
--- /dev/null
+++ b/docker/jupyter/unsloth_labext/src/logo.ts
@@ -0,0 +1,6 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-Present the Unsloth team. See /studio/LICENSE.AGPL-3.0
+
+// Auto-generated: the Unsloth logo as a data URI, so the plugin has no runtime asset.
+export const UNSLOTH_LOGO_DATA_URI =
+ "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAGQAAABhCAYAAAAgLwTnAAAKMWlDQ1BJQ0MgUHJvZmlsZQAAeJydlndUU9kWh8+9N71QkhCKlNBraFICSA29SJEuKjEJEErAkAAiNkRUcERRkaYIMijggKNDkbEiioUBUbHrBBlE1HFwFBuWSWStGd+8ee/Nm98f935rn73P3Wfvfda6AJD8gwXCTFgJgAyhWBTh58WIjYtnYAcBDPAAA2wA4HCzs0IW+EYCmQJ82IxsmRP4F726DiD5+yrTP4zBAP+flLlZIjEAUJiM5/L42VwZF8k4PVecJbdPyZi2NE3OMErOIlmCMlaTc/IsW3z2mWUPOfMyhDwZy3PO4mXw5Nwn4405Er6MkWAZF+cI+LkyviZjg3RJhkDGb+SxGXxONgAoktwu5nNTZGwtY5IoMoIt43kA4EjJX/DSL1jMzxPLD8XOzFouEiSniBkmXFOGjZMTi+HPz03ni8XMMA43jSPiMdiZGVkc4XIAZs/8WRR5bRmyIjvYODk4MG0tbb4o1H9d/JuS93aWXoR/7hlEH/jD9ld+mQ0AsKZltdn6h21pFQBd6wFQu/2HzWAvAIqyvnUOfXEeunxeUsTiLGcrq9zcXEsBn2spL+jv+p8Of0NffM9Svt3v5WF485M4knQxQ143bmZ6pkTEyM7icPkM5p+H+B8H/nUeFhH8JL6IL5RFRMumTCBMlrVbyBOIBZlChkD4n5r4D8P+pNm5lona+BHQllgCpSEaQH4eACgqESAJe2Qr0O99C8ZHA/nNi9GZmJ37z4L+fVe4TP7IFiR/jmNHRDK4ElHO7Jr8WgI0IABFQAPqQBvoAxPABLbAEbgAD+ADAkEoiARxYDHgghSQAUQgFxSAtaAYlIKtYCeoBnWgETSDNnAYdIFj4DQ4By6By2AE3AFSMA6egCnwCsxAEISFyBAVUod0IEPIHLKFWJAb5AMFQxFQHJQIJUNCSAIVQOugUqgcqobqoWboW+godBq6AA1Dt6BRaBL6FXoHIzAJpsFasBFsBbNgTzgIjoQXwcnwMjgfLoK3wJVwA3wQ7oRPw5fgEVgKP4GnEYAQETqiizARFsJGQpF4JAkRIauQEqQCaUDakB6kH7mKSJGnyFsUBkVFMVBMlAvKHxWF4qKWoVahNqOqUQdQnag+1FXUKGoK9RFNRmuizdHO6AB0LDoZnYsuRlegm9Ad6LPoEfQ4+hUGg6FjjDGOGH9MHCYVswKzGbMb0445hRnGjGGmsVisOtYc64oNxXKwYmwxtgp7EHsSewU7jn2DI+J0cLY4X1w8TogrxFXgWnAncFdwE7gZvBLeEO+MD8Xz8MvxZfhGfA9+CD+OnyEoE4wJroRIQiphLaGS0EY4S7hLeEEkEvWITsRwooC4hlhJPEQ8TxwlviVRSGYkNimBJCFtIe0nnSLdIr0gk8lGZA9yPFlM3kJuJp8h3ye/UaAqWCoEKPAUVivUKHQqXFF4pohXNFT0VFysmK9YoXhEcUjxqRJeyUiJrcRRWqVUo3RU6YbStDJV2UY5VDlDebNyi/IF5UcULMWI4kPhUYoo+yhnKGNUhKpPZVO51HXURupZ6jgNQzOmBdBSaaW0b2iDtCkVioqdSrRKnkqNynEVKR2hG9ED6On0Mvph+nX6O1UtVU9Vvuom1TbVK6qv1eaoeajx1UrU2tVG1N6pM9R91NPUt6l3qd/TQGmYaYRr5Grs0Tir8XQObY7LHO6ckjmH59zWhDXNNCM0V2ju0xzQnNbS1vLTytKq0jqj9VSbru2hnaq9Q/uE9qQOVcdNR6CzQ+ekzmOGCsOTkc6oZPQxpnQ1df11Jbr1uoO6M3rGelF6hXrtevf0Cfos/ST9Hfq9+lMGOgYhBgUGrQa3DfGGLMMUw12G/YavjYyNYow2GHUZPTJWMw4wzjduNb5rQjZxN1lm0mByzRRjyjJNM91tetkMNrM3SzGrMRsyh80dzAXmu82HLdAWThZCiwaLG0wS05OZw2xljlrSLYMtCy27LJ9ZGVjFW22z6rf6aG1vnW7daH3HhmITaFNo02Pzq62ZLde2xvbaXPJc37mr53bPfW5nbse322N3055qH2K/wb7X/oODo4PIoc1h0tHAMdGx1vEGi8YKY21mnXdCO3k5rXY65vTW2cFZ7HzY+RcXpkuaS4vLo3nG8/jzGueNueq5clzrXaVuDLdEt71uUnddd457g/sDD30PnkeTx4SnqWeq50HPZ17WXiKvDq/XbGf2SvYpb8Tbz7vEe9CH4hPlU+1z31fPN9m31XfKz95vhd8pf7R/kP82/xsBWgHcgOaAqUDHwJWBfUGkoAVB1UEPgs2CRcE9IXBIYMj2kLvzDecL53eFgtCA0O2h98KMw5aFfR+OCQ8Lrwl/GGETURDRv4C6YMmClgWvIr0iyyLvRJlESaJ6oxWjE6Kbo1/HeMeUx0hjrWJXxl6K04gTxHXHY+Oj45vipxf6LNy5cDzBPqE44foi40V5iy4s1licvvj4EsUlnCVHEtGJMYktie85oZwGzvTSgKW1S6e4bO4u7hOeB28Hb5Lvyi/nTyS5JpUnPUp2Td6ePJninlKR8lTAFlQLnqf6p9alvk4LTduf9ik9Jr09A5eRmHFUSBGmCfsytTPzMoezzLOKs6TLnJftXDYlChI1ZUPZi7K7xTTZz9SAxESyXjKa45ZTk/MmNzr3SJ5ynjBvYLnZ8k3LJ/J9879egVrBXdFboFuwtmB0pefK+lXQqqWrelfrry5aPb7Gb82BtYS1aWt/KLQuLC98uS5mXU+RVtGaorH1futbixWKRcU3NrhsqNuI2ijYOLhp7qaqTR9LeCUXS61LK0rfb+ZuvviVzVeVX33akrRlsMyhbM9WzFbh1uvb3LcdKFcuzy8f2x6yvXMHY0fJjpc7l+y8UGFXUbeLsEuyS1oZXNldZVC1tep9dUr1SI1XTXutZu2m2te7ebuv7PHY01anVVda926vYO/Ner/6zgajhop9mH05+x42Rjf2f836urlJo6m06cN+4X7pgYgDfc2Ozc0tmi1lrXCrpHXyYMLBy994f9Pdxmyrb6e3lx4ChySHHn+b+O31w0GHe4+wjrR9Z/hdbQe1o6QT6lzeOdWV0iXtjusePhp4tLfHpafje8vv9x/TPVZzXOV42QnCiaITn07mn5w+lXXq6enk02O9S3rvnIk9c60vvG/wbNDZ8+d8z53p9+w/ed71/LELzheOXmRd7LrkcKlzwH6g4wf7HzoGHQY7hxyHui87Xe4Znjd84or7ldNXva+euxZw7dLI/JHh61HXb95IuCG9ybv56Fb6ree3c27P3FlzF3235J7SvYr7mvcbfjT9sV3qID0+6j068GDBgztj3LEnP2X/9H686CH5YcWEzkTzI9tHxyZ9Jy8/Xvh4/EnWk5mnxT8r/1z7zOTZd794/DIwFTs1/lz0/NOvm1+ov9j/0u5l73TY9P1XGa9mXpe8UX9z4C3rbf+7mHcTM7nvse8rP5h+6PkY9PHup4xPn34D94Tz+6TMXDkAAC1vSURBVHic1Z15gBTlmf8/VdX3PRczwHCIqCCCCgjihQY1SoyoURE12cQrRvHKiq5Zo25cNUFdzU9jsiasyXoCHuCBIhgUATmUS24BOWaAYY6evs+q9/dHdVV3z/RAz4gm+8W2q956662q59vP8T7v+9ZIE5e/RE+gCYEqNASgCoGW29YAhEAIoVeUQACy0HckQJL0LcksBxkJOVcuyzIKkiQjnWCxW08QmjYATRwnSXI9EjUCqkA4hUDSrwYCIWmItNBoE4gWTWj7NVXdrvg8O9vWbd3avGTN6tiufYnmT75AS6V79MzfBSz/0KtLhjQFQkJGUkYrsnyOIsujZEk+TZGkvqgCWZYRCoBOtMF1jgj9nwANgYA6DYGQQFgUUuEI3uGDqT5vbCgVjn4Wb2ha0/zp6k+jW3cvCS5dF0nuOfCPe/4SkP5RGoIQSJKEgny2LEk/sirKlRZJ6aXIMrKUO1Xo50Je+Ln/iogQCDTzW+j3ITS03H1qCIQmEIqE7HVhqalAFVo2ebB1bmjlpplNsxbMCy36IiZUrUeyOJL4TgkROZWQJSoVWbndKsm3WGSlxqLIKEjISJ2uI3L/FyK/rYGuKYWaIYRJgEAnQRPCJCT/Te5eBcJmxVJbAVZLJrL+q5faF6x8qu31RV9mGpt7JJMjge+MEDSBJMlDLZL0nxZFucwqK1gkGRkJRTJ0pxiiiAhMQRdrhVakHSY5BQR1TY5A0zSEBHKVF7nST6q1fU34w5UPtf1pztuZr/f3SDbfBN86IRoCCWm4IsmP2mT5IkuOCEWSkKWutKK0nzAEX6wVhWbqMMIvql+inqaB04albw3ZWGJzeOZH97T/ae67Wmu4RzLqCb41QjShAfgVSX7KKis/s0gKFllCMcjIESFRrp+g6NdvEKSR9xXiMCQUEZLTIBVNJ9g0gTliXHaUAbVk9rV8Fpkx7+exlxZ8Kb6D6OxbIUQTGpKQfmZV5L/YJEW2SDKKLOdC25xjp5iIQj+hi6bAT2D8+jGFLjoIWiBy91Hw6899q4AQWpEfMeoXBgJm20YdVUPyu1EG1ZFatvFPoV/95dbstr3fquc/goQI/dcqqLBI8rtWWT7NIilYJAk5pxUdiYAu/IQhoBLCKvQTapGp0kyHrXUqE8UEdNCSQiKKfhS5OkITWOprkNyOcPSp2ZOiz839uIfyPizkI9WQQCAJ6Yd2WTnoUJTT7LIFmyxjkWQsUt5ldxS8ViAAXYAdTEyOeDVHgPHJmtsaqtBy+1oXZRpZoaGSb0czvzVU8ppTbBYBSUJSZNSGZtTGFp932lWLKmbc859ywHukRFeEI6IhGaEhwX/ZJOWuQvOkSKXD2M5+Im+eOvcn8r9eVYiCCKprZ50VgoymkhEqqhB6NCdJqJpWEDJ3jtoQ+fspiVykYRncF6059GnwF/91fmb9zmSPBNgFvjEhqhDISAsssnyuVVaK/ERHdDRPeTORF75JQoF5MYgotPmFBAAEM0n2JyOk1Cw22YLf6sCuKAigNRUnmYqBYqHW6ccmK2SEmv9RFPiqspBVUfpWI3mc7aFfPndm4t3PNvRIiCXQ49RJLuNRbZHkj62yMkyR9AjK8BNGHdAFj+hgrgp+mSIXLRnRTsdfv+F3MkIloWZJqBlTO1vScZJqluO9NVzXfyT1Dh9DvNUc5QrgUmxYJZndiXZWBfexLnyAWQ3rsSlWKuwuMkLNa0e3pKag7mtFrvQF/E/dulaurZgYmzHvw57KshA90hABaJqolyVphVWW+xj9ic5+omOfokM0U0CEGSUhkJDIaBoxNU1bOkEkm0ICAlYHFTYXFVYHEhBR04z29+GCXoM5rbIfAavjsPe+oHkHly5/BU2S8Fjs3SejEKqG5HVhGVhHZPqrk6N/mDOr543p6JmGCPpaZXmlRZJ7S2WHsR172MV+wthvScdpTcdxW2z0tnsYW9uXfk4/g1wVDPFU08fhpcLmRJYkRM4/lEIoFKKhoYFYLEbv3r3p168fAOfVHM0TJ3yfX6yZi8tiAyhpXsuCIiOicbLbG/Hed/VMFJno/3vzG5FiUbp4oFLICb2PJPGFIsm1Hc3TYfNOFAo/71zTQmV3vJ2spnGCrxc/7nciF/YazEBXBd6c0ErfUF6Ue/bs4Y033mDOnDns2bOHgwcPEo/HzeNjxoxh4cKFeL1eLqo7jgdcfmJqBqdiRfANSJFlRDJNdstevPdOmSniqVTsL+/N7WlzllKpi0NAkSU+kJFqjYKOROTLiqMm0SGkRIIsGl/HgmSExmW9h3Jt/QjGVNR3eUfJZJLdu3fT0NBAMBjE6XTS0NDACy+8wIoVKw554ytXrmTTpk2MHTsWm2IhnIyQSkaxBXrjlBUymtpzYmQJkcqQ3daA975r5mgtodMTc5Ys60lT0iUrXi2/siTNk+DCwjJRkojSYazhqBVJZn8yQnM6zg9rj+Ouo8dyvLdXp+t99dVXLFiwgHfeeYcdO3bQ1NREONz9vFIgEOCNN97ge9/7nlm2qGUnT+xYzrzGLwGo81TnIrlv0BFXNeQqH5LH2RT8l8dOTK/+qqm7TUiXrXyt3LrTgWnGTsf+BOQ1oDDvlE+LayBJZIXGpnAzg92V/O74czmzakDRRXbt2sVTTz1lmp4jgdNOO425c+dSXV3d6diGcBPXrZ3LqsaNOD1V+O1uspra84tlVZT+vdBaw6taL39ojNbWvR9QuYRMAubAIYgoCmPzqW8hBCq68z2YirE3EeKGAaN46LjxOBWreYEVK1Zw//33s3Dhwm49QHdQXV3NJZdcwl133cXxxx9fdOylhvVMXTOHUCJElb8uN37TswhMZFSswwaS+njt88Hrp/+8O+eWQ0g/YCPgLW2eOvoJzfQXhpmySgrbo604FStPD7+A82qONhtvaGjg9ttv56233urOfX9jTJw4kccff7yImIOpGJNXvsbHjRvw+nrhVCy6v+sJhMA6bCCR/5p9TfT3b7xS7mnlhFjPCPAW5p30jptWkA/K55w0QVHuSUFmc6SZOoeH98ddW0TGM888Q79+/b5zMgDmzZvHsGHDuOmmm8yxm152N4vOvJ7bh51HJNJMOJNC7kYU2hHZXU24r5/4rG34oM4OsgvIZh+h9L+bBWJSx9xPYeJPMxJ0hck+9DKLJLMmtJ8T/XV8csZ19Hf6AYhEIpx++uncfvvtPX7YI4U///nP+Hw+lixZYpb9fvhEnjnlSpKxNkLpRM9IkSREJA6yXOH592v/WO5ph7pSQAj+szgbmzdDqgA117vWv/VsalZoZDWdjHXhA4yvHsg7Y6dgzT3UmjVr6N27N8uW9Sgq/FYQjUY588wzuf/++82yqYNO5YVxPyaVCBLJJJFKJEoPC0VG3dOEbezQy9zXTZyUKz1kQ7I+XlDy85iAqqK0eMe0taZ1SHkLskLDKiusCzdxsr83b54y2UyqvPfee4wcOZJYLNb9h/sO8Mgjj3DllVea+z/tfzJ/OmUyiVgbKTVbcty/HKj7WnBfd+Fvlb7VNoqHgzqhKw0ZB+LmPBEUmSTTRKGbp2wBGYok81W0lX5OP6+Outxs8O233+aiiy7q0QN9l5g9ezYXX3yxuf/zo8byr8efSzhyENETPiQJEYwi960e4vrx+bcYpV1Vl83MKgXDl2h3qQYRBeZIM82TyA/2aPkBICEEbek4WaHxpxMvosrmBOCDDz5g0qRJXd3DPx3eeecdJk+ebO4/MXwi5/cdQUu4CUVWut+gIqPubsI56fQ7LYP7ujmElsjmMGV+8Ge0Jrgi77y1ghG2gtE3rXiULpsbs94abeWB48YzJtAXgJ07d3L55Zd3df1/WsyaNYt7773X3H/plCvp6+1FU7wduQf+REQTyL0CA1xTvndrrqhkI52iLE2IuzsOnZYaRs2SJ8swVZsizVzaeyi/GHgKANlslu9///tH1Gc4HA5qa2sPX/EIYPr06cyapSdva+xunjvxh6BmSGta97uMioza2IL9vNHXK/U1FrrQElnTBAWffiriR4YmmARQoA2mI89FVLl6B1NRau1unhh2vtn41KlT2b59ew/FUQyv18tVV11Fe3s711133RFpsxzccMMNHDigz/+9uPdQLqsfTnu0ucu0/6EgInEsfWuOdf3orGtzRZ20xFLYExUSPxUCS8dkYOEUHGMQyRhkUnPa8XUsyNPDLzT7Gq+//jr//d//3e2b9vv9jBs3jgEDBlBfX09dXR3Dhw9nzJgxZuj5/vvvl9VW//79mTRpEn/84x/JZrPdvhfQ+0w33ngj77zzDgDTh32fT1p20Z5J4rHYuhV3SZKM1hzEMWHUT2L/8/5ftUi8k5ZI5y79m74BCNimIY4pHM0zptEUT0DTzBkaAA2JMEM81Sw94zokSSKZTDJ06FB27dpV9s1ee+21TJ06tUjwpdDY2MiAAQNQ1XwC0Ov1kkqlSKeLJ7LNnj2byy+/nOeee45bb721Y1PdwowZM0zNvGvdOzy9ZRG1FX3JauphSZEKt4TAemw9wV/+YULi7WV/71hX1swwVjtbRRxT6KSzwghpi525Ef5mNRVV04hl09x19KmmIB999NGyyRg9ejSbNm3ixRdfZOzYsYftgH355ZdFZNx44428+eabncgYMWKEGUzccsst/OUvfynrfrrCY489ZqZYbht8GlXeGkLpQ084KRzAK5r5n1Wxjxn6/VLnyKa/QEw0/UaBnyj2FfntbG6SQUMyzIn+Wq7oMwyAYDDIs88+W9ZD3nrrraxatYqhQ4eWVR/gqKOOMrfvvfdenn/++SKCDNxyyy1F+9dffz2ff/55yRR8Odi+fbtpgge5q5jc9wSSiWDJiKszEZJORI4RrS2MbeSxF8p+d6dzZVXTUDXNogoxJZ+L0kwHni2IrIqO5QgJZ5Jc3Xe42eBjjz1GMBg87APed999ZRNXiOOOO441a9awadMmfvvb3wJ00g6ACy+8sFPZqFGjaG5u5uqrr+72dQGeeuopc/un/U5CsTpJdYi4isyT0bfvwJkWjmM9uu9wx4RRZ3S8hpE6OUkVot40U5rImSvRKZpSc8c0IJpN09vh5ZLeQwAIh8P89a9/PeyDTZ06lUcffdTcF0KQzWb1Sc5l4KSTTirSqsGDBxcdnzBhAv379+/y/Jdffpm33noLp9NZ1vUMbNu2jfnz5wNwSmU/zqo+inAyAhRqRZ4IqVhVckclpNxYsW34oE6/GllVNVTEmYW//LwZK9jWCqdj6r3yxng7Z1f2Z6CrwnzQ5ubDL3Y57rjjeOaZZxg/fjwnnHACAwcOpL6+nr59+zJkyBCmTZvG/v3lr80YOnQoo0aNMvdPO+20w55zySWXEI/Hi3JX5aBwqODS3kMhm0SRpJyWHIYIozCXTrEdP/AUyVo88UfOqllUoY3MO3CRd+amAxe5lHpOO0RuoEpTObtmkNnYzJkzD/tAsixzxx13cPvtt7N48WI2btzInj17aGpq4sCBA2zdupUnnniCPn368Nhjj5UtKCM1oygKN910U9nnzZw5kzfffLPs+i+//DJtbW0AnF7ZH5vNQ0bT8uI+FBHkNUnEk1j6Vo+w9O/Vp7C+LLlsqIjRhvCzRZpRvG+kRzQhaM8m6e+t4qK6YwF9LHzx4sWHfSBN08o2Tb/61a944IEHyqo7bdo07rnnHmbNmkV9fX1Z5xi49NJLWbFiRVkp9mg0ysqVKwEYWdGX8dVHEUzFSmhFaSJMZLIoFZ5ay9F9ji4sltOJ5FBVloYURlImORTvm6OC6IT0s3vp4/AB+i/NXMbWA1gsFu68805eeeUVLrjgArP84YcfZt26dYc93+Fw8Lvf/Y7LLrusR9cfM2YM//u//1tW3QULFpjbw7zVoKaQTLPVkYpiIiQpv+gVi4Jt2FHDCw4jJw62DdMUSdcCI6rqMG3fSDIaGWFVCEQmyRBvjdnQZ5991k0RFGPhwoU89dRTTJkyhffff5/bbrvNPPb6669/o7bLxbXXXsu555572Hpbtmwxt4/x5sJoURRXAcVaYRJReDSjYhtcP7qwVLbUVtZnUmlUrWDkz9AErcB/ULxCCVXlRH8dAIlEgqVLl/ZABDquuOIKxo8fX1RWSIgR2XxTNDU18dFHHzFz5kw+/vjjknO8HnnkkcO2s2LFCnNW5Eh/H2w2N1mhURxn5dGJCONoKoPscw0sPGrJqtmBwqrotr1gFom55s6c+FY8HxdZZmAub/XVV1/R0tJShkhKo0+fvF+bMWMG8+fPx2rNTxEq1fHrDsLhMDfccAOzZ88uKrdYLFx88cU8/PDD5uyTMWPGcOaZZ/Lpp5922V5rayvr16/n1FNPpZfdjd9iJy0EFulQREAhYQAimUap9NUrlT6f2qb/OmRVlgZk1YLVRZphnrT8qiLDZOXICGWSHOXrxRlVAwHYsOGbLY8wQsk333zTFNwrr+RnznTUnu6gpaWFE088sRMZoA8PvPnmmwwbNowpU6bQ1KRPNDznnHMO2+7evXsBCNicuC121IKcVknzhFTasQc8lUq1v8ooklVEvSY0NA2TCNUkguLlXcaDZBKcWtGPityIYOGMjZ5gz549DBw4kOuvv77k8VJDv21tbTz55JPMmDHjkJncW2+91cyrOZ1OrrjiiqI+i4HXXnuNuro65s+fz7XXXtvpeKnrA1RanfS2u4mrmS6JADo5eQlAFUg2W4XktJuEWDQhagrNk1a4lqMDEWbDapa+do9Ztnnz5sM+wOGwe/fukuXXXXdd0ZxcgE8//ZTx48ebUd2jjz7K0qVLqaurK6q3efNmc4Bp2LBhLFmyhEAgANBlBviCCy5gzJgxBAIB2tvbu7zfwkE3n9WBpi/rMzuIBjparY70SJIkI+E39mVVaM5C8yQ6mKeu0NtltkFra+shauYRCASoqKgoqy7oCcIZM2Z0Kp86dWpRiL1z586iKTwG3njjDXP72WefNckw2h4zZkzJ665cufKQZEBx/sxjtaEvCJcQXTl2io2WhP4uF2QJSZLsRj2LhlAMh218dwXziGLjKKf+cEKIw968gbPOOou5c+fS1NREa2srDQ0NbNy4kV27drF//34OHjyILMv069eP2267jdGjR3dqQwhRMnlZyo8ZP5SqqirGjh1rnv/+++8Ti8UIhUJl3XcpFAYaVTYXaDoheUp0dDZYBXsSuWyxZOZP9BFDg5AybkQTAhQLlTYXAPF4nGg0WtZDfPTRR7S0tFBbW0ttbS3HH388559//uFPLHwYSWL8+PG89FLxUrxx48Z1qmuYsNbWVpYtW8aECROYNm0aTz75ZLeuWQqKkp99Es9mQZKROkiwk3kynyHfeZT1A+Z4sCyEEFo35nlrQmCVFZyKTmooFCISiZR1biwWM216uXjxxRd5+OGHO5X94Ac/MPenTJlSlBo3MHnyZDMdcuutt3L55ZcfETJAzwwY2JcIISv5JGFJ85Tb0JcAGklIWd/XXzYB6G9N6tZgs4Y+M9GRW0rQ3t5uRjnHHHMMVVVVhzqdP//5z925HA8++CAPPPBAp/TJu+++SyKRYO/evbz88sslzx04cKCZaNy6dWuRT/mmcLv1wSUhBOFsCquka8yhiDAWxsqSpO/n3/liciADcboBAUUvBbBY8r+Mq6+++rBOe+3atTz99NNlX88Y9yjsR7S3tzN16lQ+/PBD6uvri5KCkUikKAL605/+1G2zWA6MH15TKkZzOo5TUYq8R9486UKXje2chsi5bUWAJETCOE8Gyn5blwRYJIVoJkFjQk87HHvssZx00klMmDCB8847j6+//vqw7Tz44INlj3f8+te/BvSUhqEJs2bN4g9/+AM33XRTUR+ktbUVn8/HeeedV9TG/Pnzefrpp/F4PBwpGNmFg+kYoUwSa84vdzZPRkdRMl+qIJskSchIWcDM4cgIsbtTsHwIWCQJsik+PJifb7V69WoWLlyIw+EoK80RDof5l3/5l7Kud+qppzJtmr6S7tprr8Xtdpv9h6amJpYvXw7oJumMM/QR0UL7buCOO+6gubmZ9957j/vuu48RI0aUdf1SCAQCZqplR6yN9kwSm6x0Mk+mVlBARq5cRkKxWiCZbtWiCVMpZBRlr9kbLAMC8LoqeGrHZyzIkWKYjO5M2V+wYAF33nlnWXWnT5/OK6+8Qn19PfF4nLq6OgYN0gfGzjzzTGRZZsiQIWzZsoUBAwbw2mulV4U5HA4mTpzIo48+yrp169i5cye//OUv6dWr7PU0AIwcORKfTx92WBVshGxGf9uRRBER+jslC7XCePuq/u4Vi82K1h4NZpvz/QZZC4Z3Sk576St3AY/Fhk1W+MFnL3LD2reJZvVOkuHoysXvf/977rnnnrLqTpkyhb1799LW1sbevXvZsWMHd999NzabDSEEVquVadOmsWvXrrIFfNRRR/Hkk0/S1NRkmsZyMGTIEHO7IRkCixVyWtDRPBlRlQzF5kqSUJx21NbQ7mwoGiH3Egc5vXTjPrkm0LmP3wUkIKOpVDu8SIqFGRs/ZFP7PkBXZbu9e+Q+/vjj3RrXLgwaHn/8cbMflEwmmT59ereubSASifD222+XXd/IhUWyKdaEDlBhc+raIUnIyJ3NU+6dYXkfojtvi8OOCMd35pqVAWTL0P7rRTojumu2MpqKz2IHTxWpnKmqra3tlE8qB7Nnz2bIkCHs2LGj2+cqioLb7UaWe7YWcNu2bRxzzDFljUoaOPXUUwFY1rqHDeGDVNpcZt+jpHkq0BaTHElGsVpJbN69OtesCiDLHtdO7UDbWrr5QAL9BQCoGQ6k8h3Dvn37dqsdA1u3bmXw4MH87ne/69H5PcF7773HiBEjzLR7ORg1apTp0L9OhEBophYoJfxEIUGKqTUSsqIgpdLENmzfmGtaA5DDj7yI5LSvlezWkjdQChKYr01CzbI92mYe6927d9ntlMK//du/0adPn2736LuDZDLJNddcw0UXXUQqlerWuYXR4YZwE7JswfAfpfyESYShKegmS7FbUYPRPcmd+4x+gj7up+49SHbHvpWSr3sOWZgtyHwZyvcpvikhAPv372fy5MlUVlbyH//xH+ZygG+KlpYW7r77bpxOZ9EAWHdgDJa1pRMsbN5JrcNj9r51oec0Q85rh/mvYN/q9ZD8ev+6xO79BwDT8coiniK9assS2eM8zHLEztCEAIuNhmQ+uVhqnq4kST2y88FgkIceeojevXtz8sknc++997Jw4UIymUzZbWzfvp0nnniCM844g5qamm7lsmRZprq62rzvESNGmP2XD5t3sCMepMJiLwp35cJtCp08ZupEAhwVXhJbvjbemGNK3gKQ/fLrDSKV3oIiDSnXueuDMQK7YmNvMkxbOk6lzcVZZ53Vqe5jjz3Gvffey+OPP152mNsRa9euZe3atUyfPh2fz0f//v2pra2lX79+1NTU4PP5yGazBINBGhsbaWxsZO/evTQ2NvboeqCPr59zzjnmhL2rrrrKPLaseRfZTAZZgKaJ/EihJPIagcgnE3Pj7ZKsa5JIZkRoxSbjLXRmusHo0VH50r//2nJc/W+05vLHCHJTVGmJh3j3tJ/wg7rjAH2q6LZt23JNS+zatcuca3vaaacdcspQIBBACPGNxiqOFB566CHq6+u54YYb8Hg8bN++ndraWvZFQ5y35AUimRRei033pwUvhzb7I0j59IlsbMvYagIkd+1fuuZH084WqmZHzyfqHgAAIUgv2/Ch7HWbb94sF7IkgZphTYEfKUzm2Wy2oknNh0qZjBs3jmAwSGtra1Hn6x+FSZMmce655+JyOfnDs8/qaxsF/OWrZWzat41UKsn+cJv+CbXSGGzWP+3N7G9roTnSTjQVJ51Jo6YyiGQWkU5j8ToJrdywSKhalvzSdMn8H4D1+IFUvHDPehFNDBfp7i3/aknFOMXfm5Vn3wzob2sYOXIkoPfe9+zZQ2VlJQD79u3j6KOPJpksXuwydOhQVq1aZfb2t2zZ0q11I0ca5593HvM//BDDDiSTSfbu3kskkeCxzYtJZzIMclVikxVsVgsWRUGWZTQZoiJDXNZoySbYF2olrKVJ2WQyNhmL00FFnzq23fTb84LL1i1Cd+ip3IWEmTvPbNpFZu32/7adfsKz6p6DpSYVdYleDi+rWnbxZuMGLut7AieffDLPP/88N910E3feeadJBuhZ0ssuu6woyunduzeLFy8uSr0MGTKE2267jWeeeaase+jfvz/pdPqIRWQ//unPCEbjLF22nKwmCEViqKpKUqhc6RxMv+oANpsNh82Gw27HYbfhdNqx2WzIdhuRRJz1mzaw/mCKllSMoJwl5rViGVrP5g9WvRdctm4l0AtoR9cSDTq8m8A56fRq/+M378zu2Ff2a5sFYJVkDsSDnFE1gE/PKj3zXLezul1dvXq1mX6ora3liy++MDuUK4MN9HF4qXf6aWxsZNCgQSUX5BhwuVy88MILXHnllTQ0NDBo0KBuRWEGJElm0LHHceKoMZwydhz1AwZwoOkgVosFl9OJy2HH6XTgcjhwO+zYbFadEIcdh92ORZHRO9cSBw828+X69TTu3YvIqLhsTrweH+1tbSxd9ulLHy2a//toOhlE9x1hdKeeBbRiNVBkqt74zXNKv16/0JraytISw7E7FCsN4QOc13soH5720071rv58FhfXDeWqen1u8d69e1m0aBEXXnghNTX6HOHVoX2Men86j468lPuO1eP9Sy+9lDlz5pS89ujRo1m8eHGRj7ryyitLTorrCgMGDeasCd9n6PAT6T9gIH5/gEwmRSTUjs1qwe1yYrfasNut2O12nHYbLpcTl8OB1WpFCEEqnSaVzpJIpdm9ezcbN3xJS0szLpcHb6CClmAbKz9b8tbyxYv+lozFPwdc6FrRCiSBDCUJAVzXnHu076Gfbs1+1aCUa7YEem9UkRT2Rw4yyNuLHw8YyQneGjZHW3i9cSPrGzfRv3oAK86+mTpHZwVcFz7A9z6dQVuwkR8OPp23T70G0JdAT5w4sVP9iy++mLlz53Yq76o+gEVReOTh34Cs8Prb8xh31jmMHHMqFRWVJGIRMukUFkXGbtNNkMOhE+Bw2HE7nXjcLuw2G5IE6XSGWCJBOBojkUwTiyf4eucOtm3bRjabpaqmlmCoXV2+dPH7a1Yuez0RjX0OWNG7Gu1AFN13pHJkqCUJAah85f7nrccPvFHd11K2LzGHdmWZtmSUdCqin6uBxe6lrzvA7kgTvRxefj/iIq7qewIA7ZkkLzas474N84mpWeqcfhLZFMvPupEh3hqEEAwaNKhoVe+FF17IvHnzzP1XG9ZTa/fwvZpBRKNRBg4c2GmumCzBazNnMvGSK1iycjXNbe0okkQqEUOWME2Pw27H6dA/LqcDn8eN2+XEYrGgqirxRJL2cIRQOEoskSCb1QhHIny1bQtNBw7g9gWIpxKs+XzFJ18sW/paPBJehe64LUAoR0QCSBd8spTyIQacPzrrWP+Tv9ic3bRb7o5z70SS0EcYLbKMACyywsF4iGQmzglVA6m2utgWbWFfuIkKdwU+qxNVaDREmrn/+Ak8PFRfGvDCCy+Ya8QfeughHnzwQfMacw9s4ZIPn+LekZfx2xP0lcZ33XVXp3H7Rx9/mjMmnM8HCz7C5/VQUxnAarFgzwnfmSPC5XDi8bjwe904HQ4kJFLpFJFojGA4QjgSIxaPk0xlyKgqLc3N7N2zm3QmSyweY+OXaxav+3zlnGh7+wpAyZFhEJFE14g0upkqIoOuNASg8sX7HrGOHvIrdXsjWA7/BpzC4X2pQ6FVks3cgCLJ5husU2oWv9WBz2rPvWlIn44ZyiSpsNhZffYv6JWbsrp48WICgUDR0Ousxo1MXv4yaFnOrz+B+eN+AugzD42JcX37D+TmO+7hqGOHsGf3TqoCAZwOO3a7DafDgcupf9xOB163G7/Pi92uD3rF4gmCoRDt4QjRaJxYIkE8kSSdyZJKpWltbSUYDHKw+QDbt25Zse7z5TOj7e2foWuDDYiQN03p3LfhL0wzZZBRLMcOsJ58jFQ5Y9oWLRw/VsSTXZquQxFhQJYklIJXcxmv5ujYiHGaIik0RFu4sv5EZp5SevDq3zYt4HebFlLpqsBrddCUCDHv1B9zTi99aPeNN97gf155nYsvn4Lb7SLU1oLb5cTpcOjRktOB2+nE7XLi83oI+NzYbTayqkYkEqUtFNaJiOWIiCdJJFNksiqqqhIKh9m54yu2bP7yiw1frHwl2t6+HN1RGxoRI+8jDI3I5EgoJMLM05YQXTG8d0++3HP7j2Zn1u8ApTgx2HFypNS50DxiRGJSwZULZ/GValWRZBpibYzw13H34DM4vbIfTsXK31t28dtti9nQ3kgfdxUORUEI2BNu5cRAHcvPuZFdG3ey8uu9ZAXEwu1YZBm3W4+MXE4nHrcTt8uF3+sh4PPidNhIZ7KEIlHagiHCkSjRWJxoPEE8kSCRTJJKpZFkBUmxsGPHVyz9eOHy9Z8vfzWdSKzLCdiOHsLGyJumQrPUUSOKiCiLEIDKl/79eduoY2/M5kxXd4g41MW6IsIkCgmbrHAgESKRThBwBbBIMi2JEE6rg94Or7nKS1E1EopGUyTInfFBDGqWCSpZ6mqqsNt05+x2OXG7nXicTvw+L5UBP06nnUwmS3s4QlswRCgaIxqLEYsliCeTJBJJ4vEEsqLg8gU4cGAff//w3VXLFy2cmU4kVpEnIkqeCCOM7RYRpWRUEtbjBzgqX/n1BhFLHi3aI2bnpyvz1JGKjocPR0ThfmFyLqXq72Z3WSxIgKppIASKCs1SEm9M5coDldTFFKwVbgI+Lw67HbdLD1e9bl0jKgMBPB4nqqoRCkdoCbYTCuc1IpHzE4lEAiQZb6CK1mALiz+av3LJwvfnRtvbl6IL3EneRyQpjppKmaaylh6XFUK5rjn3tMBjNy7NbNkLWVWf7lOGVnStEfmjpYgo1bjxh4sBEAJJgKQJmklQExb8eH81x8h+In4Fh8OOx+XC43bi9bjxedxUVQTw+7zIkkQ4GqOlLUgwFCYSjRONx4nHEySSKeIJPcfmCVTQHg6z4tNFaz6Z/+5rweaDy9AFa0fXhgidiei2RpSWShnwP/TTO9w/ueDp7OZdJfzJt0NEsZ/JjS8ITDJaSNK3XfDTA72os3mJ+S14nE48Lhdejwuvx02l30dVZQCHzUYsnqSlLUhbKOcn4gli8YRumhIJhCZw+yuIxCKs/nz5xr+/N+flln37PkUXqBPdR3TUCMNZfyMiSsnusKh++f4Z9lOPvy69eTeSReFImqeSx40xBQqmaAqQVY2DUpKBrXD9gVoCLjdJvxWfy4XH7cbrcRHweamprMTv9ZBVs7S0tdPSFiQcjRGJxojFddMUTyTQVA1PoJJEKsWKZZ98ufCdN15ua2pagS5oBzoJpfoRR4yIrmRzSChVPqpf/81HSm3F97I79+dI+S6IyMVqAmRV0Cwl6RcUOTI8ZHw2fG7dNPk8bioq/NRUBrDb7ISjUQ62tBIMRYhEY0RjceKJBPF4gqyq4fL5SSSTrF+zavuiD96d2bDjq4/QBW2Ypq561hlyf0eTYjK+EbrdDbcM6m2tefWBFZLTcbK6p8kkBY6UeSqY0G9s5xbly5qgTSSpCqncvL+OapeXtN8gw0OFz0NNVSUBv4+sqtLc2kZLW5BQpFAr4mTSWdz+AKlMhjWfL9++8L23Xt6/a9didA1wkdeIjkQUOmuVI6ARpSXWTVgG9bH3eu3B5bLHeVJmRyOS1VKWVpQqLSTC2M+vMMqTo6iCdlLYoml+sa+O/o4Aab8Nf04rKgN+elVX4XTYCUdjHGxpIxgKE47qEVQsFiedzuD2BcgiWL3ys53z58x+af+eXZ+ip8GduW/DWRumqdBZF6Y5jigRpeTVLViO6u3s9bf7PrL0qR6X3rrH9CmlGj4UEZ3Mk2QYKb3bK6E78ITIkkwm+Nm+akYpNSQqdc3wez1UV1ZQXRkAoLmtnda2IOFIjHAsRiQaJZPO4vL5SasqX6xYuv3jD959a/dXW/+OnnV10zUR37pGdETPM4eApbZCqv7ztHdtwwdNzGzVF9J3nAFftp8wNaTgDxjnwltN0ziYjXHpAT8XZ/sQrbLh9bjx+zz0qqzE7/OSTKV0rQiHdccdjpJKp3F5fCQyGT5fvmT7Jwvef2v3ti0foRPhQTdJYYpNU0dn/Z0Q0Uk+PW7Aaafmj7/8H+eEUT/Lbm9AJNMgy52IKNwr8hPoc5YoJML4CN1v7NdijGqxc2O8P2qFE4fXSYXfR01lBU6Hw+xXhMJRwpEoyWQKm8tNKpth/drVjQveefPVr7dsmoeuCYVEHC5qMj7fGb4xIQYC/zr55sCdV/xRPdCK1twOHRZBQt43GGXFCyANMqQiUxXWUrgjWe5o70+dtwLNZ6fS76O6IoCiKARDYYLter8inkhgd3lJZbOsXbNq37y3Zr28a8vmhejmqNA0GRph5JtKEfGdaERHHDFCAFwTRp5Y/fgt78oeV33m6/1IQuiRktmxM9IhnVMjBikyumYgQNVUWlNRrm/rzXhLb6IVVip9Pir8PjRNoz0UoT0cJh5PYnW6yAhYuXzJnnlvzJy5a9uWT4A2dGedJE9EYdLvn4YIA0eUEAClJiDX/PbnL7gvGPuTbEMzWlsESZE7+QlT+JQgBr2/cUCNMTrk5OfpQWT8drx+Dz6Ph2w2S3soTCyewO5ykxXwxepVre/MfvXVzWu+mAcEyZumCLpmdAxf/yE+4nA44oQY8E468+yqf//xS9a6yr6ZnfsglUGSZX1tNkYEVTzDTwYzTxVX0yjxNHdGB9HfVYHmt+NxOkmn00SjcZweL0KxsGL50oNvvfbSrI2rP18INKGbpjT6mIShEaVyTR171/8U+NYIAVAqvNaqO6+4r+Lq8++XbVZrZvcBSKSRFLlgVjidtEPKauzPRLk0XMOPpAFE/Qo2m5VsJovL7QWrjc+WfXrg7dmvvrP6s6XzgEbAiy50QyM6EmGEsP8UpqkrfKuEGHCOOLpvxTXfvyfww9Nvsvo8jsyeJrRYElmWCzQknzQMZZME4oJ/TR2L1+kia5UIVFQiWW2sWL6kac7rM99e+cmi94B96ERkKNaIDPnZHP8niDDwnRBiwDlkQK/qn/1gWuB7o6+396mpUFtDqMGI/mewJUkPAlRBUybKFZFafiDVk63z4fb6WL92ddtrL77w2rK/L3wbfT6TD13ghUR0jJqMnvU/PREGvlNCDFhrKlw1V58/ueL8sTe7jxswxuJykm1pJ9sWpj0dpzou8aBjNFW1dazbtiE468UX/vejd9+egx41VaELvDBqKhW+/lP6iMPhH0KIeXFZxjt66En+M06cUHn2qEnOY/qdGXFI/CTShyEbwweefum55z7+4L35QtVa0OfBKnSd4uiYazK+/0/hH0pIISSLgn3E0cMHjRs9aVjS7Z4/87W/haORvcAA9DGJQgJKOev/kxrREf8shBj3USjICiCALnjjF69Rel7T/3kiDPx/tcXfsY70TpIAAAAASUVORK5CYII=";
diff --git a/docker/jupyter/unsloth_labext/src/outputSelect.ts b/docker/jupyter/unsloth_labext/src/outputSelect.ts
new file mode 100644
index 00000000000..50ae370d6fc
--- /dev/null
+++ b/docker/jupyter/unsloth_labext/src/outputSelect.ts
@@ -0,0 +1,112 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-Present the Unsloth team. See /studio/LICENSE.AGPL-3.0
+
+import {
+ JupyterFrontEnd,
+ JupyterFrontEndPlugin
+} from '@jupyterlab/application';
+
+/**
+ * Colab-style Ctrl/Cmd+A inside a cell output: clicking an output leaves the
+ * notebook in command mode, so the chord otherwise fires `notebook:select-all`.
+ * Keyed off the target or last pointer-down, never the stale selection anchor.
+ */
+
+const OUTPUT_SELECTORS = ['.jp-OutputArea-output', '.jp-Cell-outputWrapper'];
+
+function closestOutput(node: Node | null): HTMLElement | null {
+ const el =
+ node == null
+ ? null
+ : node.nodeType === Node.ELEMENT_NODE
+ ? (node as HTMLElement)
+ : node.parentElement;
+ if (!el) {
+ return null;
+ }
+ for (const sel of OUTPUT_SELECTORS) {
+ const hit = el.closest(sel) as HTMLElement | null;
+ if (hit) {
+ return hit;
+ }
+ }
+ return null;
+}
+
+function inEditableContext(): boolean {
+ const ae = document.activeElement as HTMLElement | null;
+ if (!ae) {
+ return false;
+ }
+ if (ae.isContentEditable) {
+ return true;
+ }
+ const tag = ae.tagName;
+ if (tag === 'INPUT' || tag === 'TEXTAREA') {
+ return true;
+ }
+ return !!ae.closest('.cm-editor');
+}
+
+const outputSelectPlugin: JupyterFrontEndPlugin<void> = {
+ id: 'unsloth-jupyterlab:output-select-all',
+ description:
+ 'Ctrl/Cmd+A inside a cell output selects only that output, not every cell.',
+ autoStart: true,
+ activate: (_app: JupyterFrontEnd): void => {
+ // a click on an image/widget output leaves no text selection
+ let lastPointerOutput: HTMLElement | null = null;
+ // ...but only while it is still in the document AND in the ACTIVE cell: J/K
+ // navigation fires no pointer event, so a stale value selects an earlier cell's
+ // output, and a re-executed cell leaves a detached range that selects nothing
+ const rememberedOutput = (): HTMLElement | null => {
+ const output = lastPointerOutput;
+ if (!output || !output.isConnected) {
+ return null;
+ }
+ const cell = output.closest('.jp-Cell');
+ return cell && cell.classList.contains('jp-mod-active') ? output : null;
+ };
+ document.addEventListener(
+ 'pointerdown',
+ (event: PointerEvent): void => {
+ lastPointerOutput = closestOutput(event.target as Node | null);
+ },
+ true
+ );
+
+ const handler = (event: KeyboardEvent): void => {
+ if (event.key !== 'a' && event.key !== 'A') {
+ return;
+ }
+ if (!(event.ctrlKey || event.metaKey) || event.altKey) {
+ return;
+ }
+ if (inEditableContext()) {
+ return;
+ }
+ const output =
+ closestOutput(event.target as Node | null) ?? rememberedOutput();
+ if (!output) {
+ return;
+ }
+ // prevent Lumino's `notebook:select-all` from also running
+ event.preventDefault();
+ event.stopPropagation();
+ try {
+ const range = document.createRange();
+ range.selectNodeContents(output);
+ const sel = window.getSelection();
+ if (sel) {
+ sel.removeAllRanges();
+ sel.addRange(range);
+ }
+ } catch {
+ /* no-op */
+ }
+ };
+ document.addEventListener('keydown', handler, true);
+ }
+};
+
+export default outputSelectPlugin;
diff --git a/docker/jupyter/unsloth_labext/src/splash.ts b/docker/jupyter/unsloth_labext/src/splash.ts
new file mode 100644
index 00000000000..2b0fd16928c
--- /dev/null
+++ b/docker/jupyter/unsloth_labext/src/splash.ts
@@ -0,0 +1,87 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-Present the Unsloth team. See /studio/LICENSE.AGPL-3.0
+//
+// Replace the JupyterLab loading splash with a spinning Unsloth logo. The stock
+// splash is disabled + locked at build, so this is the only ISplashScreen provider.
+
+import { JupyterFrontEndPlugin } from '@jupyterlab/application';
+import { ISplashScreen } from '@jupyterlab/apputils';
+import { DisposableDelegate, IDisposable } from '@lumino/disposable';
+import { UNSLOTH_LOGO_DATA_URI } from './logo';
+import { SPLASH_LABEL } from './branding';
+
+const STYLE_ID = 'unsloth-splash-style';
+const SPLASH_ID = 'unsloth-splash';
+
+function ensureStyle(): void {
+ if (document.getElementById(STYLE_ID)) {
+ return;
+ }
+ const style = document.createElement('style');
+ style.id = STYLE_ID;
+ style.textContent = `
+#${SPLASH_ID} {
+ position: fixed;
+ inset: 0;
+ z-index: 1000;
+ display: flex;
+ flex-direction: column;
+ align-items: center;
+ justify-content: center;
+ background: var(--jp-layout-color0, hsl(70, 8%, 12%));
+}
+#${SPLASH_ID} img {
+ height: 72px;
+ width: 72px;
+ animation: unsloth-splash-spin 1.2s linear infinite;
+}
+#${SPLASH_ID} .unsloth-splash-label {
+ margin-top: 14px;
+ font-size: 13px;
+ opacity: 0.7;
+ font-family: sans-serif;
+ color: var(--jp-ui-font-color1, hsl(60, 30%, 92%));
+}
+@keyframes unsloth-splash-spin {
+ from { transform: rotate(0deg); }
+ to { transform: rotate(360deg); }
+}
+@media (prefers-reduced-motion: reduce) {
+ #${SPLASH_ID} img { animation: none; }
+}
+`;
+ document.head.appendChild(style);
+}
+
+const splashPlugin: JupyterFrontEndPlugin<ISplashScreen> = {
+ id: 'unsloth-jupyterlab:splash',
+ description: 'Unsloth spinning-logo loading splash.',
+ autoStart: true,
+ provides: ISplashScreen,
+ activate: (): ISplashScreen => {
+ return {
+ show: (): IDisposable => {
+ ensureStyle();
+ const overlay = document.createElement('div');
+ overlay.id = SPLASH_ID;
+
+ const img = document.createElement('img');
+ img.src = UNSLOTH_LOGO_DATA_URI;
+ img.alt = 'Unsloth';
+ overlay.appendChild(img);
+
+ const label = document.createElement('div');
+ label.className = 'unsloth-splash-label';
+ label.textContent = SPLASH_LABEL;
+ overlay.appendChild(label);
+
+ document.body.appendChild(overlay);
+ return new DisposableDelegate(() => {
+ overlay.remove();
+ });
+ }
+ };
+ }
+};
+
+export default splashPlugin;
diff --git a/docker/jupyter/unsloth_labext/src/uiChrome.ts b/docker/jupyter/unsloth_labext/src/uiChrome.ts
new file mode 100644
index 00000000000..65556fe1df6
--- /dev/null
+++ b/docker/jupyter/unsloth_labext/src/uiChrome.ts
@@ -0,0 +1,51 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-Present the Unsloth team. See /studio/LICENSE.AGPL-3.0
+
+import {
+ ILabShell,
+ JupyterFrontEnd,
+ JupyterFrontEndPlugin
+} from '@jupyterlab/application';
+
+/**
+ * Hide the right activity bar by default. There is no settings key for it, so the
+ * strip is hidden with CSS and the panel collapsed once on startup.
+ */
+
+const STYLE_ID = 'unsloth-ui-chrome-style';
+
+function injectStyle(): void {
+ if (document.getElementById(STYLE_ID)) {
+ return;
+ }
+ const style = document.createElement('style');
+ style.id = STYLE_ID;
+ style.textContent = `
+/* Hide the right-hand activity bar strip (Property Inspector / Debugger tabs). */
+.jp-SideBar.jp-mod-right {
+ display: none !important;
+}
+`;
+ document.head.appendChild(style);
+}
+
+const uiChromePlugin: JupyterFrontEndPlugin<void> = {
+ id: 'unsloth-jupyterlab:ui-chrome',
+ description: 'Hide the right activity bar by default (Colab-like chrome).',
+ autoStart: true,
+ requires: [ILabShell],
+ activate: (app: JupyterFrontEnd, shell: ILabShell): void => {
+ injectStyle();
+ app.restored
+ .then(() => {
+ try {
+ shell.collapseRight();
+ } catch {
+ /* no-op */
+ }
+ })
+ .catch(() => undefined);
+ }
+};
+
+export default uiChromePlugin;
diff --git a/docker/jupyter/unsloth_labext/style/index.css b/docker/jupyter/unsloth_labext/style/index.css
new file mode 100644
index 00000000000..0046a04a363
--- /dev/null
+++ b/docker/jupyter/unsloth_labext/style/index.css
@@ -0,0 +1,6 @@
+/* "Unsloth Dark" theme entry point.
+ * Start from the built-in JupyterLab Dark theme (theme.css pulls in its full
+ * variable set + base rules), then override the palette with the Sublime/Colab
+ * Monokai colors in variables.css. */
+@import url('@jupyterlab/theme-dark-extension/style/theme.css');
+@import url('./variables.css');
diff --git a/docker/jupyter/unsloth_labext/style/variables.css b/docker/jupyter/unsloth_labext/style/variables.css
new file mode 100644
index 00000000000..c95d90fcf4d
--- /dev/null
+++ b/docker/jupyter/unsloth_labext/style/variables.css
@@ -0,0 +1,97 @@
+/* Unsloth Dark = Sublime/Colab "Monokai" palette, overriding JupyterLab Dark.
+ * Applied on :root because the theme manager only loads this file while the
+ * "Unsloth Dark" theme is active, so it never affects the light theme.
+ *
+ * Exact HSL from Sublime "Monokai":
+ * bg hsl(70,8%,15%) fg hsl(60,30%,96%) selection hsla(55,8%,31%,.7)
+ * comment hsl(50,11%,41%) string hsl(54,70%,68%) number hsl(261,100%,75%)
+ * keyword hsl(338,95%,56%) function hsl(80,76%,53%) builtin hsl(190,81%,67%)
+ * param hsl(32,98%,56%) error hsl(0,93%,59%)
+ */
+:root {
+ /* surfaces */
+ --jp-layout-color0: hsl(70, 8%, 12%);
+ --jp-layout-color1: hsl(70, 8%, 15%);
+ --jp-layout-color2: hsl(70, 8%, 10%);
+ --jp-layout-color3: hsl(70, 8%, 8%);
+ --jp-layout-color4: hsl(70, 8%, 6%);
+ --jp-toolbar-background: hsl(70, 8%, 13%);
+ --jp-cell-editor-background: hsl(70, 8%, 15%);
+ --jp-cell-editor-active-background: hsl(70, 8%, 15%);
+ --jp-cell-editor-border-color: hsl(70, 8%, 22%);
+ --jp-rendermime-host-background: hsl(70, 8%, 15%);
+ --jp-rendermime-error-background: hsla(338, 50%, 56%, 0.15);
+ --jp-cell-prompt-not-active-font-color: hsl(60, 8%, 55%);
+ --jp-notebook-multiselected-color: hsla(80, 40%, 40%, 0.18);
+
+ /* inverse surfaces */
+ --jp-inverse-layout-color0: hsl(60, 30%, 98%);
+ --jp-inverse-layout-color1: hsl(60, 30%, 96%);
+ --jp-inverse-layout-color2: hsl(60, 10%, 72%);
+ --jp-inverse-layout-color3: hsl(60, 8%, 55%);
+
+ /* text */
+ --jp-ui-font-color0: hsl(60, 30%, 98%);
+ --jp-ui-font-color1: hsl(60, 18%, 90%);
+ --jp-ui-font-color2: hsl(60, 8%, 66%);
+ --jp-ui-font-color3: hsl(60, 6%, 46%);
+ --jp-content-font-color0: hsl(60, 30%, 98%);
+ --jp-content-font-color1: hsl(60, 30%, 96%);
+ --jp-content-font-color2: hsl(60, 12%, 72%);
+ --jp-content-font-color3: hsl(60, 8%, 52%);
+
+ /* borders */
+ --jp-border-color0: hsl(70, 8%, 26%);
+ --jp-border-color1: hsl(70, 8%, 22%);
+ --jp-border-color2: hsl(70, 8%, 18%);
+ --jp-border-color3: hsl(70, 8%, 14%);
+
+ /* accent / links / brand */
+ --jp-content-link-color: hsl(190, 81%, 67%);
+ --jp-brand-color0: hsl(190, 81%, 72%);
+ --jp-brand-color1: hsl(190, 70%, 58%);
+ --jp-brand-color2: hsl(190, 60%, 46%);
+ --jp-brand-color3: hsl(190, 55%, 36%);
+ --jp-accent-color1: hsl(80, 76%, 48%);
+ --jp-warn-color1: hsl(32, 98%, 56%);
+ --jp-error-color1: hsl(0, 93%, 59%);
+ --jp-success-color1: hsl(80, 76%, 45%);
+
+ /* selection / cursor */
+ --jp-editor-selected-background: hsla(55, 8%, 31%, 0.55);
+ --jp-editor-selected-focused-background: hsla(55, 8%, 31%, 0.75);
+ --jp-editor-cursor-color: hsl(60, 36%, 96%);
+
+ /* CodeMirror 6 syntax tokens (Monokai) */
+ --jp-mirror-editor-keyword-color: hsl(338, 95%, 56%);
+ --jp-mirror-editor-atom-color: hsl(261, 100%, 75%);
+ --jp-mirror-editor-number-color: hsl(261, 100%, 75%);
+ --jp-mirror-editor-def-color: hsl(80, 76%, 53%);
+ --jp-mirror-editor-variable-color: hsl(60, 30%, 96%);
+ --jp-mirror-editor-variable-2-color: hsl(32, 98%, 56%);
+ --jp-mirror-editor-variable-3-color: hsl(190, 81%, 67%);
+ --jp-mirror-editor-punctuation-color: hsl(60, 18%, 85%);
+ --jp-mirror-editor-property-color: hsl(80, 76%, 53%);
+ --jp-mirror-editor-operator-color: hsl(338, 95%, 56%);
+ --jp-mirror-editor-comment-color: hsl(50, 11%, 41%);
+ --jp-mirror-editor-string-color: hsl(54, 70%, 68%);
+ --jp-mirror-editor-string-2-color: hsl(54, 70%, 68%);
+ --jp-mirror-editor-meta-color: hsl(190, 81%, 67%);
+ --jp-mirror-editor-builtin-color: hsl(190, 81%, 67%);
+ --jp-mirror-editor-tag-color: hsl(338, 95%, 56%);
+ --jp-mirror-editor-attribute-color: hsl(80, 76%, 53%);
+ --jp-mirror-editor-header-color: hsl(338, 95%, 56%);
+ --jp-mirror-editor-quote-color: hsl(80, 76%, 53%);
+ --jp-mirror-editor-link-color: hsl(190, 81%, 67%);
+ --jp-mirror-editor-error-color: hsl(0, 93%, 59%);
+ --jp-mirror-editor-activeline-background: hsl(55, 11%, 22%);
+ --jp-mirror-editor-matchingbracket-color: hsl(54, 70%, 68%);
+}
+
+/* Active line tint inside the code editor (Monokai line_highlight). */
+.cm-editor .cm-activeLine {
+ background-color: hsla(55, 11%, 30%, 0.35);
+}
+.cm-editor .cm-activeLineGutter {
+ background-color: hsla(55, 11%, 30%, 0.35);
+}
diff --git a/docker/jupyter/unsloth_labext/tsconfig.json b/docker/jupyter/unsloth_labext/tsconfig.json
new file mode 100644
index 00000000000..a26bcc1a5ac
--- /dev/null
+++ b/docker/jupyter/unsloth_labext/tsconfig.json
@@ -0,0 +1,26 @@
+{
+ "compilerOptions": {
+ "allowSyntheticDefaultImports": true,
+ "composite": true,
+ "declaration": true,
+ "esModuleInterop": true,
+ "incremental": true,
+ "jsx": "react",
+ "lib": ["DOM", "ES2018", "ES2020.Promise"],
+ "module": "esnext",
+ "moduleResolution": "node",
+ "noEmitOnError": true,
+ "noImplicitAny": true,
+ "noUnusedLocals": true,
+ "preserveWatchOutput": true,
+ "resolveJsonModule": true,
+ "outDir": "lib",
+ "rootDir": "src",
+ "skipLibCheck": true,
+ "strict": true,
+ "strictNullChecks": true,
+ "target": "ES2018",
+ "types": []
+ },
+ "include": ["src/*"]
+}
diff --git a/docker/run.sh b/docker/run.sh
new file mode 100755
index 00000000000..f033941ae06
--- /dev/null
+++ b/docker/run.sh
@@ -0,0 +1,141 @@
+#!/usr/bin/env bash
+# Convenience wrapper for `docker run unsloth/unsloth`. Sets the easily-forgotten
+# flags behind the most confusing failures:
+# --gpus all attach a GPU (entrypoint refuses to start without one)
+# --ipc=host ample /dev/shm; the default 64MB crashes DataLoader workers
+# --ulimit memlock=-1 unlimited pinned memory (else multi-GPU training stalls)
+# --ulimit stack=64MB larger libtorch thread stack (some kernels OOM the 8MB default)
+# Plus mounts the host HF + Triton caches so downloads and kernels persist.
+#
+# With no command the image's own CMD runs, which on unsloth/unsloth:latest is the
+# Studio (8000) + JupyterLab (8888) launcher, not a REPL. $PWD is at /workspace/host.
+# bash docker/run.sh # start Studio + JupyterLab
+# bash docker/run.sh bash # shell in the container
+# bash docker/run.sh python /workspace/host/train.py # run your training script
+# UNSLOTH_PORTS="-p 8000:8000 -p 8888:8888" bash docker/run.sh # publish the ports
+#
+# JupyterLab on the lean core image (unsloth/unsloth:core):
+# UNSLOTH_PORTS="-p 8888:8888" UNSLOTH_IMAGE=unsloth/unsloth:core \
+# bash docker/run.sh jupyter lab --ip 0.0.0.0 --port 8888 --allow-root
+# CPU-only hosts: no --gpus and UNSLOTH_ALLOW_CPU=1. No training, but Studio chat,
+# Jupyter and GGUF tooling work:
+# UNSLOTH_GPUS=none UNSLOTH_ALLOW_CPU=1 \
+# UNSLOTH_PORTS="-p 8000:8000 -p 8888:8888" bash docker/run.sh
+#
+# Overridable env:
+# UNSLOTH_IMAGE=unsloth/unsloth:latest image and tag to pull/run
+# UNSLOTH_GPUS=all "all" | "0" | "0,1" | "none"
+# UNSLOTH_ALLOW_CPU= set to 1 to allow GPU-less runs
+# UNSLOTH_PORTS= extra -p publish flags
+# HF_HOME=$HOME/.cache/huggingface host HF cache dir to mount
+# TRITON_CACHE_DIR=...unsloth-triton host Triton cache dir to mount
+# UNSLOTH_WORKDIR=$PWD host dir mounted at /workspace/host
+set -euo pipefail
+
+IMAGE="${UNSLOTH_IMAGE:-unsloth/unsloth:latest}"
+GPUS="${UNSLOTH_GPUS:-all}"
+# Translate index selectors to Docker's `device=` form: a bare integer is a COUNT,
+# not an INDEX, so `UNSLOTH_GPUS=0` would expose zero GPUs.
+GPU_FLAG=(--gpus "$GPUS")
+case "$GPUS" in
+ none) GPU_FLAG=() ;;
+ all|"") ;;
+ \"device=*) ;;
+ device=*,*) GPU_FLAG=(--gpus "\"${GPUS}\"") ;; # docker needs the quotes
+ device=*) ;; # single device, fine unquoted
+ *[!0-9]*) GPU_FLAG=(--gpus "\"device=${GPUS}\"") ;; # comma list / UUID
+ *) GPU_FLAG=(--gpus "\"device=${GPUS}\"") ;; # bare integer index
+esac
+HF_CACHE="${HF_HOME:-$HOME/.cache/huggingface}"
+TRITON_CACHE="${TRITON_CACHE_DIR:-$HOME/.cache/unsloth-triton}"
+WORK_DIR="${UNSLOTH_WORKDIR:-$PWD}"
+
+mkdir -p "$HF_CACHE" "$TRITON_CACHE"
+
+# Docker resolves --gpus in the DAEMON, before the container exists: on a host with
+# no NVIDIA GPU it dies with "failed to discover GPU vendor from CDI: no known GPU
+# vendor found" and exit 125, so entrypoint.sh never runs and its diagnostics never
+# print. Drop the flag instead and let the container start, so the user gets the
+# entrypoint's explanation (or, on :latest, Studio in CPU mode).
+# UNSLOTH_DEV_ROOT prefixes the /dev probes below (DESTDIR idiom). It exists so the
+# regression tests can stage a fake device tree; leave it unset in normal use.
+DEV_ROOT="${UNSLOTH_DEV_ROOT:-}"
+host_has_nvidia() {
+ [[ -e "$DEV_ROOT/dev/nvidiactl" ]] && return 0
+ command -v nvidia-smi >/dev/null 2>&1 \
+ && nvidia-smi -L 2>/dev/null | grep -q '^GPU' && return 0
+ return 1
+}
+
+if [[ ${#GPU_FLAG[@]} -gt 0 ]] && ! host_has_nvidia; then
+ printf "\033[1;33mWARN:\033[0m no NVIDIA GPU on this host; dropping --gpus %s.\n" "$GPUS" >&2
+ printf " 'docker run --gpus' would fail at the daemon (exit 125) before the\n" >&2
+ printf " container starts. Set UNSLOTH_GPUS=none to silence this.\n" >&2
+ GPU_FLAG=()
+ # AMD host: hand llama.cpp/GGUF the render nodes. This is NOT torch acceleration
+ # -- torch in the image is cu128 and torch.cuda.is_available() stays False here.
+ # --group-add needs NUMERIC gids: a name is resolved INSIDE the container, where
+ # the host's video/render groups do not exist.
+ if [[ -e "$DEV_ROOT/dev/kfd" && -d "$DEV_ROOT/dev/dri" ]]; then
+ GPU_FLAG=(--device /dev/kfd --device /dev/dri)
+ # A missing group is not fatal: getent exits nonzero when the name is not in
+ # NSS, and under `set -o pipefail` that would take the whole assignment down
+ # with `set -e` before docker run is ever reached. Trailing `|| _gid=` puts the
+ # assignment in an OR-list, which suppresses that and leaves the gid empty.
+ # Minimal hosts really do ship without a render group.
+ if command -v getent >/dev/null 2>&1; then
+ for _grp in video render; do
+ _gid="$(getent group "$_grp" | cut -d: -f3)" || _gid=""
+ [[ -n "$_gid" ]] && GPU_FLAG+=(--group-add "$_gid")
+ done
+ fi
+ printf " AMD devices found: passing /dev/kfd and /dev/dri through.\n" >&2
+ fi
+ printf "\n" >&2
+fi
+
+# warn, do not abort: some setups report runtimes differently
+if [[ ${#GPU_FLAG[@]} -gt 0 ]] && ! docker info 2>/dev/null | grep -qi 'Runtimes:.*nvidia'; then
+ printf "\033[1;33mWARN:\033[0m 'docker info' does not list 'nvidia' as a runtime.\n" >&2
+ printf " If --gpus all fails below, install nvidia-container-toolkit:\n" >&2
+ printf " https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/install-guide.html\n\n" >&2
+fi
+
+# Only if set, else an empty string shadows the image's. The dash-only `-e VAR` form
+# makes Docker read the value from the parent shell, so it never lands in argv.
+declare -a ENV_FORWARD=(-e HF_HUB_ENABLE_HF_TRANSFER=1)
+[[ -n "${HF_TOKEN:-}" ]] && ENV_FORWARD+=(-e HF_TOKEN)
+[[ -n "${WANDB_API_KEY:-}" ]] && ENV_FORWARD+=(-e WANDB_API_KEY)
+[[ -n "${UNSLOTH_LICENSE:-}" ]] && ENV_FORWARD+=(-e UNSLOTH_LICENSE)
+[[ -n "${UNSLOTH_ALLOW_CPU:-}" ]] && ENV_FORWARD+=(-e UNSLOTH_ALLOW_CPU)
+# read by studio_launch.sh; without these it uses a random password and no sshd
+[[ -n "${JUPYTER_PASSWORD:-}" ]] && ENV_FORWARD+=(-e JUPYTER_PASSWORD)
+[[ -n "${PUBLIC_KEY:-}" ]] && ENV_FORWARD+=(-e PUBLIC_KEY)
+[[ -n "${SSH_KEY:-}" ]] && ENV_FORWARD+=(-e SSH_KEY)
+[[ -n "${UNSLOTH_JUPYTER_CLOUDFLARE:-}" ]] && ENV_FORWARD+=(-e UNSLOTH_JUPYTER_CLOUDFLARE)
+
+declare -a PORT_FLAGS=()
+if [[ -n "${UNSLOTH_PORTS:-}" ]]; then
+ # shellcheck disable=SC2206 # intentional word splitting of "-p X -p Y"
+ PORT_FLAGS=(${UNSLOTH_PORTS})
+fi
+
+# CI / piped invocations otherwise hit "the input device is not a TTY"
+TTY_FLAG=()
+if [ -t 0 ] && [ -t 1 ]; then
+ TTY_FLAG=(-it)
+fi
+
+# No `set -x`: it would echo HF_TOKEN / WANDB_API_KEY to CI logs. The
+# ${arr[@]+"${arr[@]}"} form keeps empty arrays nounset-safe on bash 3.2 (macOS).
+exec docker run --rm ${TTY_FLAG[@]+"${TTY_FLAG[@]}"} \
+ ${GPU_FLAG[@]+"${GPU_FLAG[@]}"} \
+ --ipc=host \
+ --ulimit memlock=-1 \
+ --ulimit stack=67108864 \
+ -v "$HF_CACHE":/workspace/.cache/huggingface \
+ -v "$TRITON_CACHE":/workspace/.cache/triton \
+ -v "$WORK_DIR":/workspace/host \
+ "${ENV_FORWARD[@]}" \
+ ${PORT_FLAGS[@]+"${PORT_FLAGS[@]}"} \
+ "$IMAGE" "$@"
diff --git a/docker/smoke_test.py b/docker/smoke_test.py
new file mode 100644
index 00000000000..8fd1dfa1131
--- /dev/null
+++ b/docker/smoke_test.py
@@ -0,0 +1,154 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-Present the Unsloth team. See /studio/LICENSE.AGPL-3.0
+
+"""Smoke test for the unsloth-blackwell image: GPU + arch list, compute capability,
+the xformers / bitsandbytes / triton imports, unsloth, and a 5-step LoRA train.
+
+ docker run --rm --gpus all unsloth-blackwell:latest python /workspace/smoke_test.py
+ ... python /workspace/smoke_test.py --skip-train # skip the train step
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+
+def banner(title: str) -> None:
+ print(f"\n=== {title} ===", flush = True)
+
+
+def check_torch() -> tuple[int, int]:
+ banner("torch + arch list")
+ import torch
+
+ # the raw C++ accessor works without CUDA, so a no-GPU host still gets a check
+ arches = torch._C._cuda_getArchFlags().split()
+ print(f"torch {torch.__version__}")
+ print(f"cuda build {torch.version.cuda}")
+ print(f"arches {arches}")
+ assert "sm_100" in arches, f"sm_100 missing: {arches}"
+ assert "sm_120" in arches, f"sm_120 missing: {arches}"
+
+ assert torch.cuda.is_available(), "CUDA not visible -- did you pass --gpus all?"
+ cap = torch.cuda.get_device_capability(0)
+ name = torch.cuda.get_device_name(0)
+ print(f"device 0 {name} sm_{cap[0]}{cap[1]}")
+ # cu128 wheels ship SASS down to sm_75, so match the entrypoint floor
+ if cap[0] < 7 or (cap[0] == 7 and cap[1] < 5):
+ sys.exit(f"FAIL: pre-Turing GPU {name} is not supported by this image")
+ if cap[0] < 8:
+ print(f"NOTE: {name} is Turing (sm_{cap[0]}{cap[1]}) -- bf16 unavailable, fp16 fallback.")
+ return cap
+
+
+def check_imports() -> None:
+ banner("dep imports")
+ import triton
+
+ print(f"triton {triton.__version__}")
+ # unsloth first, so its patches land and unsloth_zoo sees UNSLOTH_IS_PRESENT
+ import unsloth
+
+ print(f"unsloth {unsloth.__version__}")
+ import unsloth_zoo
+
+ print(f"unsloth_zoo {unsloth_zoo.__version__}")
+ try:
+ import xformers
+ print(f"xformers {xformers.__version__}")
+ except ImportError:
+ print("xformers (missing -- expected on arm64 [huggingface] extras)")
+ import bitsandbytes as bnb
+
+ print(f"bnb {bnb.__version__}")
+ import transformers
+
+ print(f"transformers {transformers.__version__}")
+ import trl
+
+ print(f"trl {trl.__version__}")
+ import peft
+
+ print(f"peft {peft.__version__}")
+
+
+def check_unsloth_import() -> None:
+ banner("unsloth FastLanguageModel reachable")
+ import unsloth
+ from unsloth import FastLanguageModel
+
+ print(f"unsloth {unsloth.__version__}")
+ print(f"FastLanguageModel {FastLanguageModel}")
+
+
+def check_tiny_train(cap: tuple[int, int]) -> None:
+ banner("tiny LoRA train (5 steps)")
+ import os
+
+ import unsloth # noqa: F401
+ from unsloth import FastLanguageModel
+ import torch
+
+ model_name = "unsloth/Llama-3.2-1B-Instruct-bnb-4bit"
+ print(f"loading {model_name}")
+ model, tokenizer = FastLanguageModel.from_pretrained(
+ model_name = model_name,
+ max_seq_length = 512,
+ dtype = None,
+ load_in_4bit = True,
+ )
+ model = FastLanguageModel.get_peft_model(
+ model,
+ r = 8,
+ lora_alpha = 16,
+ target_modules = ["q_proj", "k_proj", "v_proj", "o_proj"],
+ lora_dropout = 0.0,
+ bias = "none",
+ use_gradient_checkpointing = "unsloth",
+ random_state = 0,
+ )
+
+ prompts = [
+ "Q: What is the capital of France?\nA:",
+ "Q: 2 + 2 = ?\nA:",
+ "Q: Name a primary color.\nA:",
+ "Q: Hello, who are you?\nA:",
+ ] * 2
+ enc = tokenizer(prompts, return_tensors = "pt", padding = True, truncation = True, max_length = 64)
+ enc = {k: v.cuda() for k, v in enc.items()}
+ labels = enc["input_ids"].clone()
+
+ model.train()
+ optim = torch.optim.AdamW([p for p in model.parameters() if p.requires_grad], lr = 1e-4)
+ for step in range(5):
+ out = model(**enc, labels = labels)
+ out.loss.backward()
+ optim.step()
+ optim.zero_grad(set_to_none = True)
+ print(f"step {step} loss={out.loss.item():.4f}", flush = True)
+
+ print("OK: 5 LoRA steps completed")
+
+
+def main() -> int:
+ ap = argparse.ArgumentParser()
+ ap.add_argument(
+ "--skip-train",
+ action = "store_true",
+ help = "Skip the tiny LoRA training step (no HF download).",
+ )
+ args = ap.parse_args()
+
+ cap = check_torch()
+ check_imports()
+ check_unsloth_import()
+ if not args.skip_train:
+ check_tiny_train(cap)
+
+ banner("all checks passed")
+ return 0
+
+
+if __name__ == "__main__":
+ sys.exit(main())
diff --git a/docker/studio_launch.sh b/docker/studio_launch.sh
new file mode 100644
index 00000000000..3b157c8904d
--- /dev/null
+++ b/docker/studio_launch.sh
@@ -0,0 +1,118 @@
+#!/usr/bin/env bash
+# Default CMD of the full Unsloth image (Dockerfile.studio).
+#
+# Bootstraps the three services managed by supervisord:
+# studio port 8000 first-boot admin password printed in `docker logs`
+# jupyter port 8888 password from JUPYTER_PASSWORD, or a random one
+# printed in `docker logs` when unset
+# sshd port 22 key-only; enabled when PUBLIC_KEY / SSH_KEY is set
+#
+# Environment:
+# JUPYTER_PORT Jupyter port inside the container (default 8888)
+# JUPYTER_PASSWORD Jupyter login password (unset: generated and printed)
+# PUBLIC_KEY/SSH_KEY OpenSSH public key for root login; sshd stays disabled
+# when neither is set (nothing to authenticate with --
+# password login is never enabled for root)
+set -euo pipefail
+
+export JUPYTER_PORT="${JUPYTER_PORT:-8888}"
+export UNSLOTH_STUDIO_HOME="${UNSLOTH_STUDIO_HOME:-/opt/unsloth-studio}"
+export UNSLOTH_JUPYTER_CLOUDFLARE="${UNSLOTH_JUPYTER_CLOUDFLARE:-0}"
+
+# SSH login shells lack the `docker run -e` vars. Secrets are excluded on purpose,
+# and every value is shlex.quote()d because this file is sourced by every login shell.
+python - > /etc/profile.d/unsloth_env.sh <<'PY' || true
+import os, re, shlex
+keep = re.compile(r"^(HF_|CUDA_|NCCL_|JUPYTER_|UNSLOTH_|WANDB_|TRITON_)|^PATH$")
+secret = re.compile(r"(_TOKEN|_API_KEY|_PASSWORD|_SECRET|_LICENSE)$")
+for key, value in sorted(os.environ.items()):
+ if keep.search(key) and not secret.search(key):
+ print(f"export {key}={shlex.quote(value)}")
+PY
+
+# never store plaintext, and never a fixed default: unset means random, printed once
+JUPYTER_CONFIG_DIR=/root/.jupyter
+JUPYTER_NOTE="password from JUPYTER_PASSWORD env"
+if [[ -f "${JUPYTER_CONFIG_DIR}/jupyter_lab_config.py" ]]; then
+ JUPYTER_NOTE="existing jupyter config reused"
+else
+ if [[ -z "${JUPYTER_PASSWORD:-}" ]]; then
+ JUPYTER_PASSWORD="$(python -c 'import secrets; print(secrets.token_urlsafe(12))')"
+ JUPYTER_NOTE="generated password: ${JUPYTER_PASSWORD}"
+ fi
+ export JUPYTER_PASSWORD
+ mkdir -p "${JUPYTER_CONFIG_DIR}"
+ HASH=$(python - <<PY
+from jupyter_server.auth import passwd
+import os
+print(passwd(os.environ["JUPYTER_PASSWORD"]))
+PY
+)
+ cat > "${JUPYTER_CONFIG_DIR}/jupyter_lab_config.py" <<EOF
+c.ServerApp.ip = "0.0.0.0"
+c.ServerApp.open_browser = False
+c.ServerApp.root_dir = "/workspace"
+c.PasswordIdentityProvider.hashed_password = "${HASH}"
+EOF
+ # mirror unsloth_sync_notebooks.sh's gating, or the view points at a missing dir
+ _root_dir="/workspace"
+ _view_dir="${UNSLOTH_NOTEBOOKS_VIEW_DIR:-/workspace/Unsloth Notebooks}"
+ if [[ "${UNSLOTH_SKIP_NOTEBOOK_VIEW:-0}" != "1" \
+ && "${UNSLOTH_SKIP_NOTEBOOK_SYNC:-0}" != "1" \
+ && "${_view_dir}" == "${_root_dir}/"* ]]; then
+ _view_rel="${_view_dir#${_root_dir}/}"
+ # default_url must be set on BOTH ServerApp and LabApp, or the lab app
+ # overrides ServerApp back to /lab.
+ #
+ # repr() rather than interpolation into a heredoc: a double quote in the
+ # path closed the string literal and made jupyter_lab_config.py a
+ # SyntaxError, so the documented override stopped the service starting,
+ # and a backslash silently changed the path. Both are legal POSIX
+ # characters. Values arrive via the environment, like the password block
+ # above, so the shell side needs no quoting either.
+ UNSLOTH_VIEW_REL="${_view_rel}" UNSLOTH_VIEW_DIR="${_view_dir}" \
+ python - >> "${JUPYTER_CONFIG_DIR}/jupyter_lab_config.py" <<'PY'
+import os
+rel = os.environ["UNSLOTH_VIEW_REL"]
+view = os.environ["UNSLOTH_VIEW_DIR"]
+print(f"c.ServerApp.default_url = {'/lab/tree/' + rel!r}")
+print(f"c.LabApp.default_url = {'/lab/tree/' + rel!r}")
+print(f"c.ServerApp.preferred_dir = {view!r}")
+PY
+ fi
+fi
+
+PUBLIC_SSH_KEY="${SSH_KEY:-${PUBLIC_KEY:-}}"
+export UNSLOTH_ENABLE_SSHD=false
+if [[ -n "${PUBLIC_SSH_KEY}" ]] && command -v sshd >/dev/null 2>&1; then
+ mkdir -p /root/.ssh && chmod 700 /root/.ssh
+ echo "${PUBLIC_SSH_KEY}" > /root/.ssh/authorized_keys
+ chmod 600 /root/.ssh/authorized_keys
+ ssh-keygen -A
+ mkdir -p /run/sshd
+ export UNSLOTH_ENABLE_SSHD=true
+fi
+
+mkdir -p /workspace
+
+# AGPLv3: refuse to start if the Unsloth attribution is stripped. The same checker
+# runs at build time and as a jupyter_server extension.
+if [[ "${UNSLOTH_SKIP_BRANDING_CHECK:-0}" != "1" ]]; then
+ if ! /opt/unsloth-venv/bin/python -m unsloth_branding --verify; then
+ echo "Refusing to start the container." >&2
+ exit 1
+ fi
+fi
+
+echo "Unsloth Studio -> http://localhost:8000 (first-boot password below)"
+echo "JupyterLab -> http://localhost:${JUPYTER_PORT} (${JUPYTER_NOTE})"
+if [[ "${UNSLOTH_JUPYTER_CLOUDFLARE}" == "1" ]]; then
+ echo "JupyterLab tunnel-> enabled; public trycloudflare URL appears below once it is up"
+else
+ echo "JupyterLab tunnel-> off (set UNSLOTH_JUPYTER_CLOUDFLARE=1 for a public link)"
+fi
+if [[ "${UNSLOTH_ENABLE_SSHD}" == "true" ]]; then
+ echo "sshd -> port 22 (key-only)"
+fi
+
+exec supervisord -c /etc/supervisor/supervisord.conf
diff --git a/docker/supervisord.conf b/docker/supervisord.conf
new file mode 100644
index 00000000000..9f7b5e7579f
--- /dev/null
+++ b/docker/supervisord.conf
@@ -0,0 +1,74 @@
+# Service manager for the full Unsloth image (Dockerfile.studio):
+# studio Unsloth Studio web UI port 8000
+# jupyter JupyterLab for the notebooks port $JUPYTER_PORT (default 8888)
+# sshd key-only SSH for cloud hosts port 22
+#
+# All three log to stdout/stderr so `docker logs` shows Studio's first-boot password
+# and Jupyter's startup line.
+
+[unix_http_server]
+file=/run/supervisor.sock
+chmod=0700
+
+[supervisorctl]
+serverurl=unix:///run/supervisor.sock
+
+[rpcinterface:supervisor]
+supervisor.rpcinterface_factory = supervisor.rpcinterface:make_main_rpcinterface
+
+[supervisord]
+nodaemon=true
+pidfile=/run/supervisord.pid
+logfile=/dev/null
+logfile_maxbytes=0
+loglevel=info
+
+[program:studio]
+command=%(ENV_UNSLOTH_STUDIO_HOME)s/bin/unsloth studio -H 0.0.0.0 -p 8000
+directory=/workspace
+autostart=true
+autorestart=true
+startretries=3
+startsecs=5
+environment=HOME="/root",USER="root"
+stdout_logfile=/dev/stdout
+stdout_logfile_maxbytes=0
+stderr_logfile=/dev/stderr
+stderr_logfile_maxbytes=0
+
+[program:jupyter]
+command=jupyter lab --no-browser --ip=0.0.0.0 --port=%(ENV_JUPYTER_PORT)s --allow-root --notebook-dir=/workspace
+directory=/workspace
+autostart=true
+autorestart=true
+; HOME pins config lookup to /root/.jupyter (where the launcher wrote the
+; password config); without it an unset HOME falls back to token auth.
+environment=HOME="/root",USER="root"
+stdout_logfile=/dev/stdout
+stdout_logfile_maxbytes=0
+stderr_logfile=/dev/stderr
+stderr_logfile_maxbytes=0
+
+; Optional public Cloudflare quick-tunnel for JupyterLab. Started only when
+; UNSLOTH_JUPYTER_CLOUDFLARE=1 (studio_launch.sh exports a 0 default so this
+; expands). The trycloudflare URL is printed to docker logs by cloudflared.
+[program:jupyter-cloudflare]
+command=/usr/local/bin/unsloth-jupyter-tunnel
+directory=/workspace
+autostart=%(ENV_UNSLOTH_JUPYTER_CLOUDFLARE)s
+autorestart=true
+startsecs=5
+environment=HOME="/root",USER="root"
+stdout_logfile=/dev/stdout
+stdout_logfile_maxbytes=0
+stderr_logfile=/dev/stderr
+stderr_logfile_maxbytes=0
+
+[program:sshd]
+command=/usr/sbin/sshd -D -e
+autostart=%(ENV_UNSLOTH_ENABLE_SSHD)s
+autorestart=true
+stdout_logfile=/dev/stdout
+stdout_logfile_maxbytes=0
+stderr_logfile=/dev/stderr
+stderr_logfile_maxbytes=0
diff --git a/docker/unsloth_colab_compat.py b/docker/unsloth_colab_compat.py
new file mode 100644
index 00000000000..63b91db2049
--- /dev/null
+++ b/docker/unsloth_colab_compat.py
@@ -0,0 +1,69 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-Present the Unsloth team. See /studio/LICENSE.AGPL-3.0
+
+"""Colab cell-magic compatibility for the Unsloth Docker notebooks.
+
+IPython recognises a cell magic only on the VERY FIRST line, so a leading Colab
+`#@title` form pushes `%%capture` to line 2 and the cell dies. An
+`input_transformers_cleanup`, which runs before magic detection, hoists it back.
+
+Restricted to magics whose body runs as code, where the moved-down comment stays
+inert; a content magic would write or render it.
+"""
+
+from __future__ import annotations
+import sys
+
+
+_SAFE_CELL_MAGICS = frozenset(
+ {
+ "capture",
+ "time",
+ "timeit",
+ "prun",
+ "debug",
+ "bash",
+ "sh",
+ "shell",
+ "python",
+ "python2",
+ "python3",
+ "pypy",
+ }
+)
+
+
+def colab_cell_magic_fix(lines):
+ """Hoist a safe `%%` cell magic above leading blank/comment lines."""
+ try:
+ skipped = []
+ for i, line in enumerate(lines):
+ stripped = line.strip()
+ if stripped == "" or stripped.startswith("#"):
+ skipped.append(line)
+ continue
+ if stripped.startswith("%%") and i > 0:
+ name = stripped[2:].split(maxsplit = 1)
+ name = name[0] if name else ""
+ if name in _SAFE_CELL_MAGICS:
+ return [line] + skipped + lines[i + 1 :]
+ # content/data magic: moving the comment into its body would render it
+ return lines
+ return lines
+ return lines
+ except Exception:
+ return lines
+
+
+def register_ipython():
+ try:
+ ip = get_ipython() # noqa: F821 (provided by IPython)
+ except NameError:
+ return
+ if ip is None or getattr(ip, "_unsloth_colab_fix", False):
+ return
+ try:
+ ip.input_transformers_cleanup.append(colab_cell_magic_fix)
+ ip._unsloth_colab_fix = True
+ except Exception as e: # never break a kernel because of the helper
+ print(f"[unsloth-nb] colab-compat hook skipped: {e!r}", file = sys.stderr)
diff --git a/docker/unsloth_ipython_startup.py b/docker/unsloth_ipython_startup.py
new file mode 100644
index 00000000000..1d67e0e8f69
--- /dev/null
+++ b/docker/unsloth_ipython_startup.py
@@ -0,0 +1,46 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-Present the Unsloth team. See /studio/LICENSE.AGPL-3.0
+
+"""Baked IPython startup hook (copied to the profile's startup/ dir).
+
+Runs once per kernel, registering a pre_run_cell event that activates the right
+transformers sidecar before the first model cell. Safe no-op outside IPython, with no
+version requested, or once transformers is already imported.
+"""
+
+try:
+ import os
+
+ os.environ["UNSLOTH_NB_SHIM"] = "1"
+
+ # per-kernel, so concurrent notebooks do not read each other's pin; the shim is
+ # a child, so writer and reader agree
+ if not os.environ.get("UNSLOTH_NB_TF_MARKER"):
+ _kid = ""
+ try:
+ from ipykernel import get_connection_file # type: ignore
+ _kid = os.path.splitext(os.path.basename(get_connection_file()))[0]
+ except Exception:
+ _kid = ""
+ _kid = _kid or ("pid-%d" % os.getpid())
+ os.environ["UNSLOTH_NB_TF_MARKER"] = "/tmp/unsloth_nb/requested_transformers." + _kid
+
+ import unsloth_nb_compat
+
+ unsloth_nb_compat.register_ipython()
+
+ # in-process installs would otherwise bypass the PATH shim entirely
+ import unsloth_nb_pip_magic
+
+ unsloth_nb_pip_magic.register_ipython()
+except Exception as _e: # never break a kernel because of the helper
+ import sys
+ print(f"[unsloth-nb] startup hook skipped: {_e!r}", file = sys.stderr)
+
+# separate try/except, so neither hook can disable the other
+try:
+ import unsloth_colab_compat
+ unsloth_colab_compat.register_ipython()
+except Exception as _e: # never break a kernel because of the helper
+ import sys
+ print(f"[unsloth-nb] colab-compat hook skipped: {_e!r}", file = sys.stderr)
diff --git a/docker/unsloth_jupyter_tunnel.sh b/docker/unsloth_jupyter_tunnel.sh
new file mode 100755
index 00000000000..52082c96e43
--- /dev/null
+++ b/docker/unsloth_jupyter_tunnel.sh
@@ -0,0 +1,58 @@
+#!/usr/bin/env bash
+# Optional public Cloudflare quick-tunnel for JupyterLab, mirroring the tunnel
+# Studio creates for its own UI. Off by default. Two ways to use it:
+#
+# * at run time: docker run -e UNSLOTH_JUPYTER_CLOUDFLARE=1 ... unsloth/unsloth
+# -> the https://<name>.trycloudflare.com URL is printed in
+# `docker logs` once JupyterLab is up.
+# * on demand: docker exec <container> unsloth-jupyter-tunnel --force
+#
+# The URL works from anywhere with no account or open inbound port. JupyterLab still
+# requires its password, but treat the URL as sensitive all the same.
+set -u
+
+FORCE=0
+[ "${1:-}" = "--force" ] && FORCE=1
+if [ "$FORCE" != "1" ] && [ "${UNSLOTH_JUPYTER_CLOUDFLARE:-0}" != "1" ]; then
+ echo "[jupyter-tunnel] disabled (set UNSLOTH_JUPYTER_CLOUDFLARE=1, or run with --force)"
+ exit 0
+fi
+
+PORT="${JUPYTER_PORT:-8888}"
+
+echo "[jupyter-tunnel] waiting for JupyterLab on port ${PORT} ..."
+for _ in $(seq 1 90); do
+ if curl -fsS -o /dev/null "http://localhost:${PORT}/login" 2>/dev/null; then
+ break
+ fi
+ sleep 2
+done
+
+# Studio caches a cloudflared for its own tunnel; otherwise fetch the static binary.
+CFD=""
+for cand in \
+ "${UNSLOTH_STUDIO_HOME:-/opt/unsloth-studio}/bin/cloudflared" \
+ /usr/local/bin/cloudflared \
+ cloudflared; do
+ if command -v "$cand" >/dev/null 2>&1; then CFD="$(command -v "$cand")"; break; fi
+ [ -x "$cand" ] && { CFD="$cand"; break; }
+done
+if [ -z "$CFD" ]; then
+ case "$(uname -m)" in
+ x86_64|amd64) A=amd64;;
+ aarch64|arm64) A=arm64;;
+ *) A=amd64;;
+ esac
+ CFD=/usr/local/bin/cloudflared
+ echo "[jupyter-tunnel] downloading cloudflared (${A}) ..."
+ if ! curl -fsSL -o "$CFD" \
+ "https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-${A}"; then
+ echo "[jupyter-tunnel] could not download cloudflared" >&2
+ exit 1
+ fi
+ chmod +x "$CFD"
+fi
+
+echo "[jupyter-tunnel] starting Cloudflare quick-tunnel to JupyterLab (port ${PORT})."
+echo "[jupyter-tunnel] the https://<name>.trycloudflare.com URL appears below; log in with your Jupyter password."
+exec "$CFD" tunnel --no-autoupdate --url "http://localhost:${PORT}"
diff --git a/docker/unsloth_llama_update.sh b/docker/unsloth_llama_update.sh
new file mode 100755
index 00000000000..a8641d8ea66
--- /dev/null
+++ b/docker/unsloth_llama_update.sh
@@ -0,0 +1,213 @@
+#!/usr/bin/env bash
+# Update the baked llama.cpp prebuilt in place, inside a running container,
+# without pulling a new image. Downloads the newest portable llama.cpp bundle
+# (the same target-pinned, sha256-verified bundle the image is built with) and
+# atomically swaps it into $UNSLOTH_LLAMA_CPP_PATH, so the next GGUF export /
+# model load uses it.
+#
+# docker exec <container> unsloth-llama-update # latest release
+# docker exec <container> unsloth-llama-update --tag b9773-mix-1f1aaa4
+# docker exec <container> unsloth-llama-update --check # report only, no download
+#
+# This reuses the build-time fetcher, which resolves the latest release via the
+# GitHub /releases/latest redirect (no API token, not rate-limited) and installs
+# the portable CUDA bundle that runs on CPU and every supported GPU. That makes
+# it work the same in a CPU-only or a --gpus container, unlike the host-probing
+# installer behind the in-app banner.
+#
+# Persistence: unmounted, the swap lands in the container's writable layer
+# (survives docker restart). To keep it across a full recreate, mount the dir
+# on a named volume (-v unsloth_llama:/opt/unsloth/llama.cpp); the updater
+# detects the mount and swaps the bundle contents inside the volume.
+set -euo pipefail
+
+INSTALL_DIR="${UNSLOTH_LLAMA_CPP_PATH:-/opt/unsloth/llama.cpp}"
+STUDIO_HOME="${UNSLOTH_STUDIO_HOME:-/opt/unsloth-studio}"
+FETCHER="${UNSLOTH_LLAMA_FETCHER:-/usr/local/lib/unsloth/fetch_llama_prebuilt.py}"
+REPO="unslothai/llama.cpp"
+TAG="latest"
+CHECK_ONLY=0
+
+usage() { sed -n '2,21p' "$0"; }
+
+while [ $# -gt 0 ]; do
+ case "$1" in
+ --tag) TAG="$2"; shift 2;;
+ --install-dir) INSTALL_DIR="$2"; shift 2;;
+ --check) CHECK_ONLY=1; shift;;
+ -h|--help) usage; exit 0;;
+ *) echo "unsloth-llama-update: unknown argument: $1" >&2; usage; exit 2;;
+ esac
+done
+
+[ -f "$FETCHER" ] || { echo "unsloth-llama-update: fetcher not found at $FETCHER" >&2; exit 1; }
+
+# the fetcher is stdlib-only, so any python works
+PY=""
+for cand in \
+ "$STUDIO_HOME/unsloth_studio/bin/python" \
+ /opt/unsloth-venv/bin/python \
+ python3 python; do
+ command -v "$cand" >/dev/null 2>&1 && { PY="$cand"; break; }
+ [ -x "$cand" ] && { PY="$cand"; break; }
+done
+[ -n "$PY" ] || { echo "unsloth-llama-update: no python found" >&2; exit 1; }
+
+# amd64 -> linux-x64-cuda12 portable; arm64 -> linux-arm64-cuda13 portable.
+case "$(uname -m)" in
+ x86_64|amd64) ARCH="amd64";;
+ aarch64|arm64) ARCH="arm64";;
+ *) echo "unsloth-llama-update: unsupported arch $(uname -m)" >&2; exit 1;;
+esac
+
+# The FULL "release_tag" is what --check compares against resolve_latest_tag; the
+# marker's "tag" is the normalized base build, so preferring it reports "an update is
+# available" forever on any install the in-app updater wrote.
+installed_tag() {
+ "$PY" - "$INSTALL_DIR" <<'PY' 2>/dev/null || echo "unknown"
+import json, os, sys
+p = os.path.join(sys.argv[1], "UNSLOTH_PREBUILT_INFO.json")
+try:
+ d = json.load(open(p)); print(d.get("release_tag") or d.get("tag") or d.get("upstream_tag") or "unknown")
+except Exception:
+ print("unknown")
+PY
+}
+
+resolve_latest() {
+ "$PY" - "$FETCHER" "$REPO" <<'PY' 2>/dev/null || echo ""
+import importlib.util, sys
+spec = importlib.util.spec_from_file_location("flp", sys.argv[1])
+m = importlib.util.module_from_spec(spec); spec.loader.exec_module(m)
+print(m.resolve_latest_tag(sys.argv[2]))
+PY
+}
+
+CUR="$(installed_tag)"
+echo "[llama-update] install dir: $INSTALL_DIR"
+echo "[llama-update] installed: $CUR"
+
+if [ "$CHECK_ONLY" = "1" ]; then
+ LATEST="$(resolve_latest)"
+ echo "[llama-update] latest: ${LATEST:-unknown}"
+ # resolve_latest swallows every failure into "", so an empty value means the
+ # lookup never happened; "up to date" would report a state it could not observe
+ if [ -z "$LATEST" ]; then
+ echo "[llama-update] could not reach the release feed; update status UNKNOWN" >&2
+ echo "[llama-update] (retry once the container has network access)" >&2
+ exit 1
+ fi
+ if [ "$LATEST" != "$CUR" ]; then
+ echo "[llama-update] an update is available (run without --check to apply)"
+ else
+ echo "[llama-update] up to date"
+ fi
+ exit 0
+fi
+
+# a sibling temp dir is on the same filesystem, so the swap is an atomic rename
+parent="$(dirname "$INSTALL_DIR")"
+
+# A named volume mounted AT the install dir cannot be renamed (EBUSY), so swap its
+# CONTENTS instead. UNSLOTH_LLAMA_UPDATE_IN_PLACE=1/0 overrides autodetection.
+IN_PLACE="${UNSLOTH_LLAMA_UPDATE_IN_PLACE:-}"
+if [ -z "$IN_PLACE" ]; then
+ IN_PLACE=0
+ if command -v mountpoint >/dev/null 2>&1 && mountpoint -q "$INSTALL_DIR" 2>/dev/null; then
+ IN_PLACE=1
+ elif [ "$(stat -c %d "$INSTALL_DIR" 2>/dev/null)" != "$(stat -c %d "$parent" 2>/dev/null)" ]; then
+ IN_PLACE=1 # filesystem boundary = a volume, on hosts without mountpoint(1)
+ fi
+fi
+if [ "$IN_PLACE" = "1" ]; then
+ # work + backup live UNDER the install dir, so every swap step is a same-fs rename
+ work="$(mktemp -d "$INSTALL_DIR/.llamaupd.XXXXXX")"
+ backup="$INSTALL_DIR/.old.$$"
+else
+ work="$(mktemp -d "$parent/.llamaupd.XXXXXX")"
+ backup="${INSTALL_DIR}.old.$$"
+fi
+swap_done=0
+drained=0
+# The exit handler must never delete $backup while it is the ONLY copy: restore
+# first, remove only once the new tree is active.
+cleanup() {
+ if [ "$swap_done" -ne 1 ]; then
+ if [ "$IN_PLACE" = "1" ]; then
+ # every old entry lives in exactly one of $backup / $INSTALL_DIR, so a
+ # same-named entry in the install dir is a half-moved NEW one
+ if [ -d "$backup" ]; then
+ _restore_fail=0
+ # The loop below only sees names the OLD tree had, so a file the
+ # new release introduced would survive into a mixed-version dir and
+ # ggml dlopens every libggml-*.so next to the binaries. Gated on
+ # "drained": before that, an entry here can be the only old copy.
+ if [ "$drained" = "1" ]; then
+ find "$INSTALL_DIR" -mindepth 1 -maxdepth 1 \
+ ! -path "$work" ! -path "$backup" \
+ -exec rm -rf {} + 2>/dev/null || true
+ fi
+ for _e in "$backup"/* "$backup"/.[!.]* "$backup"/..?*; do
+ { [ -e "$_e" ] || [ -L "$_e" ]; } || continue
+ _b="$(basename "$_e")"
+ if [ -e "$INSTALL_DIR/$_b" ] || [ -L "$INSTALL_DIR/$_b" ]; then
+ rm -rf "${INSTALL_DIR:?}/$_b" 2>/dev/null || true
+ fi
+ mv "$_e" "$INSTALL_DIR/" 2>/dev/null || _restore_fail=1
+ done
+ if [ "$_restore_fail" -eq 0 ]; then
+ rmdir "$backup" 2>/dev/null || true
+ else
+ echo "[llama-update] CRITICAL: restore failed; previous install preserved at $backup" >&2
+ fi
+ fi
+ elif [ ! -e "$INSTALL_DIR" ] && [ -e "$backup" ]; then
+ if ! mv "$backup" "$INSTALL_DIR" 2>/dev/null; then
+ echo "[llama-update] CRITICAL: restore failed; previous install preserved at $backup" >&2
+ fi
+ fi
+ fi
+ rm -rf "$work" 2>/dev/null || true
+ if [ "$swap_done" = "1" ]; then
+ rm -rf "$backup" 2>/dev/null || true
+ fi
+}
+trap cleanup EXIT
+trap 'exit 129' HUP
+trap 'exit 130' INT
+trap 'exit 143' TERM
+new="$work/llama.cpp"
+
+echo "[llama-update] fetching llama.cpp '$TAG' ($ARCH portable) ..."
+"$PY" "$FETCHER" "$TAG" "$ARCH" "$new"
+
+# preserve the Studio ownership marker so setup.sh keeps recognising the dir
+[ -e "$INSTALL_DIR/.unsloth-studio-owned" ] && touch "$new/.unsloth-studio-owned"
+
+echo "[llama-update] swapping into place ..."
+if [ "$IN_PLACE" = "1" ]; then
+ mkdir "$backup"
+ find "$INSTALL_DIR" -mindepth 1 -maxdepth 1 \
+ ! -path "$work" ! -path "$backup" -exec mv -t "$backup" {} +
+ # every old entry is now in $backup, so from here the trap may clear the install
+ # dir before restoring; set -e means a failed drain never reaches this
+ drained=1
+ if find "$new" -mindepth 1 -maxdepth 1 -exec mv -t "$INSTALL_DIR" {} +; then
+ swap_done=1
+ else
+ echo "[llama-update] swap failed; restoring previous install" >&2
+ exit 1
+ fi
+else
+ mv "$INSTALL_DIR" "$backup"
+ if mv "$new" "$INSTALL_DIR"; then
+ swap_done=1
+ else
+ echo "[llama-update] swap failed; restoring previous install" >&2
+ mv "$backup" "$INSTALL_DIR"
+ exit 1
+ fi
+fi
+
+echo "[llama-update] installed now: $(installed_tag)"
+echo "[llama-update] done (reload your model / re-run export to use it)"
diff --git a/docker/unsloth_nb_compat.py b/docker/unsloth_nb_compat.py
new file mode 100644
index 00000000000..40f012aadb9
--- /dev/null
+++ b/docker/unsloth_nb_compat.py
@@ -0,0 +1,342 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-Present the Unsloth team. See /studio/LICENSE.AGPL-3.0
+
+"""Per-notebook transformers version activation for the Unsloth Docker image.
+
+The image bakes coherent transformers "sidecars" and prepends one to sys.path before
+transformers is imported. Mirrors studio/backend/utils/transformers_version.py.
+
+Selection has a FLOOR as well as a ceiling (see sidecar_for): vLLM is version-locked
+to transformers, so a sidecar older than the baked vLLM accepts is not an older
+transformers, it is an ImportError at `import unsloth`.
+"""
+
+from __future__ import annotations
+import os, sys, glob, json, re, shlex
+
+SIDECAR_ROOT = os.environ.get("UNSLOTH_TF_SIDECAR_ROOT", "/opt/unsloth-venv/tf-sidecars")
+MARKER = os.environ.get("UNSLOTH_NB_TF_MARKER", "/tmp/unsloth_nb/requested_transformers")
+
+# Lowest transformers the baked vLLM can import. Written by the Dockerfile's sidecar
+# verification step, so it tracks the vLLM the image bakes rather than a literal.
+FLOOR_FILE = os.path.join(SIDECAR_ROOT, ".vllm_min_transformers")
+
+
+def _logging_enabled() -> bool:
+ """Sidecar activation is silent by default; UNSLOTH_ENABLE_LOGGING=1 surfaces it."""
+ return os.environ.get("UNSLOTH_ENABLE_LOGGING", "").strip().lower() not in (
+ "",
+ "0",
+ "false",
+ "no",
+ "off",
+ )
+
+
+# fallback when a notebook names a new model but pins nothing; ported from Studio
+_TIER_SUBSTRINGS = {
+ "5.10.2": ("gemma-4-12b", "gemma4-12b"),
+ "5.5.0": ("gemma-4", "gemma4", "qwen3.6"),
+ "5.3.0": (
+ "ministral-3",
+ "glm-4.7-flash",
+ "qwen3-30b-a3b",
+ "qwen3.5",
+ "qwen3-next",
+ "qwen3_5",
+ "lfm2.5-vl",
+ ),
+}
+
+
+def _baked():
+ out = {}
+ for d in sorted(glob.glob(os.path.join(SIDECAR_ROOT, "t_*"))):
+ out[os.path.basename(d)[2:].replace("_", ".")] = d
+ return out
+
+
+def min_version():
+ """Lowest transformers this image's vLLM can import; None keeps the pre-floor
+ behaviour. UNSLOTH_TF_SIDECAR_MIN overrides."""
+ v = os.environ.get("UNSLOTH_TF_SIDECAR_MIN", "").strip()
+ if v:
+ return v
+ try:
+ with open(FLOOR_FILE) as f:
+ return f.read().strip() or None
+ except OSError:
+ return None
+
+
+def _eligible():
+ baked = _baked()
+ if not baked:
+ return []
+ try:
+ from packaging.version import Version
+ except Exception:
+ return None
+ floor = min_version()
+ try:
+ low = Version(floor) if floor else None
+ except Exception:
+ low = None
+ rows = []
+ for v, d in baked.items():
+ try:
+ ver = Version(v)
+ except Exception:
+ continue
+ if low is not None and ver < low:
+ continue # vLLM cannot import it
+ rows.append((ver, v, d))
+ rows.sort()
+ return rows
+
+
+def tier_for_model(model_name: str):
+ if not model_name:
+ return None
+ low = model_name.lower()
+ # newest tiers first, so gemma-4-12b wins over gemma-4
+ for ver in ("5.10.2", "5.5.0", "5.3.0"):
+ if any(s in low for s in _TIER_SUBSTRINGS[ver]):
+ return ver
+ return None
+
+
+def sidecar_for(version: str):
+ """FLOOR then CEILING: a sidecar the baked vLLM cannot import is never eligible
+ whatever the notebook pinned, so a request below the floor clamps UP; among the
+ eligible ones take the smallest >= the request, since a model added in X needs at
+ least X. Above every eligible sidecar returns None, i.e. the base venv."""
+ if not version:
+ return None
+ rows = _eligible()
+ if rows is None: # no packaging: only an exact, still-eligible match is safe
+ baked = _baked()
+ d = baked.get(version)
+ floor = min_version()
+ return d if (d and (not floor or version == floor)) else None
+ if not rows:
+ return None
+ for _ver, v, d in rows:
+ if v == version:
+ return d
+ try:
+ from packaging.version import Version
+ want = Version(version)
+ except Exception:
+ return None
+ for ver, _v, d in rows:
+ if ver >= want:
+ return d
+ return None
+
+
+def requested_version():
+ try:
+ with open(MARKER) as f:
+ v = f.read().strip()
+ return v or None
+ except OSError:
+ return None
+
+
+# --- install-cell pin scanning -------------------------------------------------
+# Lives here rather than in unsloth_run because this module is the one copied into
+# site-packages, so it is the only one a kernel can import; unsloth_run reads these
+# back out. One implementation, so the headless path and the IPython hook cannot
+# disagree about what an install line is.
+
+# The requirement NAME is matched loosely and normalised afterwards, because pip
+# accepts every PEP 503 spelling of it and unsloth_pip_shim canonicalises before it
+# decides what to drop. `Transformers==5.5.0` and `transformers[torch]==5.5.0` install
+# exactly what the canonical spelling installs and the shim drops all three, so a
+# scanner that only knew the canonical form left the pin unseen while the install was
+# still suppressed. The cell then imported the base version, and that import freezes
+# the sidecar choice for the life of the kernel with nothing left to correct it.
+_PIN_RE = re.compile(
+ r"(?<![\w.\-])([A-Za-z0-9][A-Za-z0-9._\-]*)[ \t]*(?:\[[^\]]*\])?[ \t]*=="
+ r"[ \t]*([0-9][0-9A-Za-z.\-]*)"
+)
+
+
+def _norm_req(name):
+ """PEP 503 normalised distribution name, the rule unsloth_pip_shim._norm_name uses."""
+ return re.sub(r"[-_.]+", "-", name.strip()).lower()
+
+
+def _marker_skipped_versions(lines):
+ """transformers versions on these lines whose PEP 508 marker is FALSE here.
+
+ Both real tools skip such a requirement entirely ("Ignoring transformers: markers
+ ... don't match your environment"), so nothing is installed and no sidecar should
+ be activated for it. Splitting the way a shell does is the point: only a QUOTED
+ requirement reaches pip carrying its marker, while `pip install pkg==1; marker`
+ unquoted is cut at the `;` by the shell and really is an unconditional pin.
+
+ packaging is optional here, exactly as it is for the version ordering above, so a
+ missing or unparsable requirement simply yields no veto and the old behaviour."""
+ skipped = set()
+ try:
+ from packaging.requirements import Requirement
+ except Exception:
+ return skipped
+ for line in lines.splitlines():
+ try:
+ tokens = shlex.split(line, posix = True)
+ except ValueError:
+ continue
+ for tok in tokens:
+ try:
+ req = Requirement(tok)
+ if _norm_req(req.name) != "transformers" or req.marker is None:
+ continue
+ if req.marker.evaluate():
+ continue
+ except Exception:
+ continue
+ for spec in req.specifier:
+ if spec.operator == "==":
+ skipped.add(spec.version)
+ return skipped
+
+
+def pin_from(text):
+ """transformers version pinned by an install command in `text`, else None."""
+ lines = _install_lines(text)
+ skipped = _marker_skipped_versions(lines)
+ for m in _PIN_RE.finditer(lines):
+ if _norm_req(m.group(1)) == "transformers" and m.group(2) not in skipped:
+ return m.group(2)
+ return None
+
+
+# Only an actual install invocation may supply the pin: the pin outranks the model
+# tier, so a commented-out install line would pick the wrong sidecar with nothing
+# running afterwards to correct it.
+_INSTALL_RE = re.compile(
+ r"""^[ \t]*(?![ \t]*\#)[!%]?[ \t]*
+ (?: uv (?:[ \t]+-{1,2}\S+)* [ \t]+ )?
+ (?: \S+ [ \t]+ -m [ \t]+ )?
+ pip[0-9.]* [ \t]+
+ (?: -{1,2}\S+ [ \t]+ )*
+ install (?: [ \t] | $ )""",
+ re.VERBOSE,
+)
+
+
+def _strip_comment(line):
+ """Drop a trailing `# ...` from a shell/magic line. Only a `#` starting a token
+ counts, so a `git+https://...#egg=` fragment survives, as does a quoted #."""
+ quote = None
+ for i, ch in enumerate(line):
+ if quote:
+ if ch == quote:
+ quote = None
+ elif ch in "'\"":
+ quote = ch
+ elif ch == "#" and (i == 0 or line[i - 1].isspace()):
+ return line[:i]
+ return line
+
+
+# A triple-quoted body is data, not code. Blanked keeping newlines, so the
+# continuation logic below is unaffected.
+_TRIPLE_RE = re.compile(r'("""|\'\'\')(?:.|\n)*?\1')
+
+
+def _live_source(src):
+ """Triple-quoted bodies and comments blanked out. Single-quoted strings stay
+ intact: the model name unsloth_run scans for lives inside one."""
+ blanked = _TRIPLE_RE.sub(lambda m: re.sub(r"[^\n]", " ", m.group(0)), src)
+ return "\n".join(_strip_comment(line) for line in blanked.splitlines())
+
+
+def _install_lines(src):
+ kept, cont = [], False
+ for line in src.splitlines():
+ if cont or _INSTALL_RE.match(line):
+ code = _strip_comment(line)
+ kept.append(code)
+ cont = code.rstrip().endswith("\\")
+ else:
+ cont = False
+ return "\n".join(kept)
+
+
+def pin_in_cell(source):
+ """transformers version pinned by an install command IN this cell, else None.
+
+ Same scan unsloth_run runs over a whole notebook, applied to one cell. Anything
+ that installs nothing has to lose: once transformers is imported the sidecar
+ choice is frozen for the life of the kernel, so a wrong guess is unrecoverable
+ while no guess merely leaves the base venv."""
+ if not source:
+ return None
+ return pin_from(_live_source(source))
+
+
+def activate(version: str | None, *, quiet: bool = False):
+ """Prepend the matching sidecar to sys.path, if transformers is not imported yet."""
+ if not version:
+ return None
+ d = sidecar_for(version)
+ if not d:
+ return None
+ if "transformers" in sys.modules:
+ if not quiet:
+ print(
+ f"[unsloth-nb] transformers already imported; cannot switch to "
+ f"{version} in-process (restart the kernel, or use `unsloth-run`).",
+ file = sys.stderr,
+ )
+ return None
+ if d not in sys.path:
+ sys.path.insert(0, d)
+ # guarded like the sys.path insert above: the hook runs on EVERY cell until
+ # transformers is imported, so an unconditional prepend grows PYTHONPATH by one
+ # copy per cell and every child process inherits the pile
+ _pp = os.environ.get("PYTHONPATH", "")
+ if d not in _pp.split(os.pathsep):
+ os.environ["PYTHONPATH"] = d + os.pathsep + _pp
+ if not quiet and _logging_enabled():
+ print(f"[unsloth-nb] activated transformers sidecar for {version}: {d}")
+ return d
+
+
+def resolve(model_name: str | None = None):
+ return requested_version() or tier_for_model(model_name or "")
+
+
+def _pre_run_cell(info = None):
+ """Activate before the cell's first statement runs.
+
+ The marker is the shim's record of a PREVIOUS cell's install, so it cannot help a
+ cell that installs and then imports in one go: the shim writes it from a child
+ process partway through that same cell, long after this hook has returned. Reading
+ the pin out of the cell we are about to run covers that shape, which is how the
+ notebooks pin a new model. Without it the cell silently ran the base transformers
+ and every later cell got "already imported; cannot switch"."""
+ if "transformers" in sys.modules:
+ return
+ # The cell's own pin outranks the marker, which is a record of an install that has
+ # ALREADY run. Within one notebook a later cell can pin a different version, and
+ # the marker still holds the earlier one; the marker path also falls back to
+ # pid-<pid> when the ipykernel connection file cannot be read, and /tmp is never
+ # swept, so a recycled pid inherits someone else's pin.
+ v = pin_in_cell(getattr(info, "raw_cell", None)) or requested_version()
+ if v:
+ activate(v)
+
+
+def register_ipython():
+ try:
+ ip = get_ipython() # noqa: F821 (provided by IPython)
+ except NameError:
+ return
+ if ip is not None and not getattr(ip, "_unsloth_tf_hook", False):
+ ip.events.register("pre_run_cell", _pre_run_cell)
+ ip._unsloth_tf_hook = True
diff --git a/docker/unsloth_nb_content_sig.py b/docker/unsloth_nb_content_sig.py
new file mode 100644
index 00000000000..9bd5339a34d
--- /dev/null
+++ b/docker/unsloth_nb_content_sig.py
@@ -0,0 +1,247 @@
+#!/usr/bin/env python3
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-Present the Unsloth team. See /studio/LICENSE.AGPL-3.0
+
+import hashlib
+import json
+import re
+import sys
+
+_BOILERPLATE_MD = (
+ "to run this, press",
+ 'press "*runtime*"',
+ "### news",
+ "introducing **unsloth studio**",
+ "you will learn how to do",
+ "this notebook is licensed",
+ "and we're done",
+ "this notebook and all unsloth notebooks are licensed",
+ "join discord if you need help",
+ "star us on",
+ "some other resources",
+)
+
+
+def _text(cell):
+ src = cell.get("source", "")
+ if isinstance(src, list):
+ src = "".join(src)
+ return src.replace("\r\n", "\n").replace("\r", "\n")
+
+
+_INSTALL_MARKERS = (
+ "pip install",
+ "pip3-autoremove",
+ "uv pip install",
+ "conda install",
+ "apt-get install",
+ "apt install",
+)
+
+
+_MAGIC_INSTALL = ("%pip", "%uv", "%conda")
+
+
+def _is_shell_cell(text):
+ """A `%%bash` / `%%sh` cell magic makes every line of the cell a shell command."""
+ for line in text.split("\n"):
+ s = line.strip()
+ if s:
+ return s.startswith(("%%bash", "%%sh", "%%script"))
+ return False
+
+
+def _unquoted(line):
+ """`line` with every quoted stretch blanked, so a marker inside a string literal
+ cannot be read as a command. Length is preserved; only the characters change."""
+ out = []
+ quote = None
+ for ch in line:
+ if quote:
+ out.append(" ")
+ if ch == quote:
+ quote = None
+ elif ch in "'\"":
+ quote = ch
+ out.append(" ")
+ else:
+ out.append(ch)
+ return "".join(out)
+
+
+# Shell command separators. A marker right after one of these begins a command; the
+# same words anywhere else on the segment are an argument or an operand.
+_SEG_RE = re.compile(r"\|\||&&|[;&|(){}`]")
+
+# Words that may stand in front of a command without changing what the command is.
+_CMD_PREFIXES = ("sudo", "env", "time", "nohup", "xargs", "then", "do", "else", "!")
+
+_PY_DASH_M = re.compile(r"^\S*python[0-9.]* -m ")
+
+
+def _starts_command(segment):
+ """True when `segment` invokes an install marker rather than merely naming one."""
+ s = " ".join(segment.split())
+ while True:
+ head = s.split(" ", 1)
+ if len(head) != 2:
+ break
+ # a leading `VAR=value` is a per-command environment, not the command
+ if head[0] in _CMD_PREFIXES or re.match(r"^[A-Za-z_][A-Za-z0-9_]*=", head[0]):
+ s = head[1]
+ continue
+ break
+ return _PY_DASH_M.sub("", s).startswith(_INSTALL_MARKERS)
+
+
+def _is_install_line(line, shell):
+ """A real install invocation rather than a mention of one: `!`, a `%pip`-family
+ magic, or a command position inside a shell cell. On an ordinary Python line the
+ same words are prose or data, and treating the cell as an install cell on that
+ basis put four shipped notebooks through the flattening below over a comment (see
+ tests/python/test_docker_nb_install_cell_sig.py).
+
+ A `%%bash` cell used to qualify on the whole line, which is the same mistake one
+ level down: `msg="pip install foo # bar"` counted, and _normalize_install then
+ stripped the quoted `# bar` and collapsed the rest, so editing that string upstream
+ produced SAME and the refresh kept the old shell behaviour. Quoted stretches are
+ blanked and the marker has to open a command, which every one of the 1064 marker
+ lines in the 561 shipped notebooks already does."""
+ low = _unquoted(line.lower())
+ if not any(m in low for m in _INSTALL_MARKERS):
+ return False
+ s = low.lstrip()
+ if s.startswith("!") or s.startswith(_MAGIC_INSTALL):
+ return True
+ return shell and any(_starts_command(seg) for seg in _SEG_RE.split(low))
+
+
+def _is_install_code(cell):
+ if cell.get("cell_type") != "code":
+ return False
+ t = _text(cell)
+ shell = _is_shell_cell(t)
+ return any(_is_install_line(line, shell) for line in t.split("\n"))
+
+
+def _is_boilerplate_md(cell):
+ if cell.get("cell_type") != "markdown":
+ return False
+ low = _text(cell).lower()
+ return any(m in low for m in _BOILERPLATE_MD)
+
+
+def _strip_comment(line):
+ """`line` with its trailing shell comment removed. POSIX starts a comment only on
+ a `#` that OPENS an unquoted token, so two kinds of `#` are data:
+
+ - one glued to the previous token, as in the `#subdirectory=pkg` fragment of
+ `pip install "git+https://host/repo#subdirectory=pkg"`, which selects the
+ package;
+ - one inside a string literal, which a compound install line carries whenever
+ it chains code after the install:
+ `!pip install foo && python -c 'print("a # b")' && pip install bar==2.0`.
+ Cutting at that `#` dropped the rest of the line, so an upstream bump of
+ `bar` hashed the same and the refresh kept the stale notebook. The quote rule
+ is the one `_is_install_line` already applies through `_unquoted`.
+
+ An unterminated quote keeps the whole line: a shell would not treat its tail as a
+ comment either, and keeping bytes can only ever say DIFF."""
+ quote = None
+ for i, ch in enumerate(line):
+ if quote:
+ if ch == quote:
+ quote = None
+ elif ch in "'\"":
+ quote = ch
+ elif ch == "#" and (i == 0 or line[i - 1].isspace()):
+ return line[:i]
+ return line
+
+
+def _normalize_install(text):
+ """Drop the cosmetic half of an install cell, keep what it installs. Its package
+ specs are functional and the image keys its transformers sidecar off them, so
+ skipping the whole cell hid an upstream fix forever: SAME keeps the old file AND
+ re-records its old hash.
+
+ Only the install COMMANDS are flattened. Three quarters of the install cells in
+ unslothai/notebooks carry ordinary Python or shell around the install, and
+ flattening that as well made a `#` or a run of spaces inside a string literal
+ cosmetic. A non-install line therefore keeps its bytes, unless it is blank or a
+ whole-line comment, or it contains no quote and no `#` at all and so has nowhere
+ for whitespace to be data."""
+ shell = _is_shell_cell(text)
+ lines = []
+ for raw in text.split("\n"):
+ if _is_install_line(raw, shell):
+ line = _strip_comment(raw)
+ else:
+ stripped = raw.strip()
+ if not stripped or stripped.startswith("#"):
+ continue
+ if any(ch in raw for ch in ('"', "'", "#")):
+ lines.append(raw)
+ continue
+ line = raw
+ body = " ".join(line.split())
+ if not body:
+ continue
+ # Keep the INDENTATION: the cell is an `if "COLAB_" not in ...:` block, so a
+ # line's indent decides which runtime it runs on. Only the spacing WITHIN a
+ # line churns, and tabs expand so a tab/space rewrite stays cosmetic.
+ indent = line[: len(line) - len(line.lstrip())]
+ lines.append(" " * len(indent.expandtabs(4)) + body)
+ return "\n".join(lines)
+
+
+def middle_digest(path):
+ """sha256 over the (type, source) of every non-boilerplate cell, or None."""
+ try:
+ with open(path, "r", encoding = "utf-8") as f:
+ nb = json.load(f)
+ except Exception:
+ return None
+ cells = nb.get("cells")
+ if not isinstance(cells, list):
+ return None
+ h = hashlib.sha256()
+ for cell in cells:
+ if not isinstance(cell, dict):
+ continue
+ if _is_boilerplate_md(cell):
+ continue
+ text = _text(cell)
+ if _is_install_code(cell):
+ text = _normalize_install(text)
+ h.update(b"\x00")
+ h.update(str(cell.get("cell_type", "")).encode("utf-8"))
+ h.update(b"\x01")
+ h.update(text.encode("utf-8"))
+ return h.hexdigest()
+
+
+def main(argv):
+ if len(argv) == 2:
+ d = middle_digest(argv[1])
+ if d is None:
+ print("ERR")
+ return 0
+ print(d)
+ return 0
+ if len(argv) == 3:
+ a = middle_digest(argv[1])
+ b = middle_digest(argv[2])
+ if a is None or b is None:
+ print("ERR")
+ elif a == b:
+ print("SAME")
+ else:
+ print("DIFF")
+ return 0
+ print("ERR")
+ return 0
+
+
+if __name__ == "__main__":
+ sys.exit(main(sys.argv))
diff --git a/docker/unsloth_nb_pip_magic.py b/docker/unsloth_nb_pip_magic.py
new file mode 100644
index 00000000000..3209a627b42
--- /dev/null
+++ b/docker/unsloth_nb_pip_magic.py
@@ -0,0 +1,69 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-Present the Unsloth team. See /studio/LICENSE.AGPL-3.0
+
+"""Route notebook `%pip` / `%uv` / `python -m pip` installs through the shim.
+
+The PATH shim only intercepts `!pip` shell cells, but `%pip` runs pip in-process and
+`python -m pip` runs it as a module. `%pip` / `%pip3` / `%uv` are re-registered as
+line magics that delegate to the shell -- overriding the MAGIC, not rewriting cell
+text, so a `%pip` inside a string is untouched -- and an input transformer rewrites
+an explicit `!python -m pip` line to `!pip`.
+"""
+
+import re
+
+# Transformers see the RAW cell text (IPython expands `{sys.executable}` later), so
+# the braced form and quoted/bare interpreter paths must be matched here too.
+_PY_M_PIP = re.compile(
+ r"""^(\s*)!\s*
+ (?:
+ (?:python[0-9.]*|py) # literal python / py
+ | ["']?\{\s*sys\.executable\s*\}["']? # {sys.executable}, opt. quoted
+ | "(?:[^"]*[/\\])python[0-9.]*(?:\.exe)?" # quoted interpreter path
+ | '(?:[^']*[/\\])python[0-9.]*(?:\.exe)?'
+ | \S*[/\\]python[0-9.]*(?:\.exe)? # bare interpreter path
+ )
+ \s+-m\s+(pip|uv)\b(.*)$""",
+ re.VERBOSE,
+)
+
+
+def _rewrite_python_dash_m(lines):
+ """`!python -m pip install X` -> `!pip install X`, which hits the PATH shim."""
+ try:
+ out = []
+ for line in lines:
+ body = line.rstrip("\n")
+ tail = line[len(body) :] # keep the trailing newline(s)
+ m = _PY_M_PIP.match(body)
+ if m:
+ out.append(m.group(1) + "!" + m.group(2) + m.group(3) + tail)
+ else:
+ out.append(line)
+ return out
+ except Exception:
+ return lines
+
+
+def register_ipython():
+ try:
+ ip = get_ipython() # noqa: F821 (provided by IPython)
+ except Exception:
+ ip = None
+ if ip is None or getattr(ip, "_unsloth_pip_magic", False):
+ return
+
+ def _make(tool):
+ def _magic(line):
+ return ip.system(tool + " " + line)
+
+ return _magic
+
+ ip.register_magic_function(_make("pip"), "line", "pip")
+ ip.register_magic_function(_make("pip"), "line", "pip3")
+ ip.register_magic_function(_make("uv"), "line", "uv")
+
+ if _rewrite_python_dash_m not in ip.input_transformers_cleanup:
+ ip.input_transformers_cleanup.append(_rewrite_python_dash_m)
+
+ ip._unsloth_pip_magic = True
diff --git a/docker/unsloth_nb_strip_colab.py b/docker/unsloth_nb_strip_colab.py
new file mode 100644
index 00000000000..635b0cf602c
--- /dev/null
+++ b/docker/unsloth_nb_strip_colab.py
@@ -0,0 +1,326 @@
+#!/usr/bin/env python3
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-Present the Unsloth team. See /studio/LICENSE.AGPL-3.0
+
+# Remove the Colab-only "To run this, press Runtime > Run all ..." sentence, which is
+# wrong inside Docker, keeping the rest of the header cell. Two modes:
+#
+# unsloth_nb_strip_colab.py <a.ipynb> ... strip in place (idempotent)
+# unsloth_nb_strip_colab.py --state <STATE> --dest <DEST>
+# strip + rehash each notebook whose hash still matches STATE
+#
+# Safe with refresh: content_sig classifies the intro cell as boilerplate, so the
+# body digest is unchanged. Exit code is always 0.
+import argparse
+import hashlib
+import json
+import os
+import stat
+import sys
+
+_INTRO_PREFIX = "to run this, press"
+
+# Baked tqdm widget outputs render as a stuck "Loading widget...", and outputs are not
+# in the refresh signature, so dropping them is safe.
+_WIDGET_VIEW_MIME = "application/vnd.jupyter.widget-view+json"
+
+
+def _is_intro_line(line):
+ """True for the Colab run announcement, bare or inside a single-line HTML comment.
+ Only a comment that OPENS AND CLOSES on one line matches, so dropping it can never
+ leave a dangling `<!--` that swallows the rest of the cell."""
+ stripped = line.strip()
+ low = stripped.lower()
+ if low.startswith(_INTRO_PREFIX):
+ return True
+ if low.startswith("<!--") and stripped.endswith("-->"):
+ return stripped[4:-3].strip().lower().startswith(_INTRO_PREFIX)
+ return False
+
+
+def _stage_metadata(staged, dest):
+ """os.replace swaps the directory entry, so the staged inode's root owner would
+ become the published file's, undoing the sync script's care to leave a
+ bind-mounted notebook host-owned. Best effort."""
+ try:
+ st = os.stat(dest)
+ except OSError:
+ return
+ try:
+ os.chmod(staged, stat.S_IMODE(st.st_mode))
+ except OSError:
+ pass
+ try:
+ os.chown(staged, st.st_uid, st.st_gid)
+ except (OSError, AttributeError):
+ pass
+
+
+def _strip_lines(lines):
+ for i, line in enumerate(lines):
+ if _is_intro_line(line):
+ out = lines[:i] + lines[i + 1 :]
+ if i < len(out) and out[i].strip() == "":
+ out = out[:i] + out[i + 1 :]
+ return out
+ return None
+
+
+def _strip_cell(cell):
+ src = cell.get("source")
+ if isinstance(src, str):
+ lines = src.splitlines(keepends = True)
+ as_str = True
+ elif isinstance(src, list):
+ lines = list(src)
+ as_str = False
+ else:
+ return False
+ new_lines = _strip_lines(lines)
+ if new_lines is None:
+ return False
+ cell["source"] = "".join(new_lines) if as_str else new_lines
+ return True
+
+
+def _strip_intro(nb):
+ """Strip the Colab intro from the LEADING markdown block: cells[0] alone misses the
+ notebooks that put the badge there and the sentence in cells[1]. The scan stops at
+ the first non-markdown cell, so it never reaches prose between code cells."""
+ cells = nb.get("cells")
+ if not isinstance(cells, list):
+ return False
+ changed = False
+ for cell in cells:
+ if not isinstance(cell, dict) or cell.get("cell_type") != "markdown":
+ break # the first code cell ends the header block
+ if _strip_cell(cell):
+ changed = True
+ return changed
+
+
+def _clean_widgets(nb):
+ changed = False
+ cells = nb.get("cells")
+ if isinstance(cells, list):
+ for cell in cells:
+ if not isinstance(cell, dict):
+ continue
+ outs = cell.get("outputs")
+ if not isinstance(outs, list):
+ continue
+ kept = [
+ o
+ for o in outs
+ if not (isinstance(o, dict) and _WIDGET_VIEW_MIME in (o.get("data") or {}))
+ ]
+ if len(kept) != len(outs):
+ cell["outputs"] = kept
+ changed = True
+ md = nb.get("metadata")
+ if isinstance(md, dict) and "widgets" in md:
+ del md["widgets"]
+ changed = True
+ return changed
+
+
+def _unlink(path):
+ try:
+ os.remove(path)
+ except OSError:
+ pass
+
+
+def _stage_clean(path):
+ """(tmp, hash_before, hash_after) for a cleaned copy written beside the notebook but
+ NOT published, or None when there was nothing to change or the write failed.
+
+ Split out of strip_notebook so migrate can record the new hash before the notebook
+ carries it."""
+ try:
+ before = _sha256(path)
+ with open(path, "r", encoding = "utf-8") as f:
+ nb = json.load(f)
+ except Exception:
+ return None
+
+ changed = _strip_intro(nb)
+ changed = _clean_widgets(nb) or changed
+ if not changed:
+ return None
+
+ tmp = path + ".tmp"
+ try:
+ with open(tmp, "w", encoding = "utf-8") as f:
+ json.dump(nb, f, indent = 1, ensure_ascii = False)
+ f.write("\n")
+ return tmp, before, _sha256(tmp)
+ except Exception:
+ _unlink(tmp)
+ return None
+
+
+def _publish(tmp, path, before):
+ """Move the staged copy onto the notebook. False if it was not published."""
+ try:
+ # JupyterLab is already serving the tree, so a save between the read above and
+ # this replace would be overwritten and then recorded as pristine forever
+ if _sha256(path) != before:
+ _unlink(tmp)
+ return False
+ _stage_metadata(tmp, path)
+ os.replace(tmp, path)
+ except Exception:
+ _unlink(tmp)
+ return False
+ return True
+
+
+def _write_state(state_path, lines):
+ """Replace the state file durably; False when it could not be written.
+
+ fsync before the rename, because a crash between the two makes the rename visible
+ with the content unwritten, which strands the notebooks the same way."""
+ tmp = state_path + ".tmp"
+ try:
+ with open(tmp, "w", encoding = "utf-8") as f:
+ f.write("\n".join(lines) + "\n")
+ f.flush()
+ os.fsync(f.fileno())
+ os.replace(tmp, state_path)
+ except OSError:
+ _unlink(tmp)
+ return False
+ return True
+
+
+def _resume(path, rec):
+ """Finish a publish that was interrupted after its record landed. True if it did.
+
+ Recording before publishing closes the window that stranded the whole set at once,
+ but it leaves a one-notebook window of its own: a stop between os.replace on the
+ state file and os.replace on the notebook leaves `rec` describing the cleaned bytes
+ while the file still holds the pristine ones, and every later run reads that
+ mismatch as a user edit and carries the stale record forward forever. Cleaning what
+ is actually on disk tells the two apart, because only the interrupted case
+ reproduces `rec` byte for byte; a real edit cannot, so nothing else is touched."""
+ st = _stage_clean(path)
+ if st is None:
+ return False
+ tmp, before, after = st
+ if after != rec:
+ _unlink(tmp)
+ return False
+ return _publish(tmp, path, before)
+
+
+def strip_notebook(path, staged = None):
+ """True if the notebook was modified and written back. `staged`, when given, gets
+ {"sha256": ...} for the bytes THIS call wrote, so the caller need not re-read."""
+ st = _stage_clean(path)
+ if st is None:
+ return False
+ tmp, before, after = st
+ if not _publish(tmp, path, before):
+ return False
+ if staged is not None:
+ staged["sha256"] = after
+ return True
+
+
+def _sha256(path):
+ h = hashlib.sha256()
+ with open(path, "rb") as f:
+ for chunk in iter(lambda: f.read(65536), b""):
+ h.update(chunk)
+ return h.hexdigest()
+
+
+def migrate(state_path, dest):
+ """Clean every notebook the state file says we own, recording each one BEFORE it is
+ published.
+
+ Publishing the whole set first and then writing the state once meant that losing
+ that single write left every cleaned notebook no longer matching its record. The
+ refresh reads a hash mismatch as a user edit and carries the stale record forward,
+ so upstream updates stop reaching those notebooks permanently, while this reports
+ success. It is not a one-notebook risk either: on the first boot after this ships,
+ migrate cleans the entire set in one pass, so a docker stop or an ENOSPC anywhere
+ in that window stranded all of them at once.
+
+ Ordering it the other way is safe in the direction that matters. If the state write
+ fails, nothing has been published and the disk still matches the record, so the next
+ start simply tries again. The narrow window that is left, a stop between the two
+ renames, is reconciled by _resume rather than mistaken for a user edit."""
+ try:
+ with open(state_path, "r", encoding = "utf-8") as f:
+ lines = f.read().splitlines()
+ except OSError:
+ return 0
+
+ out = list(lines) # malformed lines and untouched records survive verbatim
+ changed = 0
+ stopped = False
+ for i, line in enumerate(lines):
+ parts = line.split(" ", 1) # "<sha256> <relpath>"
+ if len(parts) != 2:
+ continue
+ rec, rel = parts
+ path = os.path.join(dest, rel)
+ if not (rel.endswith(".ipynb") and os.path.isfile(path)):
+ continue
+ try:
+ digest = _sha256(path)
+ except OSError:
+ continue
+ if digest != rec: # not ours, the user has edited it, or a publish was cut off
+ if _resume(path, rec):
+ changed += 1
+ continue
+ staged = _stage_clean(path)
+ if staged is None:
+ continue
+ tmp, before, after = staged
+ out[i] = "%s %s" % (after, rel)
+ if not _write_state(state_path, out):
+ _unlink(tmp)
+ out[i] = line
+ stopped = True
+ break
+ if _publish(tmp, path, before):
+ changed += 1
+ else:
+ # nothing landed, so take the record back off
+ out[i] = line
+ _write_state(state_path, out)
+
+ if changed:
+ print(f"[unsloth-nb] cleaned {changed} notebook(s) (Colab intro + widget outputs)")
+ if stopped:
+ print(
+ "[unsloth-nb] could not record the cleaned notebooks; leaving the rest for "
+ "the next start"
+ )
+ return 0
+
+
+def main(argv):
+ ap = argparse.ArgumentParser(description = "Strip the Colab-only intro sentence.")
+ ap.add_argument("--state", help = "sync state file (enables migration mode)")
+ ap.add_argument("--dest", help = "notebooks dir (with --state)")
+ ap.add_argument("paths", nargs = "*", help = "notebooks to strip in place")
+ args = ap.parse_args(argv)
+
+ if args.state:
+ if not args.dest:
+ ap.error("--state requires --dest")
+ return migrate(args.state, args.dest)
+
+ changed = sum(1 for p in args.paths if strip_notebook(p))
+ if changed:
+ print(f"[unsloth-nb] cleaned {changed} notebook(s) (Colab intro + widget outputs)")
+ return 0
+
+
+if __name__ == "__main__":
+ sys.exit(main(sys.argv[1:]))
diff --git a/docker/unsloth_nb_view.py b/docker/unsloth_nb_view.py
new file mode 100644
index 00000000000..03280a18208
--- /dev/null
+++ b/docker/unsloth_nb_view.py
@@ -0,0 +1,243 @@
+#!/usr/bin/env python3
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-Present the Unsloth team. See /studio/LICENSE.AGPL-3.0
+
+# Build a categorized, Colab-like folder VIEW of the Unsloth notebooks: a disposable
+# sibling of DEST holding relative SYMLINKS, so real files never move and the sync
+# state machine skips them. Section = nearest preceding markdown header, folders
+# numbered `NN ` by first appearance so JupyterLab's sort keeps README order.
+#
+# Usage:
+# unsloth_nb_view.py <DEST> <VIEW> [--amd] build the symlink view
+# unsloth_nb_view.py <DEST> --print [--amd] print "section\tfile" rows
+# Exits nonzero on error (caller falls back to the raw tree).
+import argparse
+import os
+import re
+import sys
+import urllib.parse
+
+_NB_RE = re.compile(r"nb/([\w.()%\-]+?\.ipynb)")
+_OTHER = "Other Notebooks"
+
+
+def _load_makedirs_as_host():
+ """unsloth_run's directory maker, or None.
+
+ mkdir(2) gives a new directory the CALLER's uid and only setgid carries down, so
+ building the view as root under a host bind mount leaves the view root and every
+ category folder root:root: the host user cannot add their own link to a category,
+ or delete the generated view, without escalating. unsloth_sync_notebooks.sh grew
+ mkdir_keep_owner and unsloth_run has _makedirs_as_host for exactly this; the view
+ was the sibling both of them missed.
+
+ Imported rather than copied a third time. __file__ is the /usr/local/bin symlink
+ in the image, so resolve it before deriving the directory, and
+ test_the_view_uses_the_same_directory_maker_as_unsloth_run fails if this stops
+ resolving rather than letting it degrade quietly back to the bug.
+ """
+ here = os.path.dirname(os.path.realpath(__file__))
+ added = here not in sys.path
+ if added:
+ sys.path.insert(0, here)
+ try:
+ from unsloth_run import _makedirs_as_host
+ return _makedirs_as_host
+ except Exception:
+ return None
+ finally:
+ if added:
+ try:
+ sys.path.remove(here)
+ except ValueError:
+ pass
+
+
+_MAKEDIRS_AS_HOST = _load_makedirs_as_host()
+
+
+def _makedirs(path):
+ if _MAKEDIRS_AS_HOST is not None:
+ _MAKEDIRS_AS_HOST(path)
+ else:
+ os.makedirs(path, exist_ok = True)
+
+
+def clean_section(title):
+ title = title.strip().strip("#").strip()
+ title = re.sub(r"^[^\w]+", "", title)
+ title = title.replace("-", " ").replace("/", " ")
+ title = re.sub(r"\s+", " ", title).strip()
+ return title
+
+
+def parse_readme(readme_path):
+ """Ordered (section_label, filename) pairs, filename urldecoded. Dedup is per
+ (section, file), not global: the README deliberately cross-lists a notebook so
+ every header becomes a populated folder."""
+ with open(readme_path, "r", encoding = "utf-8") as f:
+ text = f.read()
+
+ rows = []
+ seen_pairs = set()
+ section = None
+ # any heading level: `#`/`##` domain headers carry their own nb/*.ipynb tables
+ for line in text.splitlines():
+ m = re.match(r"^#{1,6}\s+(.*)$", line)
+ if m:
+ section = clean_section(m.group(1))
+ continue
+ if section is None:
+ continue
+ for raw in _NB_RE.findall(line):
+ fname = urllib.parse.unquote(raw)
+ key = (section, fname)
+ if key in seen_pairs:
+ continue
+ seen_pairs.add(key)
+ rows.append((section, fname))
+ return rows
+
+
+def _ordered_sections(rows):
+ order = []
+ for section, _ in rows:
+ if section not in order:
+ order.append(section)
+ order = [s for s in order if s != _OTHER] + [_OTHER]
+ return order
+
+
+def build_view(
+ dest,
+ view,
+ amd = False,
+):
+ nb_dir = os.path.join(dest, "nb")
+ readme = os.path.join(dest, "README.md")
+ if not os.path.isdir(nb_dir):
+ raise SystemExit(f"no nb/ dir under {dest}")
+
+ if os.path.islink(view):
+ resolved = os.path.realpath(view)
+ if not os.path.isdir(resolved):
+ raise SystemExit(f"view symlink has no directory target: {view} -> {resolved}")
+ view = resolved
+
+ rows = parse_readme(readme) if os.path.isfile(readme) else []
+
+ def allowed(fname):
+ return amd or not fname.startswith("AMD-")
+
+ by_section = {}
+ placed = set()
+ for section, fname in rows:
+ if not allowed(fname):
+ continue
+ if not os.path.isfile(os.path.join(nb_dir, fname)):
+ continue
+ by_section.setdefault(section, []).append(fname)
+ placed.add(fname)
+
+ for fname in sorted(os.listdir(nb_dir)):
+ if not fname.endswith(".ipynb"):
+ continue
+ if fname in placed or not allowed(fname):
+ continue
+ by_section.setdefault(_OTHER, []).append(fname)
+
+ order = [s for s in _ordered_sections(rows) if s in by_section]
+ if _OTHER in by_section and _OTHER not in order:
+ order.append(_OTHER)
+
+ # keyed on DEST/nb, the only place our links point, so a user's own shortcut
+ # elsewhere survives the rebuild
+ nb_real = os.path.realpath(nb_dir)
+ _clear_view(view, nb_real)
+ _makedirs(view)
+
+ n_links = 0
+ for i, section in enumerate(order, start = 1):
+ folder = os.path.join(view, f"{i:02d} {section}")
+ _makedirs(folder)
+ for fname in by_section[section]:
+ link = os.path.join(folder, fname)
+ target = os.path.join(nb_dir, fname)
+ rel = os.path.relpath(target, folder)
+ try:
+ if os.path.islink(link) and _points_into(link, nb_real):
+ os.remove(link)
+ elif os.path.islink(link) or os.path.exists(link):
+ print(f"[unsloth-nb] view: keep user file, skip link {fname}", file = sys.stderr)
+ continue
+ os.symlink(rel, link)
+ n_links += 1
+ except OSError as e:
+ print(f"[unsloth-nb] view: skip {fname}: {e}", file = sys.stderr)
+ return len(order), n_links
+
+
+def _points_into(link, nb_real):
+ """The ownership test for cleanup: our links all point into DEST/nb, so a user's
+ own symlink resolves outside it and survives. realpath resolves a broken link's
+ path string too, so stale links still count as ours."""
+ try:
+ target = os.path.realpath(link)
+ except OSError:
+ return False
+ return target == nb_real or target.startswith(nb_real + os.sep)
+
+
+def _clear_view(path, nb_real):
+ # VIEW is also JupyterLab's landing dir, so unlink only symlinks we own and rmdir
+ # only emptied folders; the VIEW root is never removed
+ if os.path.islink(path) or not os.path.isdir(path):
+ return
+ for root, dirs, files in os.walk(path, topdown = False):
+ for name in files:
+ p = os.path.join(root, name)
+ if os.path.islink(p) and _points_into(p, nb_real):
+ try:
+ os.remove(p)
+ except OSError:
+ pass
+ for name in dirs:
+ p = os.path.join(root, name)
+ try:
+ if os.path.islink(p):
+ if _points_into(p, nb_real):
+ os.remove(p) # unlink, never recurse
+ else:
+ os.rmdir(p) # succeeds only if we emptied it
+ except OSError:
+ pass
+
+
+def main(argv):
+ ap = argparse.ArgumentParser(description = "Build the categorized notebook view.")
+ ap.add_argument("dest", help = "notebooks dir (contains README.md and nb/)")
+ ap.add_argument("view", nargs = "?", help = "output view dir (omit with --print)")
+ ap.add_argument("--amd", action = "store_true", help = "include AMD-* notebooks")
+ ap.add_argument(
+ "--print",
+ dest = "do_print",
+ action = "store_true",
+ help = "print section<TAB>file rows instead of building",
+ )
+ args = ap.parse_args(argv)
+
+ if args.do_print:
+ for section, fname in parse_readme(os.path.join(args.dest, "README.md")):
+ if args.amd or not fname.startswith("AMD-"):
+ print(f"{section}\t{fname}")
+ return 0
+
+ if not args.view:
+ ap.error("view dir is required unless --print is given")
+ n_sections, n_links = build_view(args.dest, args.view, amd = args.amd)
+ print(f"[unsloth-nb] view: {n_links} notebooks in {n_sections} folders -> {args.view}")
+ return 0
+
+
+if __name__ == "__main__":
+ sys.exit(main(sys.argv[1:]))
diff --git a/docker/unsloth_pip_shim.py b/docker/unsloth_pip_shim.py
new file mode 100644
index 00000000000..68f6dea1a9a
--- /dev/null
+++ b/docker/unsloth_pip_shim.py
@@ -0,0 +1,1269 @@
+#!/opt/unsloth-venv/bin/python
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-Present the Unsloth team. See /studio/LICENSE.AGPL-3.0
+
+"""pip / uv shim for the Unsloth Docker notebook environment.
+
+Sits ahead of the real tools on PATH so a notebook `!pip install` cell cannot clobber
+the baked cu128 stack: `transformers==X` is recorded for the unsloth_nb_compat sidecar
+instead of installed, other _KEEP packages are skipped WHEN THEY ARE ACTUALLY BAKED
+IN, everything else passes through. The real tools are invoked by absolute path, so
+there is no recursion.
+"""
+
+import os, re, sys, tempfile
+
+REAL = {"pip": "/opt/unsloth-venv/bin/pip", "uv": "/opt/unsloth-venv/bin/uv"}
+MARKER = os.environ.get("UNSLOTH_NB_TF_MARKER", "/tmp/unsloth_nb/requested_transformers")
+
+# Membership criterion: replacing the package invalidates the stack the image was
+# built and tested against, either an ABI/CUDA-matched wheel the Dockerfile resolved
+# deliberately, or a library unsloth/unsloth_zoo patches by version at import time.
+_KEEP = {
+ "torch",
+ "torchvision",
+ "torchaudio",
+ "torchao",
+ "torchcodec",
+ "triton",
+ "triton-rocm",
+ "pytorch-triton",
+ "xformers",
+ "vllm",
+ "bitsandbytes",
+ "flashinfer",
+ "flashinfer-python",
+ "unsloth",
+ "unsloth-zoo",
+ "unsloth_zoo",
+ "trl",
+ "peft",
+ "datasets",
+ "accelerate",
+ "huggingface-hub",
+ "huggingface_hub",
+ "tokenizers",
+ "safetensors",
+}
+_KEEP_PREFIX = ("nvidia-", "nvidia_")
+_VALUE_FLAGS = {
+ "-r",
+ "--requirement",
+ "--requirements",
+ "-c",
+ "--constraint",
+ "--constraints",
+ "-i",
+ "--index-url",
+ "--extra-index-url",
+ "-f",
+ "--find-links",
+ "--target",
+ "-t",
+ "--python",
+ "-p",
+ "--prefix",
+ "--index-strategy",
+ "--upgrade-strategy",
+ "--upgrade-package",
+ "-P",
+ "--reinstall-package",
+ "--no-binary",
+ "--only-binary",
+ "--platform",
+ "--python-version",
+ "--abi",
+ "--implementation",
+ "-e",
+ "--editable",
+ "--allow-insecure-host",
+ "--build-constraints",
+ "-b",
+ "--cache-dir",
+ "--color",
+ "--config-file",
+ "--config-setting",
+ "-C",
+ "--config-settings-package",
+ "--default-index",
+ "--directory",
+ "--exclude-newer",
+ "--exclude-newer-package",
+ "--excludes",
+ "--extra",
+ "--fork-strategy",
+ "--group",
+ "--index",
+ "--keyring-provider",
+ "--link-mode",
+ "--no-build-isolation-package",
+ "--no-sources-package",
+ "--overrides",
+ "--prerelease",
+ "--project",
+ "--python-platform",
+ "--refresh-package",
+ "--resolution",
+ "--torch-backend",
+ "--no-editable-package",
+ "--upgrade-group",
+ "--prerelease-package",
+ "--build-constraint",
+ "--cert",
+ "--client-cert",
+ "--config-settings",
+ "--exists-action",
+ "--log",
+ "--progress-bar",
+ "--proxy",
+ "--report",
+ "--resume-retries",
+ "--retries",
+ "--root",
+ "--root-user-action",
+ "--src",
+ "--timeout",
+ "--trusted-host",
+ "--use-deprecated",
+ "--use-feature",
+ "--all-releases",
+ "--only-final",
+ "--requirements-from-script",
+ "--uploaded-prior-to",
+}
+_REQ_FILE_FLAGS = {"-r", "--requirement", "--requirements"}
+_CONSTRAINT_FILE_FLAGS = {"-c", "--constraint", "--constraints"}
+# a protected editable must drop BOTH flag and value, or a dangling -e eats the next
+_EDITABLE_FLAGS = {"-e", "--editable"}
+_UPGRADE_PKG_FLAGS = {"-P", "--upgrade-package", "--reinstall-package"}
+_ATTACHED_SHORT_FLAGS = {"-r", "-c", "-e", "-P"}
+# these rebuild baked deps; the kept target still installs once they are dropped
+_REINSTALL_FLAGS = {"--force-reinstall", "--ignore-installed", "-I", "--reinstall", "--exact"}
+# dropped with their value; eager would upgrade every dep of a kept target
+# Hidden ALIASES of flags already listed above. pip's --help prints only the
+# canonical spelling, so no amount of help-scraping can find these; the selfcheck now
+# introspects pip's own option table instead, which is where they came from.
+# --python-preference is a uv GLOBAL that appears in neither `uv --help` nor
+# `uv help`, and uv still accepts it.
+_ALIAS_VALUE_FLAGS = {
+ "--default-timeout",
+ "--local-log",
+ "--log-file",
+ "--pypi-url",
+ "--source",
+ "--source-dir",
+ "--source-directory",
+ "--python-preference",
+}
+_VALUE_FLAGS |= _ALIAS_VALUE_FLAGS
+
+_DROP_VALUE_FLAGS = {"--upgrade-strategy"}
+
+# these ARE the install target, with no package on the command line: without them the
+# shim scans to no target and no-ops while printing "ok"
+_TARGET_VALUE_FLAGS = {"--group", "--upgrade-group", "--requirements-from-script"}
+
+
+_ARCHIVE_EXTS = (".tar.gz", ".tgz", ".tar.bz2", ".tbz2", ".tar.xz", ".txz", ".tar", ".zip")
+
+
+def _norm_name(name):
+ """PEP 503 normalised name; every _KEEP / _KEEP_PREFIX comparison goes through here."""
+ return re.sub(r"[-_.]+", "-", name.strip()).lower() or None
+
+
+def _base_site_packages():
+ """site-packages of the venv that owns the REAL pip/uv, or [] if it cannot be
+ located.
+
+ Every scan below MUST be scoped to this rather than to sys.path. When a notebook
+ activates a transformers sidecar, unsloth_nb_compat and unsloth_run PREPEND that
+ sidecar to PYTHONPATH, and the sidecars are built with `uv pip install --target`,
+ so each one ships a real transformers-X.dist-info. A bare distributions() walks
+ sys.path in order and therefore reports the SIDECAR's transformers first, which
+ would pin the sidecar version into the protected constraints and let the resolver
+ move the shared base install to it.
+
+ The venv that owns the REAL pip is the authoritative answer. purelib is the
+ fallback and is safe for the same reason: it derives from sys.prefix, which
+ PYTHONPATH cannot influence, so it can never name a sidecar."""
+ import glob
+
+ venv = os.path.dirname(os.path.dirname(REAL["pip"]))
+ found = [
+ p
+ for p in sorted(glob.glob(os.path.join(venv, "lib", "python*", "site-packages")))
+ if os.path.isdir(p)
+ ]
+ if found:
+ return found
+ import sysconfig
+
+ purelib = sysconfig.get_paths().get("purelib") or ""
+ return [purelib] if purelib and os.path.isdir(purelib) else []
+
+
+_INSTALLED_NAMES = []
+
+
+def _installed_names():
+ """Every distribution name in this venv, PEP 503 normalised, or None when the scan
+ fails. Cached because importlib.metadata rescans sys.path on every call."""
+ if not _INSTALLED_NAMES:
+ try:
+ from importlib.metadata import distributions
+
+ scope = _base_site_packages()
+ if not scope:
+ # unknown base: None makes _is_installed answer "assume baked", which
+ # is the stricter of the two answers
+ raise RuntimeError("base site-packages not found")
+ found = set()
+ for dist in distributions(path = scope):
+ try:
+ n = _norm_name(dist.metadata["Name"] or "")
+ except Exception:
+ n = None
+ if n:
+ found.add(n)
+ _INSTALLED_NAMES.append(found)
+ except Exception:
+ _INSTALLED_NAMES.append(None)
+ return _INSTALLED_NAMES[0]
+
+
+def _is_protected(name):
+ """True when `name` is a baked package that is REALLY installed. Every drop
+ decision goes through here so the three call sites cannot drift apart.
+
+ An absent package is nothing to protect, and dropping it turned a recovery
+ install into a silent success: the Dockerfile lets the torchcodec bake and the
+ non-amd64 vLLM bake fail on purpose, so a notebook `pip install vllm` printed
+ "kept baked versions, skipped: vllm" over an image that had no vLLM at all, and
+ the GRPO fast_inference path stayed broken. Forwarding instead either installs it
+ under the protected constraints or fails loudly, and both beat a false success.
+ An unreadable metadata scan keeps the old, stricter answer."""
+ if name is None:
+ return False
+ if not (name in _KEEP or name.startswith(_KEEP_PREFIX)):
+ return False
+ return _is_installed(name)
+
+
+def _is_installed(name):
+ """True when `name` is really in this venv, or when the scan failed and the
+ stricter "assume baked" answer is the safe one."""
+ present = _installed_names()
+ return present is None or name in present
+
+
+def _sdist_name(basename):
+ """Name from a `{name}-{version}.ext` basename, split at the first hyphen before a
+ digit so legacy hyphenated names resolve too."""
+ low = basename.lower()
+ stem = None
+ for ext in _ARCHIVE_EXTS:
+ if low.endswith(ext):
+ stem = basename[: -len(ext)]
+ break
+ if stem is None:
+ return None
+ m = re.match(r"^(.+?)-\d", stem)
+ return _norm_name(m.group(1) if m else stem)
+
+
+def _canon(token):
+ if token.startswith("-"):
+ return None
+ # IGNORECASE: URL schemes are case insensitive and pip normalises them, so
+ # `unsloth@GIT+HTTPS://...` is the same direct reference as the lowercase
+ # spelling. Matching only lowercase missed the explicit name, fell through to the
+ # URL branch, and returned None (or, for a .whl URL, the wheel's own stem), so a
+ # protected package was classified unknown and forwarded.
+ _dref = re.match(
+ r"^([A-Za-z0-9][A-Za-z0-9._-]*)\s*(?:\[[^\]]*\])?\s*@(?:\s|git\+|hg\+|bzr\+|svn\+|[a-z]+://)",
+ token,
+ re.IGNORECASE,
+ )
+ if _dref:
+ return _norm_name(_dref.group(1))
+ if (
+ re.match(r"^[a-z]+\+", token, re.IGNORECASE)
+ or "://" in token
+ or token.startswith((".", "/"))
+ ):
+ _egg = re.search(r"[#&]egg=([A-Za-z0-9][A-Za-z0-9._-]*)", token)
+ if _egg:
+ return _norm_name(_egg.group(1))
+ _whl = re.search(r"([^/\\#?]+)\.whl(?:[#?]|$)", token)
+ if _whl:
+ dist = _norm_name(_whl.group(1).split("-", 1)[0])
+ if dist:
+ return dist
+ _arch = _sdist_name(token.split("#", 1)[0].split("?", 1)[0].rstrip("/").rsplit("/", 1)[-1])
+ if _arch:
+ return _arch
+ if re.match(r"^[a-z]+\+", token):
+ _rest = token.split("#", 1)[0].split("?", 1)[0]
+ # split path from authority first, so an SSH userinfo @ is not the ref
+ if "://" in _rest:
+ _authority, _slash, _path = _rest.partition("://")[2].partition("/")
+ if "@" in _path:
+ _path = _path.rsplit("@", 1)[0]
+ _rest = _path if _slash else _authority
+ _seg = _rest.rstrip("/").rsplit("/", 1)[-1]
+ _seg = _seg.split("@", 1)[0]
+ if _seg.endswith(".git"):
+ _seg = _seg[:-4]
+ _seg = _norm_name(_seg)
+ if _seg:
+ return _seg
+ _local = _local_project_name(token)
+ if _local:
+ return _local
+ return None
+ if "/" in token or os.sep in token:
+ _local = _local_project_name(token)
+ if _local:
+ return _local
+ if token.lower().endswith(".whl"):
+ dist = _norm_name(token.rsplit("/", 1)[-1][:-4].split("-", 1)[0])
+ if dist:
+ return dist
+ _barch = _sdist_name(token.rsplit("/", 1)[-1])
+ if _barch:
+ return _barch
+ name = re.split(r"[<>=!~\[\s;@]", token, maxsplit = 1)[0].strip()
+ return _norm_name(name)
+
+
+def _local_project_name(token):
+ """Name pip/uv would build for a local project dir, falling back to the basename
+ only when the dir is an installable project at all. None for a metadata-less dir,
+ so ordinary paths pass through."""
+ # from uv's working directory, not ours: `uv pip --directory X install -e ./p`
+ # stats ./p from X, so resolving it here against our own cwd misses and reports
+ # the project as unknown. That is silent, and worse than the requirements-file
+ # case, because the injected constraint only rejects a version MISMATCH: a local
+ # checkout whose version equals the baked one installs and replaces it.
+ path = _resolve_read_path(token.split("#", 1)[0])
+ if not os.path.isdir(path):
+ return None
+ _pyproject = os.path.join(path, "pyproject.toml")
+ if os.path.isfile(_pyproject):
+ try:
+ import tomllib
+ with open(_pyproject, "rb") as f:
+ _name = (tomllib.load(f).get("project") or {}).get("name")
+ if _name:
+ return _norm_name(_name)
+ except Exception:
+ pass
+ _setup_cfg = os.path.join(path, "setup.cfg")
+ if os.path.isfile(_setup_cfg):
+ try:
+ import configparser
+
+ _cp = configparser.ConfigParser()
+ _cp.read(_setup_cfg)
+ _name = _cp.get("metadata", "name", fallback = None)
+ if _name:
+ return _norm_name(_name)
+ except Exception:
+ pass
+ if os.path.isfile(os.path.join(path, "setup.py")) or os.path.isfile(_pyproject):
+ _base = os.path.basename(os.path.normpath(path))
+ return _norm_name(_base)
+ return None
+
+
+def _marker_is_false(token):
+ """True when this requirement carries a PEP 508 marker that does not hold here.
+
+ Both real tools then skip it entirely, so it pins nothing and must not reach the
+ sidecar marker file. packaging is treated as optional, as it is elsewhere: if it
+ is missing or the token does not parse, nothing is vetoed."""
+ try:
+ from packaging.requirements import Requirement
+ req = Requirement(token)
+ except Exception:
+ return False
+ try:
+ return req.marker is not None and not req.marker.evaluate()
+ except Exception:
+ return False
+
+
+def _version_pin(token):
+ if _marker_is_false(token):
+ return None
+ m = re.search(r"==\s*([0-9][0-9A-Za-z.\-]*)", token)
+ return m.group(1) if m else None
+
+
+# pip expands ${UPPERCASE} in requirements files, so `${PKG}==` would slip _KEEP.
+# Expanded for CLASSIFICATION only; kept lines stay verbatim.
+_ENV_REF_RE = re.compile(r"\$\{([A-Z0-9_]+)\}")
+
+
+def _expand_env_refs(text):
+ return _ENV_REF_RE.sub(lambda m: os.environ.get(m.group(1), m.group(0)), text)
+
+
+_EXTRAS_RE = re.compile(
+ r"^(?P<name>[A-Za-z0-9][A-Za-z0-9._-]*)\s*\[(?P<extras>[^\]]+)\]\s*(?P<rest>.*)$"
+)
+
+
+def _extras_only_target(token):
+ """`name[extras]` when `token` asks for EXTRAS of a baked package, else None.
+
+ pip and uv treat `pkg[extra]` against an already-satisfied `pkg` as "add the
+ optional dependencies", not "replace pkg", so dropping the whole token loses
+ every package the extra pulls in and still prints ok: `pip install
+ "datasets[audio]"` became a no-op and the notebook died later on the missing
+ decoder. The version specifier is dropped along with the rest of the
+ requirement and _protected_constraints_file() pins the baked version, so what
+ is forwarded can only ADD. A direct reference (`pkg[extra] @ url`) or a path
+ IS a replacement request, so those keep being dropped."""
+ if "://" in token or token.startswith((".", "/", "-")) or os.sep in token:
+ return None
+ m = _EXTRAS_RE.match(token.strip())
+ if not m:
+ return None
+ rest = m.group("rest").strip()
+ if rest.startswith("@"):
+ return None
+ out = m.group("name") + "[" + m.group("extras").strip() + "]"
+ marker = rest.split(";", 1)
+ if len(marker) == 2 and marker[1].strip():
+ out += " ; " + marker[1].strip()
+ return out
+
+
+def _classify_flag_target(spec):
+ name = _canon(spec)
+ if name == "transformers":
+ return "drop", _version_pin(spec)
+ if _is_protected(name):
+ return "drop", None
+ return "keep", None
+
+
+def _parse_flag_line(stripped, flags):
+ """(flag, target_or_None, inline_comment_or_None) for a `<flag> <target>`
+ requirements-file line, in any of the forms pip accepts, else (None, None, None)."""
+ body, sep, comment = stripped.partition(" #")
+ body = body.rstrip()
+ comment = ("#" + comment) if sep else None
+ for flag in flags:
+ if body == flag or body.startswith(flag + " "):
+ target = body[len(flag) :].strip()
+ elif body.startswith(flag + "="):
+ target = body[len(flag) + 1 :].strip()
+ elif not flag.startswith("--") and body.startswith(flag) and len(body) > len(flag):
+ target = body[len(flag) :].strip()
+ else:
+ continue
+ return flag, (target or None), comment
+ return None, None, None
+
+
+def _rewrite_include(line, stripped, src_dir, depth):
+ """Rewrite a nested `-r`/`-c` include -> (new_line, changed, recorded, dropped).
+ pip resolves it against the directory of the file it is READING, and our filtered
+ copy lives under /tmp, so a relative include must be absolutised."""
+ flag, raw_target, comment = _parse_flag_line(
+ stripped, ("-r", "--requirement", "-c", "--constraint")
+ )
+ if not raw_target:
+ return line, False, None, []
+ target = _expand_env_refs(raw_target)
+ newline_char = "\n" if line.endswith("\n") else ""
+
+ def _emit(new_target):
+ rebuilt = flag + " " + new_target
+ if comment:
+ rebuilt += " " + comment
+ return rebuilt + newline_char
+
+ if "://" in target:
+ return None, True, None, [flag + " " + raw_target]
+ abs_target = target if os.path.isabs(target) else os.path.join(src_dir, target)
+ if depth < 8:
+ f_path, f_rec, f_drp = _filter_requirements_file(abs_target, _depth = depth + 1)
+ # a -c include is a constraint, not an install request: no marker
+ if flag in _CONSTRAINT_FILE_FLAGS:
+ f_rec = None
+ if f_path != abs_target:
+ return _emit(f_path), True, f_rec, f_drp
+ if not os.path.isabs(target):
+ return _emit(abs_target), True, None, []
+ return line, False, None, []
+
+
+def _logical_lines(lines):
+ """Group physical requirements-file lines into the LOGICAL lines pip parses.
+
+ A trailing backslash continues onto the next line, which is exactly how
+ `pip-compile --generate-hashes` / `uv pip compile --generate-hashes` write a
+ pinned requirement: `torch==2.11.0 \\` then indented `--hash=...` rows.
+ Filtering physical lines dropped only the first row and published the orphaned
+ `--hash` rows, which uv rejects outright ("Unexpected '-', expected ... the
+ start of a requirement"), killing the whole install."""
+ group = []
+ for line in lines:
+ group.append(line)
+ body = line.strip()
+ if body.endswith("\\") and not body.startswith("#"):
+ continue
+ yield group
+ group = []
+ if group:
+ yield group
+
+
+# Where the real tool will resolve a relative `-r`/`-c` path from. None means our
+# own cwd, which is what pip always uses. main() sets it for uv.
+_WORKING_DIR = None
+
+
+def _uv_working_dir(tool, argv):
+ """The directory uv will change to before resolving a relative requirements
+ path, or None. `--directory` is a uv GLOBAL, so it is accepted in every
+ position: before `pip`, between `pip` and `install`, and after `install`. uv
+ rejects it more than once ("cannot be used multiple times"), so the first hit
+ is the only hit, and it overrides UV_WORKING_DIR. pip has no equivalent."""
+ if tool != "uv":
+ return None
+ for n, tok in enumerate(argv):
+ if tok == "--directory":
+ return argv[n + 1] if n + 1 < len(argv) else None
+ if tok.startswith("--directory="):
+ return tok[len("--directory=") :] or None
+ return os.environ.get("UV_WORKING_DIR") or None
+
+
+def _resolve_read_path(path):
+ """Read a relative requirements path from where the real tool will read it.
+ Reading it from our cwd instead makes open() miss, and a miss is silent: the
+ original relative path is forwarded unfiltered and uv, now chdir'd, installs a
+ file we never inspected and never recorded a transformers pin from."""
+ if not _WORKING_DIR or os.path.isabs(path):
+ return path
+ return os.path.join(_WORKING_DIR, path)
+
+
+def _filter_requirements_file(path, _depth = 0):
+ """Strip protected packages out of a `-r` file, recursing into nested includes.
+ Returns (path_to_use, recorded_transformers_version, dropped_specs)."""
+ read_path = _resolve_read_path(path)
+ try:
+ # utf-8-sig, not utf-8: a BOM would otherwise leave "\ufefftransformers==X" on
+ # line 1, matching no handler, so a file whose ONLY protected pin is first
+ # forwards unchanged. Both real tools strip it and honour the line.
+ with open(read_path, encoding = "utf-8-sig") as f:
+ lines = f.readlines()
+ except OSError:
+ # forward what the caller passed, not the resolved path: uv resolves it
+ # itself, and pip never had a working directory to resolve against
+ return path, None, []
+ src_dir = os.path.dirname(os.path.abspath(read_path))
+ out, dropped, recorded, changed = [], [], None, False
+ for group in _logical_lines(lines):
+ line = group[0]
+ stripped = " ".join(part.strip().rstrip("\\").strip() for part in group).strip()
+ if not stripped or stripped.startswith("#"):
+ out.extend(group)
+ continue
+ if stripped.startswith("-"):
+ e_flag, e_target, _e_comment = _parse_flag_line(stripped, ("-e", "--editable"))
+ if e_target is not None:
+ _action, _ver = _classify_flag_target(_expand_env_refs(e_target))
+ if _action == "drop":
+ if _ver and not recorded:
+ recorded = _ver
+ dropped.append(e_flag + " " + e_target)
+ changed = True
+ continue
+ out.extend(group)
+ continue
+ if len(group) > 1:
+ out.extend(group)
+ continue
+ new_line, rewrote, inc_rec, inc_drp = _rewrite_include(line, stripped, src_dir, _depth)
+ if new_line is not None:
+ out.append(new_line)
+ if rewrote:
+ changed = True
+ if inc_rec and not recorded:
+ recorded = inc_rec
+ dropped.extend(inc_drp)
+ continue
+ spec = stripped.split(" #", 1)[0].strip()
+ # the per-requirement options a joined `--hash` block carries are noise here
+ report = spec.split(" --", 1)[0].strip()
+ classified = _expand_env_refs(spec)
+ name = _canon(classified)
+ if name is None:
+ out.extend(group)
+ continue
+ if name == "transformers":
+ v = _version_pin(classified)
+ if v and not recorded:
+ recorded = v
+ # extras of the BAKED transformers are additive exactly as they are for
+ # every _KEEP package below, and the sidecar only replaces the version:
+ # dropping the whole token loses deepspeed/sentencepiece/... and still
+ # reports ok. The pin is stripped, so this can only ADD.
+ extras = _extras_only_target(spec) if _is_installed("transformers") else None
+ if extras is not None:
+ out.append(extras + ("\n" if group[-1].endswith("\n") else ""))
+ changed = True
+ continue
+ dropped.append(report)
+ changed = True
+ continue
+ if _is_protected(name):
+ extras = _extras_only_target(spec)
+ if extras is not None:
+ out.append(extras + ("\n" if group[-1].endswith("\n") else ""))
+ changed = True
+ continue
+ dropped.append(report)
+ changed = True
+ continue
+ out.extend(group)
+ if not changed:
+ return path, None, []
+ try:
+ fd, tmp = tempfile.mkstemp(prefix = "unsloth-nb-req-", suffix = ".txt")
+ with os.fdopen(fd, "w", encoding = "utf-8") as f:
+ f.writelines(out)
+ except OSError as exc:
+ # fail CLOSED: forwarding the original hands pip the specs we must filter
+ raise SystemExit(
+ f"[unsloth-nb] could not write a filtered copy of {path} ({exc}); "
+ "refusing to forward a requirements file that pins protected packages."
+ )
+ return tmp, recorded, dropped
+
+
+def _protected_constraints_file():
+ """Temp constraints file pinning every INSTALLED protected package, or None when
+ the environment has none to pin. Argument filtering does not constrain the
+ RESOLVER: a kept package declaring `torch==99.0` would replace the baked torch,
+ and pinning makes that fail loudly. `_extras_only_target` leans on the same pin --
+ it forwards `torch[opt]` with the version specifier stripped precisely because the
+ pin holds the baked version, so an unconstrained forward can REPLACE rather than
+ only ADD.
+
+ So a failure to build the file fails CLOSED, exactly as _filter_requirements_file
+ already does for the same mkstemp error: swallowing it returned None, which the
+ caller cannot tell apart from "nothing to protect", and the install then ran with
+ the whole protection silently off. Only a wholesale failure aborts; one dist whose
+ metadata cannot be read is skipped, since a half-removed `.dist-info` left by an
+ interrupted install is ordinary and must not block every later install."""
+ try:
+ from importlib.metadata import distributions
+
+ scope = _base_site_packages()
+ if not scope:
+ raise RuntimeError(f"could not locate the site-packages of {REAL['pip']}")
+ # scoped, NOT a bare distributions(): see _base_site_packages. An activated
+ # sidecar sits ahead of the venv on PYTHONPATH and would otherwise be pinned
+ # here in place of the baked version.
+ dists = list(distributions(path = scope))
+ except Exception as exc:
+ raise SystemExit(
+ f"[unsloth-nb] could not enumerate installed packages ({exc}); refusing to "
+ "install without the constraints that hold the baked stack in place."
+ )
+ pins = {}
+ for dist in dists:
+ try:
+ raw = (dist.metadata["Name"] or "").strip()
+ version = dist.version
+ except Exception:
+ continue
+ name = _norm_name(raw)
+ if not name or not version or name in pins:
+ continue
+ if name == "transformers" or name in _KEEP or name.startswith(_KEEP_PREFIX):
+ pins[name] = f"{raw}=={version}"
+ if not pins:
+ return None
+ try:
+ fd, tmp = tempfile.mkstemp(prefix = "unsloth-nb-protected-", suffix = ".txt")
+ with os.fdopen(fd, "w", encoding = "utf-8") as f:
+ f.write("\n".join(pins[name] for name in sorted(pins)) + "\n")
+ except OSError as exc:
+ raise SystemExit(
+ f"[unsloth-nb] could not write the protected constraints file ({exc}); "
+ "refusing to install without the pins that hold the baked stack in place."
+ )
+ return tmp
+
+
+def _selfcheck_value_flags():
+ """Assert every value-taking flag the REAL pip/uv accept is classified, else the
+ scanner misreads a flag's VALUE as an install target and forwards the install
+ unfiltered. Run at image build time.
+
+ pip is INTROSPECTED, not scraped. Its --help prints one spelling per option, so
+ seven hidden aliases (--default-timeout among them) were invisible to the old
+ scrape while the check still reported OK -- a false success guarding the guard.
+ optparse knows all of them.
+
+ uv is a binary with no such table, so it is scraped at all three levels rather
+ than just `uv pip install`, and the globals it accepts but documents nowhere are
+ probed directly. A level we cannot inspect is a FAILURE, never a pass.
+ """
+ import subprocess
+
+ known = _VALUE_FLAGS | _DROP_VALUE_FLAGS
+ missing = {}
+
+ probe = (
+ "from pip._internal.commands import create_command\n"
+ "v=set()\n"
+ "for o in create_command('install').parser.option_list_all:\n"
+ " if o.takes_value(): v.update(o._long_opts); v.update(o._short_opts)\n"
+ "print('\\n'.join(sorted(v)))\n"
+ )
+ try:
+ out = subprocess.run(
+ [os.path.join(os.path.dirname(REAL["pip"]), "python"), "-c", probe],
+ capture_output = True,
+ text = True,
+ )
+ if out.returncode != 0 or not out.stdout.strip():
+ raise OSError(out.stderr.strip()[:200] or "no output")
+ gap = {f for f in out.stdout.split() if f.startswith("-")} - known
+ if gap:
+ missing["pip"] = sorted(gap)
+ except OSError as exc:
+ print(
+ f"[unsloth-nb] could not introspect pip's option table ({exc}); refusing to "
+ "certify the value-flag list from --help alone, which cannot see aliases.",
+ file = sys.stderr,
+ )
+ sys.exit(1)
+
+ seen_uv = False
+ for cmd in (
+ [REAL["uv"], "--help"],
+ [REAL["uv"], "pip", "--help"],
+ [REAL["uv"], "pip", "install", "--help"],
+ ):
+ try:
+ out = subprocess.run(cmd, capture_output = True, text = True).stdout
+ except OSError:
+ continue
+ seen_uv = True
+ flags = set()
+ for m in re.finditer(r"^\s+(-\w)?,?\s*(--[\w-]+)[= ]<", out, re.M):
+ if m.group(1):
+ flags.add(m.group(1))
+ flags.add(m.group(2))
+ for m in re.finditer(r"^\s+(-\w) <", out, re.M):
+ flags.add(m.group(1))
+ gap = flags - known
+ if gap:
+ missing.setdefault("uv", []).extend(sorted(gap))
+ if not seen_uv:
+ print("[unsloth-nb] could not run uv to check its flags", file = sys.stderr)
+ sys.exit(1)
+
+ # uv globals that are accepted but documented nowhere: verify each still takes a
+ # value, so the list rots loudly instead of silently.
+ for flag in sorted(_ALIAS_VALUE_FLAGS):
+ if flag == "--python-preference":
+ r = subprocess.run(
+ [REAL["uv"], flag, "system", "pip", "install", "--help"],
+ capture_output = True,
+ text = True,
+ )
+ if r.returncode != 0:
+ print(
+ f"[unsloth-nb] uv no longer accepts `{flag} <value>`; the entry in "
+ "_ALIAS_VALUE_FLAGS is stale and may now swallow an install target.",
+ file = sys.stderr,
+ )
+ sys.exit(1)
+
+ if missing:
+ print(f"[unsloth-nb] value flags missing from _VALUE_FLAGS: {missing}", file = sys.stderr)
+ sys.exit(1)
+ print("[unsloth-nb] value-flag selfcheck OK")
+ sys.exit(0)
+
+
+def _expand_short_clusters(argv):
+ """Split `-qr reqs.txt` into `-q -r reqs.txt`, which is what both real tools see.
+
+ A cluster reached no handler at all: only `tok[:2]` is tested against the
+ attached-value flags, the exact-token comparisons never match, and the fallback
+ keeps any unrecognised `-...` verbatim. So `pip install -qr reqs.txt` forwarded the
+ ORIGINAL requirements file, unfiltered and with nothing recorded, and `-I` hid
+ inside a cluster the same way and escaped the reinstall handling.
+
+ A value-taking short flag consumes the REST of the cluster as its attached value,
+ or the next argv token when it ends the cluster, exactly as getopt does.
+ """
+ shorts = {f for f in _VALUE_FLAGS if len(f) == 2 and f[0] == "-" and f[1] != "-"}
+ shorts |= _ATTACHED_SHORT_FLAGS
+ out = []
+ for tok in argv:
+ if len(tok) <= 2 or tok[0] != "-" or tok[1] == "-" or tok in _VALUE_FLAGS:
+ out.append(tok)
+ continue
+ i = 1
+ while i < len(tok):
+ flag = "-" + tok[i]
+ rest = tok[i + 1 :]
+ if flag in shorts:
+ out.append(flag + rest) # attached value, or bare when rest is empty
+ break
+ out.append(flag)
+ i += 1
+ else:
+ continue
+ return out
+
+
+def _install_index(tool, argv):
+ """Index of the install SUBCOMMAND, or None when this is not a package install.
+
+ pip's command path is `pip [opts] install`, but uv's is `uv [opts] pip [opts]
+ install`, and uv has other subcommands ending in `install`. A bare
+ argv.index("install") matched those too, which was not merely a wasted rewrite:
+ `uv python install 3.13` and `uv tool install ruff` got the protected
+ `--constraint` appended, which neither accepts, and `uv tool install transformers`
+ was filtered down to nothing and reported ok, installing NO tool at all.
+
+ So match the command path POSITIONALLY: `install` for pip, `pip install` for uv.
+ Finding it needs option VALUES skipped, not just options -- `uv pip --directory
+ /tmp install torch` is valid (uv lists --directory under Global options), and
+ treating `/tmp` as the subcommand loses the command entirely, which is the worst
+ outcome available here: the install runs unfiltered and unconstrained, free to
+ replace the baked torch/CUDA stack. _VALUE_FLAGS is the same set the tail scanner
+ uses and _selfcheck_value_flags() holds it to the real CLIs at build time."""
+ expect = ["install"] if tool == "pip" else ["pip", "install"]
+ got = _positionals(argv)
+ if len(got) < len(expect):
+ return None
+ for (idx, tok), want in zip(got, expect):
+ if tok != want:
+ return None
+ return got[len(expect) - 1][0]
+
+
+def _positionals(argv):
+ """(index, token) for every positional, skipping options AND their values.
+
+ `--flag=value` carries its own value; a bare value flag eats the next token.
+ _VALUE_FLAGS is the same set the tail scanner uses and _selfcheck_value_flags()
+ holds it to the real CLIs at build time."""
+ out = []
+ skip = False
+ for i, tok in enumerate(argv):
+ if skip:
+ skip = False
+ continue
+ if tok.startswith("-"):
+ if "=" not in tok and tok in _VALUE_FLAGS:
+ skip = True
+ continue
+ out.append((i, tok))
+ return out
+
+
+def _is_uv_pip_sync(argv):
+ """`uv pip sync` is an install path we cannot make safe by filtering.
+
+ It UNINSTALLS every package absent from the requirements file, so unlike install
+ there is nothing to strip: keeping a protected package out of the file is exactly
+ what deletes it, and --constraint only bounds versions, never prevents a removal.
+ """
+ return [tok for _, tok in _positionals(argv)][:2] == ["pip", "sync"]
+
+
+# Options that send the install somewhere OTHER than the venv this shim guards.
+# pip documents --target as "Install packages into <dir>" and --python as "Run pip
+# with the specified Python interpreter"; uv documents --python as "The Python
+# interpreter into which packages should be installed".
+_DEST_DIR_FLAGS = {"--target", "-t", "--prefix"}
+# --root is NOT a destination directory. pip documents it as "Install everything
+# relative to this alternate root directory" and applies it as a relocation PREFIX:
+# the computed scheme path is unchanged and then re-anchored under the root, so
+# `--root /` is the identity and still writes the venv's own site-packages. Measured:
+# `pip install --root / idna==3.6` put idna in the venv's purelib, while a real root
+# relocated it under that directory and left the venv untouched.
+_DEST_ROOT_FLAGS = {"--root"}
+_DEST_PYTHON_FLAGS = {"--python", "-p"}
+# pip honours PIP_<OPTION> for every option and uv documents --python as
+# [env: UV_PYTHON=]; both redirect with nothing on the command line at all.
+# Per TOOL, because each ignores the other's variables and a bypass granted on a
+# variable the invoked tool never reads is the dangerous direction: the install lands
+# in the baked venv with no filtering at all. Measured against both CLIs: pip honours
+# PIP_TARGET, PIP_PREFIX, PIP_ROOT and PIP_PYTHON and ignores UV_PYTHON; uv honours
+# UV_PYTHON, ignores every PIP_ variable, and has no environment form for its
+# --target/--prefix at all.
+# pip options that carry INSTALL TARGETS rather than a destination, in their
+# environment spelling. Both are space separated when they name more than one.
+# Flags that supply install TARGETS the shim cannot read. --group names a PEP 735
+# table inside a pyproject.toml (pip 25.3+ and uv), --requirements-from-script a PEP
+# 723 header inside a script (pip 26+). Measured: both are consumed for real, and a
+# group holding `unsloth @ file:///checkout` at the baked version installs over it
+# because pip reinstalls a same-version LOCAL PATH or sdist. --upgrade-group is NOT
+# here: `uv pip install` rejects it outright and pip has no such option, so it can
+# never supply a target on the command lines this shim sees.
+_UNINSPECTABLE_TARGET_FLAGS = {"--group", "--requirements-from-script"}
+_PIP_TARGET_ENV = {"PIP_REQUIREMENT": "-r", "PIP_EDITABLE": "-e"}
+_DEST_DIR_ENV = {"pip": ("PIP_TARGET", "PIP_PREFIX"), "uv": ()}
+# PIP_ROOT is the environment spelling of --root, so it relocates rather than names a
+# destination and has to be resolved the same way
+_DEST_ROOT_ENV = {"pip": ("PIP_ROOT",), "uv": ()}
+_DEST_PYTHON_ENV = {"pip": ("PIP_PYTHON",), "uv": ("UV_PYTHON",)}
+
+
+def _flag_values(argv, flags):
+ """Every value given for any of `flags`, in the spellings both tools accept:
+ separated, `--flag=value`, and a short flag with its value attached."""
+ out, want = [], False
+ for tok in argv:
+ if want:
+ out.append(tok)
+ want = False
+ continue
+ if tok in flags:
+ want = True
+ continue
+ for f in flags:
+ if tok.startswith(f + "="):
+ out.append(tok[len(f) + 1 :])
+ break
+ if len(f) == 2 and f[0] == "-" and f[1] != "-" and tok.startswith(f) and len(tok) > 2:
+ out.append(tok[2:])
+ break
+ return [v for v in out if v]
+
+
+def _base_venv_root():
+ """The venv that owns the REAL pip/uv, i.e. the one this shim exists to guard."""
+ return os.path.realpath(os.path.dirname(os.path.dirname(REAL["pip"])))
+
+
+def _relocated_under_root(root, path):
+ """Where `path` ends up once pip re-anchors it under `--root <root>`.
+
+ pip keeps the whole absolute path and hangs it beneath the root, so `--root /`
+ yields `path` itself and anything else lands outside the venv. Anchored on the
+ venv ROOT rather than on site-packages so it agrees with _inside_base_venv even
+ when the two are derived differently."""
+ _drive, rest = os.path.splitdrive(path)
+ return os.path.join(root, rest.lstrip(os.sep))
+
+
+def _inside_base_venv(path):
+ root = _base_venv_root()
+ resolved = os.path.realpath(path)
+ return resolved == root or resolved.startswith(root + os.sep)
+
+
+def _installs_elsewhere(tool, argv):
+ """True when this install is aimed at an environment that is NOT the baked venv.
+
+ Every reason to filter is about protecting that venv, so filtering an install
+ bound for somewhere else drops the packages the caller actually asked for and
+ then reports success having installed nothing.
+
+ Deliberately conservative: only a destination we can positively resolve OUTSIDE
+ the venv counts. A bare `--python python3` or `--python 3.12` may well name the
+ baked interpreter, so it keeps the protective behaviour. Environment variables
+ count only for the tool that actually reads them; a flag is left unscoped because
+ a tool that does not accept one fails loudly on it rather than silently."""
+ dirs = _flag_values(argv, _DEST_DIR_FLAGS)
+ dirs += [os.environ[v] for v in _DEST_DIR_ENV[tool] if os.environ.get(v)]
+ roots = _flag_values(argv, _DEST_ROOT_FLAGS)
+ roots += [os.environ[v] for v in _DEST_ROOT_ENV[tool] if os.environ.get(v)]
+ # a root re-anchors the venv's OWN paths beneath it, so resolve where each one
+ # actually lands rather than classifying the root value itself
+ dirs += [_relocated_under_root(r, _base_venv_root()) for r in roots]
+ if any(not _inside_base_venv(d) for d in dirs):
+ return True
+ pythons = _flag_values(argv, _DEST_PYTHON_FLAGS)
+ pythons += [os.environ[v] for v in _DEST_PYTHON_ENV[tool] if os.environ.get(v)]
+ return any((os.path.isabs(p) or os.sep in p) and not _inside_base_venv(p) for p in pythons)
+
+
+def main():
+ tool = "uv" if os.path.basename(sys.argv[0]).startswith("uv") else "pip"
+ argv = sys.argv[1:]
+
+ if argv[:1] == ["--unsloth-selfcheck-value-flags"]:
+ _selfcheck_value_flags()
+
+ if os.environ.get("UNSLOTH_NB_SHIM") != "1":
+ os.execv(REAL[tool], [REAL[tool]] + argv)
+ return
+
+ # Before the sync refusal as well: `uv pip sync --python <other>` only uninstalls
+ # from that other environment, so there is no baked stack for it to strip.
+ if _installs_elsewhere(tool, argv):
+ os.execv(REAL[tool], [REAL[tool]] + argv)
+ return
+
+ if tool == "uv" and _is_uv_pip_sync(argv):
+ raise SystemExit(
+ "[unsloth-nb] refusing `uv pip sync`: it UNINSTALLS every package missing "
+ "from the requirements file, which would strip the baked torch/CUDA stack "
+ "this image is built on, and no --constraint can prevent a removal. Use "
+ "`uv pip install -r <file>`, which adds without removing."
+ )
+
+ global _WORKING_DIR
+ _wd = _uv_working_dir(tool, argv)
+ _WORKING_DIR = os.path.abspath(_wd) if _wd else None
+
+ i = _install_index(tool, argv)
+ if i is None:
+ os.execv(REAL[tool], [REAL[tool]] + argv)
+ return
+
+ # after the install check, so a subcommand that merely mentions one of these is
+ # left alone, and after the destination bypass, so a group installed into another
+ # environment is not our problem
+ if _flag_values(argv, _UNINSPECTABLE_TARGET_FLAGS):
+ raise SystemExit(
+ "[unsloth-nb] refusing an install whose targets this shim cannot read: "
+ + " ".join(sorted(_UNINSPECTABLE_TARGET_FLAGS))
+ + ". A dependency group or a PEP 723 script block supplies package "
+ "specifications the same way a requirements file does, but they live "
+ "inside a pyproject.toml table or a script header rather than a plain "
+ "list, so they are forwarded uninspected: a same-version local path or "
+ "sdist naming a baked package resolves cleanly against the injected "
+ "constraints and replaces the stack this image is built on. Pass the "
+ "same requirements with `-r <file>`, which IS filtered."
+ )
+
+ # pip reads PIP_<OPTION> for every option, so a requirements file or an editable
+ # target can arrive with nothing on the command line to show for it. The scan below
+ # only walks argv, so `PIP_REQUIREMENT=/tmp/r.txt pip install packaging` filtered
+ # `packaging` and handed the real pip an uninspected file. The injected constraints
+ # do not save it: a same-version editable or direct reference resolves cleanly.
+ # Fold them in as ordinary flags so they go through the same filtering, and clear
+ # them from the child so the real tool cannot consume them a second time. uv has no
+ # environment form for --requirements, so this is pip-only.
+ env_tail = []
+ child_env = None
+ if tool == "pip":
+ for _var, _flag in _PIP_TARGET_ENV.items():
+ for _val in os.environ.get(_var, "").split():
+ env_tail += [_flag, _val]
+ if env_tail:
+ child_env = {k: v for k, v in os.environ.items() if k not in _PIP_TARGET_ENV}
+
+ head, tail = argv[: i + 1], env_tail + _expand_short_clusters(argv[i + 1 :])
+ keep_args, dropped, recorded = [], [], None
+ extras_only = []
+ has_target = False
+ skip_next = False
+ prev_flag = None
+ for tok in tail:
+ if skip_next:
+ if prev_flag in _REQ_FILE_FLAGS or prev_flag in _CONSTRAINT_FILE_FLAGS:
+ if "://" in tok:
+ if keep_args and keep_args[-1] == prev_flag:
+ keep_args.pop()
+ dropped.append(prev_flag + " " + tok)
+ elif prev_flag in _REQ_FILE_FLAGS:
+ _req_path, _req_rec, _req_drp = _filter_requirements_file(tok)
+ keep_args.append(_req_path)
+ has_target = True
+ if _req_rec and not recorded:
+ recorded = _req_rec
+ dropped.extend(_req_drp)
+ else:
+ _c_path, _c_rec, _c_drp = _filter_requirements_file(tok)
+ keep_args.append(_c_path)
+ dropped.extend(_c_drp)
+ elif prev_flag in _DROP_VALUE_FLAGS:
+ if keep_args and keep_args[-1] == prev_flag:
+ keep_args.pop()
+ dropped.append(prev_flag + " " + tok)
+ elif prev_flag in _EDITABLE_FLAGS or prev_flag in _UPGRADE_PKG_FLAGS:
+ _action, _ver = _classify_flag_target(tok)
+ if _action == "drop":
+ if _ver and not recorded:
+ recorded = _ver
+ dropped.append(prev_flag + " " + tok)
+ else:
+ keep_args.append(prev_flag)
+ keep_args.append(tok)
+ if prev_flag in _EDITABLE_FLAGS:
+ has_target = True
+ else:
+ keep_args.append(tok)
+ if prev_flag in _TARGET_VALUE_FLAGS:
+ has_target = True
+ skip_next = False
+ prev_flag = None
+ continue
+ if tok.startswith("--") and "=" in tok:
+ _flag, _, _val = tok.partition("=")
+ if _flag in _VALUE_FLAGS:
+ if (_flag in _REQ_FILE_FLAGS or _flag in _CONSTRAINT_FILE_FLAGS) and "://" in _val:
+ dropped.append(tok)
+ elif _flag in _REQ_FILE_FLAGS:
+ _req_path, _req_rec, _req_drp = _filter_requirements_file(_val)
+ keep_args.append(_flag + "=" + _req_path)
+ has_target = True
+ if _req_rec and not recorded:
+ recorded = _req_rec
+ dropped.extend(_req_drp)
+ elif _flag in _DROP_VALUE_FLAGS:
+ dropped.append(tok)
+ elif _flag in _CONSTRAINT_FILE_FLAGS:
+ _c_path, _c_rec, _c_drp = _filter_requirements_file(_val)
+ keep_args.append(_flag + "=" + _c_path)
+ dropped.extend(_c_drp)
+ elif _flag in _EDITABLE_FLAGS or _flag in _UPGRADE_PKG_FLAGS:
+ _action, _ver = _classify_flag_target(_val)
+ if _action == "drop":
+ if _ver and not recorded:
+ recorded = _ver
+ dropped.append(tok)
+ else:
+ keep_args.append(tok)
+ if _flag in _EDITABLE_FLAGS:
+ has_target = True
+ else:
+ keep_args.append(tok)
+ if _flag in _TARGET_VALUE_FLAGS:
+ has_target = True
+ continue
+ if len(tok) > 2 and tok[0] == "-" and tok[1] != "-" and tok[:2] in _ATTACHED_SHORT_FLAGS:
+ _sflag, _sval = tok[:2], tok[2:]
+ if (_sflag in _REQ_FILE_FLAGS or _sflag in _CONSTRAINT_FILE_FLAGS) and "://" in _sval:
+ dropped.append(_sflag + " " + _sval)
+ elif _sflag in _REQ_FILE_FLAGS:
+ _req_path, _req_rec, _req_drp = _filter_requirements_file(_sval)
+ keep_args.append(_sflag)
+ keep_args.append(_req_path)
+ has_target = True
+ if _req_rec and not recorded:
+ recorded = _req_rec
+ dropped.extend(_req_drp)
+ elif _sflag in _CONSTRAINT_FILE_FLAGS:
+ _c_path, _c_rec, _c_drp = _filter_requirements_file(_sval)
+ keep_args.append(_sflag)
+ keep_args.append(_c_path)
+ dropped.extend(_c_drp)
+ else: # -e / -P
+ _action, _ver = _classify_flag_target(_sval)
+ if _action == "drop":
+ if _ver and not recorded:
+ recorded = _ver
+ dropped.append(_sflag + " " + _sval)
+ else:
+ keep_args.append(_sflag)
+ keep_args.append(_sval)
+ if _sflag in _EDITABLE_FLAGS:
+ has_target = True
+ continue
+ if tok in _REINSTALL_FLAGS:
+ dropped.append(tok)
+ continue
+ if tok in _VALUE_FLAGS:
+ # hold -e/-P back so skip_next emits or drops the pair together
+ if tok not in _EDITABLE_FLAGS and tok not in _UPGRADE_PKG_FLAGS:
+ keep_args.append(tok)
+ skip_next = True
+ prev_flag = tok
+ continue
+ name = _canon(tok)
+ if name is None:
+ keep_args.append(tok)
+ if not tok.startswith("-"):
+ has_target = True
+ continue
+ if name == "transformers":
+ v = _version_pin(tok)
+ if v:
+ recorded = v
+ # same additive-extras rule as the protected branch below: the version is
+ # what the sidecar replaces, so only the pin is suppressed here
+ extras = _extras_only_target(tok) if _is_installed("transformers") else None
+ if extras is not None:
+ keep_args.append(extras)
+ extras_only.append(extras)
+ has_target = True
+ continue
+ dropped.append(tok)
+ continue
+ if _is_protected(name):
+ extras = _extras_only_target(tok)
+ if extras is not None:
+ keep_args.append(extras)
+ extras_only.append(extras)
+ has_target = True
+ continue
+ dropped.append(tok)
+ continue
+ keep_args.append(tok)
+ has_target = True
+
+ if extras_only:
+ print("[unsloth-nb] kept baked versions, adding extras only: " + " ".join(extras_only))
+ if recorded:
+ try:
+ parent = os.path.dirname(MARKER)
+ if parent: # "" for a bare relative MARKER, and makedirs("") raises
+ os.makedirs(parent, exist_ok = True)
+ with open(MARKER, "w") as f:
+ f.write(recorded)
+ except OSError as exc:
+ # do NOT abort: nothing has been installed or mis-forwarded, and the baked
+ # transformers still works, so hard-failing a notebook cell over an
+ # unwritable path the user cannot act on is the worse trade. But do not
+ # report success either: transformers is already out of the real arguments,
+ # so staying silent leaves the cell claiming the pin was honoured while the
+ # model cells import the baked version.
+ print(
+ f"[unsloth-nb] WARNING: could not record the requested "
+ f"transformers=={recorded} at {MARKER} ({exc}); the sidecar will NOT "
+ f"activate and the model cells will use the baked transformers.",
+ file = sys.stderr,
+ )
+ else:
+ print(
+ f"[unsloth-nb] notebook requested transformers=={recorded}; will "
+ f"activate its sidecar for the model cells (base stack kept)."
+ )
+ if dropped:
+ print("[unsloth-nb] kept baked versions, skipped: " + " ".join(dropped))
+
+ # only baked packages left: no-op rather than exec a bare install that fails
+ if not has_target:
+ print("[unsloth-nb] nothing to install after keeping the baked stack; ok.")
+ return
+ constraints = _protected_constraints_file()
+ if constraints:
+ # `--` ends option parsing for both real tools, so the pair must go first
+ try:
+ _eoo = keep_args.index("--")
+ except ValueError:
+ keep_args += ["--constraint", constraints]
+ else:
+ keep_args[_eoo:_eoo] = ["--constraint", constraints]
+ cmd = [REAL[tool]] + head + keep_args
+ sys.stdout.flush()
+ if child_env is not None:
+ os.execve(REAL[tool], cmd, child_env)
+ os.execv(REAL[tool], cmd)
+
+
+if __name__ == "__main__":
+ main()
diff --git a/docker/unsloth_run.py b/docker/unsloth_run.py
new file mode 100644
index 00000000000..d94d9d8a2dd
--- /dev/null
+++ b/docker/unsloth_run.py
@@ -0,0 +1,278 @@
+#!/opt/unsloth-venv/bin/python
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-Present the Unsloth team. See /studio/LICENSE.AGPL-3.0
+
+"""unsloth-run: execute an unslothai/notebooks notebook unchanged, headless.
+
+Resolves the transformers version the notebook wants (install-cell pin, else the
+model-name tier), launches the kernel with that sidecar on PYTHONPATH so the whole
+kernel process is coherent, and executes every cell with nbconvert.
+
+Usage:
+ unsloth-run <notebook.ipynb | URL> [--out OUT.ipynb] [--timeout SECONDS]
+ [--fetch-timeout SECONDS] # URL download stall limit (default 60)
+ [--transformers X.Y.Z] # force a version, skip auto-detect
+"""
+
+import argparse, json, os, re, shutil, stat, subprocess, sys, tempfile, urllib.request
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+try:
+ import unsloth_nb_compat as compat
+except Exception:
+ compat = None
+
+_MODEL_RE = re.compile(r"""from_pretrained\(\s*['"]([^'"]+)['"]""")
+_MODEL_NAME_RE = re.compile(r"""model_name\s*=\s*['"]([^'"]+)['"]""")
+
+# The install-cell scanner lives in unsloth_nb_compat, which is the copy the image puts
+# in site-packages and therefore the only one an IPython kernel can import. Sharing it
+# is what stops this path and the kernel hook from disagreeing about what counts as an
+# install line, which would put the kernel on one sidecar and the hook on another.
+if compat is not None:
+ _PIN_RE = compat._PIN_RE
+ _INSTALL_RE = compat._INSTALL_RE
+ _strip_comment = compat._strip_comment
+ _live_source = compat._live_source
+ _install_lines = compat._install_lines
+ _pin_from = compat.pin_from
+else:
+ # compat is also what turns a scan result into a sidecar, so with it gone there is
+ # nothing either half of the scan could select (see main, where sidecar stays None
+ # and the tier lookup is skipped). Degrade to no scan rather than keep a second
+ # copy of the rules here, which is the drift this move exists to prevent.
+ _PIN_RE = _INSTALL_RE = None
+ _strip_comment = _live_source = _install_lines = _pin_from = None
+
+
+DEFAULT_FETCH_TIMEOUT = int(os.environ.get("UNSLOTH_NOTEBOOK_FETCH_TIMEOUT", "60") or 60)
+
+
+def _load(path_or_url, fetch_timeout = None):
+ """Parsed notebook. A URL is fetched with a socket timeout: --timeout only ever
+ reached nbconvert, so a host that accepted the connection and then went quiet hung
+ the run before a single cell had executed. This bounds each blocking socket
+ operation, not the total transfer, which is what that failure needs; a server
+ trickling bytes forever is a different problem and not one seen here."""
+ if path_or_url.startswith(("http://", "https://")):
+ if fetch_timeout is None:
+ fetch_timeout = DEFAULT_FETCH_TIMEOUT
+ with urllib.request.urlopen( # nosec - user-provided nb
+ path_or_url, timeout = fetch_timeout
+ ) as r:
+ data = r.read().decode()
+ return json.loads(data)
+ with open(path_or_url) as f:
+ return json.load(f)
+
+
+def _scan(nb):
+ """(pinned_transformers, first_model_name); dead code must not count, as above."""
+ pin = model = None
+ if compat is None:
+ return pin, model
+ for cell in nb.get("cells", []):
+ if cell.get("cell_type") != "code":
+ continue
+ src = _live_source("".join(cell.get("source", [])))
+ if pin is None:
+ # the shared helper, not _PIN_RE directly: the pattern now matches any
+ # requirement name and the PEP 503 comparison that picks transformers out
+ # of it lives with it, so reading the match here would drop that half
+ pin = _pin_from(src)
+ if model is None:
+ m = _MODEL_RE.search(src) or _MODEL_NAME_RE.search(src)
+ if m:
+ model = m.group(1)
+ return pin, model
+
+
+def _makedirs_as_host(path):
+ """Create `path` owned by the nearest existing ancestor. mkdir(2) uses the CALLER's
+ uid/gid and only setgid carries down, so a new `--out sub/dir/` would be root-owned
+ and _stage_metadata would then give the OUTPUT that owner too."""
+ path = os.path.abspath(path)
+ missing = []
+ probe = path
+ while not os.path.isdir(probe):
+ missing.append(probe)
+ parent = os.path.dirname(probe)
+ if parent == probe:
+ break
+ probe = parent
+ os.makedirs(path, exist_ok = True)
+ if not missing:
+ return
+ try:
+ anchor = os.stat(probe)
+ except OSError:
+ return
+ for created in reversed(missing):
+ try:
+ os.chown(created, anchor.st_uid, anchor.st_gid)
+ except (OSError, AttributeError):
+ pass
+
+
+def _stage_metadata(staged, dest):
+ """Give the staged output the metadata the destination must end up with: mkstemp()
+ creates 0600, nbconvert truncates that same inode, and os.replace carries it onto
+ the destination. Best effort."""
+ try:
+ st = os.stat(dest)
+ except OSError:
+ # new output: the umask-derived mode a plain write would have produced
+ try:
+ umask = os.umask(0)
+ os.umask(umask)
+ os.chmod(staged, 0o666 & ~umask)
+ except OSError:
+ pass
+ try:
+ _dir = os.stat(os.path.dirname(os.path.abspath(dest)) or ".")
+ os.chown(staged, _dir.st_uid, _dir.st_gid)
+ except (OSError, AttributeError):
+ pass
+ return
+ try:
+ os.chmod(staged, stat.S_IMODE(st.st_mode))
+ except OSError:
+ pass
+ try:
+ os.chown(staged, st.st_uid, st.st_gid)
+ except (OSError, AttributeError):
+ pass
+
+
+def main():
+ ap = argparse.ArgumentParser(prog = "unsloth-run")
+ ap.add_argument("notebook")
+ ap.add_argument("--out")
+ ap.add_argument("--timeout", type = int, default = 3600)
+ ap.add_argument(
+ "--fetch-timeout",
+ dest = "fetch_timeout",
+ type = int,
+ default = DEFAULT_FETCH_TIMEOUT,
+ help = "seconds a URL fetch may stall before giving up (default 60)",
+ )
+ ap.add_argument("--transformers", dest = "tf")
+ args = ap.parse_args()
+
+ nb = _load(args.notebook, fetch_timeout = args.fetch_timeout)
+ pin, model = _scan(nb)
+ want = args.tf or pin or (compat.tier_for_model(model) if compat else None)
+ sidecar = compat.sidecar_for(want) if (compat and want) else None
+
+ tmp_dir = None
+ tmp_files = []
+ publish_from = None
+ if args.out:
+ out_path = os.path.abspath(args.out)
+ out_dir = os.path.dirname(out_path) or "."
+ _makedirs_as_host(out_dir)
+ if args.notebook.startswith(("http://", "https://")):
+ # A URL has no source tree to run in, so the download stays beside --out:
+ # that is the directory the run's own artifacts should land in.
+ fd, src_path = tempfile.mkstemp(prefix = ".unsloth-run-in-", suffix = ".ipynb", dir = out_dir)
+ with os.fdopen(fd, "w") as f:
+ json.dump(nb, f)
+ tmp_files.append(src_path)
+ else:
+ # nbconvert makes the INPUT notebook's directory the kernel cwd
+ # (Exporter.from_filename sets resources["metadata"]["path"] to it), so a
+ # staged copy under --out would resolve the notebook's relative opens,
+ # local imports and saves against the OUTPUT tree. Execute the original
+ # where it lives; only the result is staged beside --out.
+ src_path = args.notebook
+ fd, publish_from = tempfile.mkstemp(
+ prefix = ".unsloth-run-out-", suffix = ".ipynb", dir = out_dir
+ )
+ os.close(fd)
+ tmp_files.append(publish_from)
+ elif args.notebook.startswith(("http://", "https://")):
+ tmp_dir = tempfile.mkdtemp()
+ src_path = os.path.join(tmp_dir, os.path.basename(args.notebook.split("?")[0]))
+ with open(src_path, "w") as f:
+ json.dump(nb, f)
+ out_path = src_path
+ else:
+ src_path = args.notebook
+ out_path = src_path
+
+ env = dict(os.environ)
+ env["UNSLOTH_NB_SHIM"] = "1"
+ # Per-run marker, and ALWAYS a fresh one: an inherited value is never this run's.
+ # The IPython startup hook gives every kernel its own UNSLOTH_NB_TF_MARKER, so
+ # `!unsloth-run nb.ipynb` from a notebook cell inherits the CALLER's. Reusing it
+ # broke both ways: a target with a pin overwrote the caller kernel's pin, and a
+ # target with no pin ran against the caller's stale one. Either way a kernel that
+ # has not imported transformers yet can be handed the wrong sidecar.
+ fd, marker = tempfile.mkstemp(prefix = ".unsloth-run-tfmarker-")
+ os.close(fd)
+ env["UNSLOTH_NB_TF_MARKER"] = marker
+ tmp_files.append(marker)
+ if want:
+ open(marker, "w").write(want)
+ if sidecar:
+ env["PYTHONPATH"] = sidecar + os.pathsep + env.get("PYTHONPATH", "")
+ print(f"[unsloth-run] transformers {want} -> sidecar {sidecar}")
+ elif want:
+ print(f"[unsloth-run] transformers {want}: no sidecar (using base venv's newest)")
+ else:
+ print("[unsloth-run] no transformers pin/model tier detected; using base venv")
+
+ nbconvert_out = publish_from if publish_from is not None else out_path
+ cmd = [
+ "/opt/unsloth-venv/bin/jupyter",
+ "nbconvert",
+ "--to",
+ "notebook",
+ "--execute",
+ f"--ExecutePreprocessor.timeout={args.timeout}",
+ "--ExecutePreprocessor.kernel_name=python3",
+ src_path,
+ "--output",
+ os.path.basename(nbconvert_out),
+ "--output-dir",
+ os.path.dirname(os.path.abspath(nbconvert_out)) or ".",
+ ]
+ print(
+ "[unsloth-run] executing:",
+ os.path.basename(args.notebook.split("?")[0]) if args.out else os.path.basename(src_path),
+ )
+ try:
+ rc = subprocess.call(cmd, env = env)
+ if rc == 0 and publish_from is not None:
+ _stage_metadata(publish_from, out_path)
+ try:
+ os.replace(publish_from, out_path)
+ except OSError:
+ # rename(2) onto a bind-mounted OUTPUT FILE returns EBUSY even though
+ # the file is writable, and such a mount needs the inode write anyway
+ try:
+ with open(publish_from, "rb") as staged, open(out_path, "wb") as live:
+ shutil.copyfileobj(staged, live)
+ except OSError:
+ # keep the result rather than delete it: a run can be hours long
+ if publish_from in tmp_files:
+ tmp_files.remove(publish_from)
+ print(
+ f"[unsloth-run] could not publish to {out_path}; "
+ f"the executed notebook is at {publish_from}",
+ file = sys.stderr,
+ )
+ raise
+ finally:
+ if tmp_dir is not None:
+ shutil.rmtree(tmp_dir, ignore_errors = True)
+ for p in tmp_files:
+ try:
+ os.remove(p)
+ except OSError:
+ pass
+ sys.exit(rc)
+
+
+if __name__ == "__main__":
+ main()
diff --git a/docker/unsloth_studio_update.sh b/docker/unsloth_studio_update.sh
new file mode 100755
index 00000000000..22b976cf0bf
--- /dev/null
+++ b/docker/unsloth_studio_update.sh
@@ -0,0 +1,125 @@
+#!/usr/bin/env bash
+# Update Unsloth Studio in place, inside a running container, without pulling a
+# new image. Updates ONLY the Studio Python packages (the backend code and the
+# pre-built frontend, which ships inside the unsloth wheel) and restarts the
+# Studio service. The torch/CUDA stack is left untouched.
+#
+# docker exec <container> unsloth-studio-update # latest PyPI release
+# docker exec <container> unsloth-studio-update --ref main # latest git main
+# docker exec <container> unsloth-studio-update --with-deps # also update deps
+# docker exec <container> unsloth-studio-update --no-restart # update, restart later
+#
+# Not `unsloth studio update`: that re-runs the full installer, which re-probes the
+# host GPU for torch wheels and in a CPU-only container downgrades torch to CPU/cu126.
+#
+# Persistence: the update is written to the container's writable layer, so it
+# survives `docker restart`. To keep it across a full `docker rm` + `docker run`
+# (and to keep your chats/users/models), run Studio with its home on a named
+# volume: -v unsloth_studio_home:/opt/unsloth-studio
+set -euo pipefail
+
+STUDIO_HOME="${UNSLOTH_STUDIO_HOME:-/opt/unsloth-studio}"
+REF=""
+ZOO_REF=""
+NO_DEPS="--no-deps"
+RESTART=1
+PACKAGES="unsloth unsloth_zoo"
+
+usage() { sed -n '2,21p' "$0"; }
+
+while [ $# -gt 0 ]; do
+ case "$1" in
+ --ref) REF="$2"; shift 2;;
+ --zoo-ref) ZOO_REF="$2"; shift 2;;
+ --with-deps) NO_DEPS=""; shift;;
+ --no-restart) RESTART=0; shift;;
+ --packages) PACKAGES="$2"; shift 2;;
+ -h|--help) usage; exit 0;;
+ *) echo "unsloth-studio-update: unknown argument: $1" >&2; usage; exit 2;;
+ esac
+done
+
+PY=""
+for cand in \
+ "$STUDIO_HOME/unsloth_studio/bin/python" \
+ "$STUDIO_HOME/unsloth_studio/bin/python3"; do
+ [ -x "$cand" ] && { PY="$cand"; break; }
+done
+if [ -z "$PY" ] && [ -L "$STUDIO_HOME/bin/unsloth" ]; then
+ venv_bin="$(dirname "$(readlink -f "$STUDIO_HOME/bin/unsloth")")"
+ [ -x "$venv_bin/python" ] && PY="$venv_bin/python"
+fi
+[ -n "$PY" ] || { echo "unsloth-studio-update: could not find the Studio venv under $STUDIO_HOME" >&2; exit 1; }
+
+version_of() { "$PY" -c "from importlib.metadata import version; print(version('unsloth'))" 2>/dev/null || echo "unknown"; }
+
+echo "[studio-update] Studio venv: $PY"
+echo "[studio-update] before: unsloth $(version_of)"
+
+if [ -n "$REF" ]; then
+ SPECS="git+https://github.com/unslothai/unsloth.git@${REF}#egg=unsloth"
+ # unsloth-zoo does NOT track unsloth's tags
+ _zoo_ref="$ZOO_REF"
+ if [ -z "$_zoo_ref" ]; then
+ # git documents status 2 for "reached the remote, no matching ref"; any other
+ # non-zero means the lookup never happened, and falling through to main pairs
+ # the requested unsloth revision with an unrelated zoo one across a private API
+ _ls_rc=0
+ git ls-remote --exit-code https://github.com/unslothai/unsloth-zoo.git \
+ "$REF" >/dev/null 2>&1 || _ls_rc=$?
+ if [ "$_ls_rc" = "0" ]; then
+ _zoo_ref="$REF"
+ elif [ "$_ls_rc" = "2" ]; then
+ _zoo_ref="main"
+ echo "[studio-update] unsloth-zoo has no ref '${REF}'; using zoo main"
+ else
+ echo "unsloth-studio-update: could not reach unslothai/unsloth-zoo (git ls-remote exit ${_ls_rc}); refusing to guess the zoo ref." >&2
+ echo "unsloth-studio-update: retry, or pin it yourself with --zoo-ref <ref>." >&2
+ exit 1
+ fi
+ fi
+ SPECS="$SPECS git+https://github.com/unslothai/unsloth-zoo.git@${_zoo_ref}#egg=unsloth_zoo"
+ echo "[studio-update] installing from git: unsloth @${REF}, unsloth-zoo @${_zoo_ref}"
+else
+ SPECS="$PACKAGES"
+ echo "[studio-update] installing latest release of: $PACKAGES"
+fi
+
+# shellcheck disable=SC2086
+"$PY" -m pip install -U $NO_DEPS $SPECS
+
+echo "[studio-update] after: unsloth $(version_of)"
+
+# Restarting into code that cannot import kills a process that is serving fine and
+# leaves supervisord's studio program in FATAL, which it never leaves on its own.
+if ! "$PY" -c "import studio.backend.main" >/dev/null 2>&1; then
+ echo "[studio-update] ERROR: 'import studio.backend.main' failed after update." >&2
+ echo "[studio-update] A new dependency may be missing. Re-run with --with-deps:" >&2
+ echo "[studio-update] unsloth-studio-update --with-deps" >&2
+ echo "[studio-update] NOT restarting Studio, so the process already running keeps" >&2
+ echo "[studio-update] serving whatever it has already imported. That is the only" >&2
+ echo "[studio-update] thing still working: the venv on disk is ALREADY replaced." >&2
+ echo "[studio-update] Anything it imports lazily from here on fails the same way," >&2
+ echo "[studio-update] any restart parks Studio in FATAL, and because the venv lives" >&2
+ echo "[studio-update] under \$UNSLOTH_STUDIO_HOME, a persisted home keeps it broken" >&2
+ echo "[studio-update] across docker rm + docker run. Fix it before restarting." >&2
+ echo "[studio-update] Once fixed: supervisorctl restart studio" >&2
+ exit 1
+fi
+
+if [ "$RESTART" = "1" ]; then
+ SUPCTL="$(command -v supervisorctl || true)"
+ [ -n "$SUPCTL" ] || SUPCTL="/opt/unsloth-venv/bin/supervisorctl"
+ if [ -x "$SUPCTL" ] && "$SUPCTL" status studio >/dev/null 2>&1; then
+ echo "[studio-update] restarting the studio service"
+ "$SUPCTL" restart studio
+ else
+ echo "[studio-update] supervisor not managing 'studio' here; restart Studio yourself"
+ echo "[studio-update] (e.g. 'docker restart <container>')"
+ fi
+else
+ echo "[studio-update] --no-restart: restart Studio to load the update"
+ echo "[studio-update] docker exec <container> supervisorctl restart studio"
+fi
+
+echo "[studio-update] done"
diff --git a/docker/unsloth_sync_notebooks.sh b/docker/unsloth_sync_notebooks.sh
new file mode 100644
index 00000000000..2ef8cef1bee
--- /dev/null
+++ b/docker/unsloth_sync_notebooks.sh
@@ -0,0 +1,693 @@
+#!/usr/bin/env bash
+# Populate and refresh /workspace/unsloth-notebooks from unslothai/notebooks. The
+# user's edits always win: each written file's hash is recorded, and a file whose
+# hash differs is left untouched.
+#
+# Opt-out / tuning (all optional):
+# UNSLOTH_SKIP_NOTEBOOK_SYNC=1 do nothing (no populate, no refresh)
+# UNSLOTH_SKIP_NOTEBOOK_REFRESH=1 populate from the baked template only;
+# never touch the network
+# UNSLOTH_KEEP_DELETED_NOTEBOOKS=1 do not restore notebooks the user deleted
+# (default: deleted files are healed back)
+# UNSLOTH_KEEP_REMOVED_NOTEBOOKS=1 keep pristine notebooks that upstream deleted
+# or renamed (default: they are removed too)
+# UNSLOTH_NOTEBOOKS_DIR=<path> target dir (default /workspace/unsloth-notebooks)
+# UNSLOTH_NOTEBOOKS_REPO=<url> source repo (default unslothai/notebooks)
+# UNSLOTH_NOTEBOOK_FETCH_TIMEOUT=N seconds for each network op (default 60)
+# UNSLOTH_SKIP_NOTEBOOK_VIEW=1 do not build the categorized folder view
+# UNSLOTH_NOTEBOOKS_VIEW_DIR=<path> categorized view dir
+# (default "/workspace/Unsloth Notebooks")
+# UNSLOTH_NB_GPU=amd|cuda force AMD-* notebook visibility (default:
+# autodetect; AMD-* shown only on AMD/HIP)
+# UNSLOTH_KEEP_COLAB_INTRO=1 keep the Colab "Run all on Colab" sentence
+# (default: strip it for the Docker image)
+set -u
+
+TEMPLATE="${UNSLOTH_NOTEBOOKS_TEMPLATE:-/opt/unsloth-notebooks}"
+DEST="${UNSLOTH_NOTEBOOKS_DIR:-/workspace/unsloth-notebooks}"
+REMOTE="${UNSLOTH_NOTEBOOKS_REPO:-https://github.com/unslothai/notebooks}"
+STATE="$DEST/.unsloth_sync_state" # "sha256 relpath" of what we last wrote
+SYNCED="$DEST/.unsloth_sync_commit" # upstream commit we last synced to
+LOCK="$DEST/.unsloth_sync.lock" # serialises this script against itself
+PARTIAL="$DEST/.unsloth_sync_partial" # set when first-boot populate left files behind
+TIMEOUT="${UNSLOTH_NOTEBOOK_FETCH_TIMEOUT:-60}"
+LOCK_WAIT="${UNSLOTH_NOTEBOOK_LOCK_TIMEOUT:-600}"
+
+PYBIN="$(command -v python3 2>/dev/null || command -v python 2>/dev/null || true)"
+_self_dir="$(cd "$(dirname "$0")" 2>/dev/null && pwd)"
+resolve_helper() {
+ if [ -n "$1" ]; then printf '%s' "$1"; return 0; fi
+ if command -v "$2" >/dev/null 2>&1; then command -v "$2"; return 0; fi
+ [ -n "$_self_dir" ] && [ -f "$_self_dir/$3" ] && printf '%s' "$_self_dir/$3"
+ return 0
+}
+SIG_HELPER="$(resolve_helper "${UNSLOTH_NB_SIG_HELPER:-}" unsloth-nb-content-sig unsloth_nb_content_sig.py)"
+VIEW_HELPER="$(resolve_helper "${UNSLOTH_NB_VIEW_HELPER:-}" unsloth-nb-view unsloth_nb_view.py)"
+STRIP_HELPER="$(resolve_helper "${UNSLOTH_NB_STRIP_HELPER:-}" unsloth-nb-strip-colab unsloth_nb_strip_colab.py)"
+
+# so a refresh does not rewrite a notebook when only boilerplate moved
+middle_unchanged() {
+ case "$1" in *.ipynb) : ;; *) return 1 ;; esac
+ [ -n "$PYBIN" ] && [ -n "$SIG_HELPER" ] || return 1
+ [ "${UNSLOTH_NOTEBOOK_BODY_AWARE:-1}" = "1" ] || return 1
+ [ "$("$PYBIN" "$SIG_HELPER" "$1" "$2" 2>/dev/null)" = "SAME" ] || return 1
+ return 0
+}
+
+[ "${UNSLOTH_SKIP_NOTEBOOK_SYNC:-0}" = "1" ] && exit 0
+[ -d "$TEMPLATE" ] || exit 0
+
+hash_of() { sha256sum "$1" 2>/dev/null | cut -d' ' -f1; }
+
+# Give a file that has no destination to inherit from the mode a plain write would
+# have produced and the OWNER of the directory it lands in. Under -v $PWD:/workspace
+# that directory is the host user's, so without this the clone's or template's
+# root:root 0644 is published and they cannot edit their own notebook. This is the
+# new-file branch of unsloth_run.py's _stage_metadata, which the shell twin lacked.
+own_like_dir() {
+ chmod "$(printf '%03o' "$(( 0666 & ~0$(umask) ))")" "$1" 2>/dev/null || true
+ chown --reference="$2" "$1" 2>/dev/null || true
+ return 0
+}
+
+# rename swaps the DIRECTORY ENTRY, so without this the clone's root:root 0644 lands
+# on a bind-mounted notebook the host user owns. Best effort.
+stage_metadata() {
+ if [ ! -e "$2" ]; then
+ # A notebook upstream just added: no destination metadata exists, and
+ # returning here published the clone's ownership unchanged.
+ own_like_dir "$1" "$(dirname "$2")"
+ return 0
+ fi
+ chmod --reference="$2" "$1" 2>/dev/null || true
+ chown --reference="$2" "$1" 2>/dev/null || true
+ return 0
+}
+
+# plain `cp` truncates the existing inode and leaves its metadata alone, where
+# `cp -a` would chown the host user's file to root
+cp_keep_meta() {
+ if [ -e "$2" ]; then cp "$1" "$2" 2>/dev/null; else cp -a "$1" "$2" 2>/dev/null; fi
+}
+
+# mkdir(2) gives the new directory the CALLER's uid and only setgid carries down, so
+# a new category folder would land root:root. Anchored on the nearest existing
+# ancestor, not $DEST, because a bind mount can nest.
+mkdir_keep_owner() {
+ local dir="$1" anchor parent rest cur part
+ local -a parts
+ [ -d "$dir" ] && return 0
+ anchor="$dir"
+ while [ ! -d "$anchor" ]; do
+ parent="$(dirname "$anchor")"
+ [ "$parent" = "$anchor" ] && break
+ anchor="$parent"
+ done
+ mkdir -p "$dir" 2>/dev/null || return 0
+ [ -d "$anchor" ] || return 0
+ rest="${dir#"$anchor"}"
+ cur="$anchor"
+ IFS='/' read -r -a parts <<< "$rest"
+ for part in ${parts[@]+"${parts[@]}"}; do
+ [ -z "$part" ] && continue
+ cur="$cur/$part"
+ chown --reference="$anchor" "$cur" 2>/dev/null || true
+ done
+ return 0
+}
+
+# Created through the helper, not a plain `mkdir -p` earlier: $DEST is the anchor
+# every later mkdir_keep_owner and own_like_dir inherits from, so a root:root root
+# under a host-owned bind mount publishes root ownership down the whole tree.
+mkdir_keep_owner "$DEST"
+[ -d "$DEST" ] || exit 0
+
+# The refresh runs in a DETACHED child, so two copies mutate $DEST and $STATE at once
+# by design and a notebook the child copied while the parent hashed it is permanently
+# marked user-edited. One lock per invocation also fixes the ORDER.
+_LOCK_HELD=0
+lock_acquire() {
+ [ "$_LOCK_HELD" = "1" ] && return 0
+ command -v flock >/dev/null 2>&1 || return 0
+ # group-redirect: bash reports a failed exec redirection before applying it
+ { exec 9>>"$LOCK"; } 2>/dev/null || return 0
+ flock -w "$LOCK_WAIT" 9 2>/dev/null || return 0
+ _LOCK_HELD=1
+ return 0
+}
+lock_release() {
+ [ "$_LOCK_HELD" = "1" ] || return 0
+ _LOCK_HELD=0
+ flock -u 9 2>/dev/null || true
+ exec 9>&- 2>/dev/null || true
+ return 0
+}
+
+nb_gpu_is_amd() {
+ case "${UNSLOTH_NB_GPU:-}" in
+ amd|AMD|hip|HIP|rocm|ROCm|ROCM) return 0 ;;
+ cuda|CUDA|nvidia|NVIDIA|nv|NV) return 1 ;;
+ esac
+ if command -v nvidia-smi >/dev/null 2>&1 \
+ && nvidia-smi -L 2>/dev/null | grep -q '^GPU'; then
+ return 1
+ fi
+ if command -v rocm-smi >/dev/null 2>&1 || command -v rocminfo >/dev/null 2>&1; then
+ return 0
+ fi
+ return 1 # default: non-AMD, so AMD-* stay hidden
+}
+
+build_categorized_view() {
+ [ "${UNSLOTH_SKIP_NOTEBOOK_VIEW:-0}" = "1" ] && return 0
+ [ -n "$PYBIN" ] && [ -n "$VIEW_HELPER" ] || return 0
+ [ -d "$DEST/nb" ] || return 0
+ _view="${UNSLOTH_NOTEBOOKS_VIEW_DIR:-/workspace/Unsloth Notebooks}"
+ if nb_gpu_is_amd; then
+ "$PYBIN" "$VIEW_HELPER" "$DEST" "$_view" --amd 2>/dev/null || true
+ else
+ "$PYBIN" "$VIEW_HELPER" "$DEST" "$_view" 2>/dev/null || true
+ fi
+}
+
+strip_colab_intros() {
+ [ "${UNSLOTH_KEEP_COLAB_INTRO:-0}" = "1" ] && return 0
+ [ -n "$PYBIN" ] && [ -n "$STRIP_HELPER" ] || return 0
+ [ -f "$STATE" ] || return 0
+ "$PYBIN" "$STRIP_HELPER" --state "$STATE" --dest "$DEST" 2>/dev/null || true
+}
+
+# called explicitly BEFORE the fork, so the strip never overlaps the child's copy
+_FINALIZED=0
+finalize() {
+ [ "$_FINALIZED" = "1" ] && return 0
+ _FINALIZED=1
+ strip_colab_intros
+ build_categorized_view
+ return 0
+}
+trap 'finalize; lock_release' EXIT
+
+lock_acquire
+
+# Undo what section 1b restored when its state rewrite is abandoned. The old $STATE
+# is kept in that case and describes the tree as it was BEFORE these files came back,
+# so leaving them on disk would contradict it.
+undo_restores() {
+ [ "${#RESTORED_PATHS[@]}" -gt 0 ] || return 0
+ for _p in "${RESTORED_PATHS[@]}"; do
+ rm -f "$_p" 2>/dev/null || true
+ done
+ RESTORED_PATHS=()
+}
+
+
+record_state() {
+ : > "$STATE.tmp" 2>/dev/null || return 0
+ ( cd "$DEST" && find . -type f -print0 ) | while IFS= read -r -d '' rel; do
+ rel="${rel#./}"
+ case "$rel" in
+ .unsloth_sync_state|.unsloth_sync_state.tmp|.unsloth_sync_commit) continue ;;
+ .unsloth_sync.lock|.unsloth_sync_partial) continue ;;
+ esac
+ printf '%s %s\n' "$(hash_of "$DEST/$rel")" "$rel" >> "$STATE.tmp"
+ done
+ mv "$STATE.tmp" "$STATE" 2>/dev/null || rm -f "$STATE.tmp"
+}
+
+# 1) First-boot populate. Re-runs when the last one left files behind: a file with no
+# state entry is never restored by 1b, and stamping the marker anyway makes 2) exit
+# early too. Process substitution, not a pipeline, so the counter survives the loop.
+if [ ! -f "$STATE" ] || [ -f "$PARTIAL" ]; then
+ # Same leftover as the refresh child clears below: a run killed between the
+ # truncate and the mv leaves $STATE.tmp behind, and when that run was a different
+ # uid (root once, then --user) the truncate here cannot empty it. Without the
+ # unlink the appends below fail one by one while the loop keeps going, and the mv
+ # -- which needs write on $DEST, not on the file -- then publishes the FOREIGN
+ # file as our state: every notebook this run copied is missing from it, so run 2
+ # reads them all as user edits and never refreshes them again, and the commit
+ # marker is stamped anyway because no copy failed.
+ rm -f "$STATE.tmp" 2>/dev/null || true
+ populate_failed=0
+ # Set only when the merge loop below loses a record. Those are the sole records for
+ # notebooks that exist upstream but not in the baked template, so nothing can
+ # re-derive them; a failed COPY, by contrast, is re-walked from the template on the
+ # next boot, which is why that case still publishes.
+ merge_lost=0
+ stage_ok=1
+ if ! : > "$STATE.tmp" 2>/dev/null; then
+ # Still unstageable, so $DEST itself is the problem. Nothing has been copied
+ # yet, so bail like the refresh child does: leave the marker off and retry on
+ # the next start rather than publish notebooks we cannot record.
+ echo "[unsloth-nb] the sync state could not be staged in $DEST; leaving the sync marker off so the next start retries"
+ stage_ok=0
+ fi
+ while IFS= read -r -d '' rel; do
+ [ "$stage_ok" = 1 ] || continue
+ rel="${rel#./}"
+ case "$rel" in .unsloth_template_commit) continue ;; esac
+ mkdir_keep_owner "$DEST/$(dirname "$rel")"
+ # user data: do NOT record it, else the refresh reads it as pristine
+ if [ -e "$DEST/$rel" ]; then
+ if [ "$(hash_of "$DEST/$rel")" != "$(hash_of "$TEMPLATE/$rel")" ]; then
+ echo "[unsloth-nb] kept existing user file: $DEST/$rel"
+ continue
+ fi
+ # same bytes already there, so copying would only stamp root:root on it
+ # Every append is checked: staging the temp file proves DEST was writable
+ # once, not that it stays so. A quota or ENOSPC that lands here leaves the
+ # notebook on disk with no record, and an unrecorded file is read as a user
+ # edit and never refreshed again. Count it exactly like a failed copy, so
+ # the marker stays off and the next start retries.
+ printf '%s %s\n' "$(hash_of "$DEST/$rel")" "$rel" >> "$STATE.tmp" \
+ || populate_failed=$((populate_failed + 1))
+ continue
+ fi
+ if cp -a "$TEMPLATE/$rel" "$DEST/$rel" 2>/dev/null; then
+ # cp -a preserves the TEMPLATE's root:root 0644; hand it to the host user.
+ own_like_dir "$DEST/$rel" "$(dirname "$DEST/$rel")"
+ printf '%s %s\n' "$(hash_of "$DEST/$rel")" "$rel" >> "$STATE.tmp" \
+ || populate_failed=$((populate_failed + 1))
+ else
+ populate_failed=$((populate_failed + 1))
+ fi
+ done < <(cd "$TEMPLATE" && find . -type f -print0)
+ # A RETRY must not throw away what we already manage. Between the failed populate
+ # and this run the refresh published newer bytes for template files and added
+ # notebooks that exist only upstream, and the loop above sees both as user files:
+ # the newer ones differ from the template so they hit the "kept existing user
+ # file" branch, and the upstream-only ones are never visited at all. Keeping only
+ # this loop's records hands all of them to the user permanently, while the commit
+ # marker below is stamped anyway, so it looks converged.
+ # -r, not just -f. Without set -e a failed redirect below simply skips the loop,
+ # so an unreadable $STATE silently contributes NO preserved records and the merged
+ # state is published without them. These are the only records for notebooks that
+ # exist upstream but not in the baked template, and nothing can re-derive them.
+ if [ "$stage_ok" = 1 ] && [ -f "$STATE" ] && [ ! -r "$STATE" ]; then
+ echo "[unsloth-nb] the sync state in $DEST is unreadable; leaving it alone rather than republishing it without the records it holds"
+ stage_ok=0
+ fi
+ if [ "$stage_ok" = 1 ] && [ -f "$STATE" ]; then
+ declare -A POPULATED=()
+ while IFS= read -r line; do
+ p="${line#* }"
+ [ -n "$p" ] && [ "$p" != "$line" ] && POPULATED["$p"]=1
+ done < "$STATE.tmp"
+ while IFS= read -r line; do
+ p="${line#* }"
+ [ -n "$p" ] && [ "$p" != "$line" ] || continue
+ [ -n "${POPULATED[$p]:-}" ] && continue
+ # same reason as the copy loop: a dropped record here hands a notebook the
+ # refresh already manages to the user permanently
+ printf '%s\n' "$line" >> "$STATE.tmp" \
+ || { populate_failed=$((populate_failed + 1)); merge_lost=1; }
+ done < "$STATE"
+ unset POPULATED
+ fi
+ # Only publish a COMPLETE state. Section 1b already states this rule and follows
+ # it; this sibling published the short one and merely withheld the marker, which is
+ # not equivalent here: the merge loop above is the only source of records for
+ # notebooks that exist upstream but not in the baked template, and unlike the
+ # refresh child there is no rollback to compensate. Discarding is recoverable
+ # instead -- the old state keeps those records, and with no old state at all the
+ # next boot re-runs this populate from the template.
+ if [ "$stage_ok" = 1 ] && [ "$merge_lost" -eq 0 ]; then
+ mv "$STATE.tmp" "$STATE" 2>/dev/null || rm -f "$STATE.tmp"
+ else
+ rm -f "$STATE.tmp" 2>/dev/null || true
+ fi
+ if [ "$stage_ok" != 1 ]; then
+ : > "$PARTIAL" 2>/dev/null || true
+ rm -f "$SYNCED" 2>/dev/null || true
+ elif [ "$populate_failed" -eq 0 ]; then
+ rm -f "$PARTIAL" 2>/dev/null || true
+ cp -a "$TEMPLATE/.unsloth_template_commit" "$SYNCED" 2>/dev/null || true
+ echo "[unsloth-nb] notebooks ready at $DEST"
+ else
+ : > "$PARTIAL" 2>/dev/null || true
+ rm -f "$SYNCED" 2>/dev/null || true
+ echo "[unsloth-nb] $populate_failed notebook(s) could not be written; leaving the sync marker off so the next start retries"
+ fi
+fi
+
+if [ -f "$STATE" ] && [ "${UNSLOTH_KEEP_DELETED_NOTEBOOKS:-0}" != "1" ]; then
+ restored=0
+ downgraded=0
+ # Beside $STATE, exactly like the other two writers, and for the reasons bee9e5a52
+ # gives for the refresh child. mktemp puts it in /tmp, which in the shipped image
+ # is the container overlay while $DEST is a bind mount, so the publish below was a
+ # cross-device copy that can leave a HALF-WRITTEN state behind rather than an
+ # atomic same-directory rename. mktemp also creates 0600 owned by whoever booted,
+ # so this was the one writer that re-owned and downgraded $STATE, undoing what
+ # own_like_dir and mkdir_keep_owner exist to preserve: a root boot then left it
+ # unreadable to a later --user boot.
+ RS_TMP="$STATE.tmp"
+ # Same class as the populate loop: an unchecked append publishes a state that is
+ # missing records for notebooks still on disk, which hands them to the user for
+ # good. Here the old $STATE is still valid, so abandon the rewrite rather than
+ # publish a truncated one.
+ rs_ok=1
+ # Everything this loop puts back, so a doomed rewrite can be undone. These files
+ # were ABSENT before the loop ran, so removing them restores the exact prior state
+ # rather than discarding anything a user has.
+ RESTORED_PATHS=()
+ rm -f "$RS_TMP" 2>/dev/null || true
+ if ! : > "$RS_TMP" 2>/dev/null; then
+ rs_ok=0
+ fi
+ # An unreadable $STATE must not quietly become an EMPTY one. There is no set -e, so
+ # a failed redirect below just skips the loop body: rs_ok stays 1 and the mv
+ # publishes a zero-line state over a valid one, stranding every notebook it
+ # described while still reporting success.
+ if [ "$rs_ok" = 1 ] && [ ! -r "$STATE" ]; then
+ echo "[unsloth-nb] the sync state in $DEST is unreadable; leaving it alone rather than replacing it with an empty one"
+ rs_ok=0
+ fi
+ [ "$rs_ok" = 1 ] && while IFS= read -r line; do
+ # re-tested INSIDE the loop, like the populate loop's `stage_ok || continue`.
+ # Evaluating it once let a failed append keep restoring files the state would
+ # never record, leaving them at BAKED content while the kept state holds
+ # post-refresh hashes: the next refresh then reads every one as a user edit.
+ [ "$rs_ok" = 1 ] || continue
+ h="${line%% *}"; rel="${line#* }"
+ if [ -n "$rel" ] && [ "$rel" != "$line" ] \
+ && [ ! -e "$DEST/$rel" ] && [ -f "$TEMPLATE/$rel" ]; then
+ mkdir_keep_owner "$DEST/$(dirname "$rel")"
+ if cp -a "$TEMPLATE/$rel" "$DEST/$rel" 2>/dev/null; then
+ # cp -a preserves the TEMPLATE's root:root 0644; hand it to the host user.
+ own_like_dir "$DEST/$rel" "$(dirname "$DEST/$rel")"
+ RESTORED_PATHS+=("$DEST/$rel")
+ new_h="$(hash_of "$DEST/$rel")"
+ printf '%s %s\n' "$new_h" "$rel" >> "$RS_TMP" || rs_ok=0
+ restored=$((restored + 1))
+ # The record was ahead of the baked copy, so this notebook has just
+ # gone BACKWARDS to whatever the image shipped. The refresh child
+ # exits on remote == last, so leaving the marker alone would strand
+ # it there until upstream happened to commit again.
+ [ "$new_h" != "$h" ] && downgraded=$((downgraded + 1))
+ continue
+ fi
+ fi
+ printf '%s\n' "$line" >> "$RS_TMP" || rs_ok=0
+ done < "$STATE"
+ if [ "$rs_ok" = 1 ]; then
+ # loud, and drop the marker, exactly like the sibling branch three lines down:
+ # a silent failure here left the "restored N" success message printing over a
+ # state that was never published
+ mv "$RS_TMP" "$STATE" 2>/dev/null || {
+ echo "[unsloth-nb] the sync state could not be published in $DEST; keeping the previous state and dropping the sync marker so the next start retries"
+ rm -f "$RS_TMP"
+ undo_restores
+ rm -f "$SYNCED" 2>/dev/null || true
+ }
+ else
+ echo "[unsloth-nb] the sync state could not be rewritten in $DEST; keeping the previous state and dropping the sync marker so the next start retries"
+ rm -f "$RS_TMP"
+ undo_restores
+ rm -f "$SYNCED" 2>/dev/null || true
+ fi
+ # Only when one actually went backwards: dropping the marker on every restore
+ # would make an ordinary delete cost a full clone even when the baked copy was
+ # already current, and the marker is re-stamped as soon as the refresh succeeds.
+ if [ "$downgraded" -gt 0 ]; then
+ rm -f "$SYNCED" 2>/dev/null || true
+ fi
+ [ "$restored" -gt 0 ] \
+ && echo "[unsloth-nb] restored $restored deleted notebook(s) from the baked set ($downgraded needing a refresh)"
+fi
+
+# 2) Best-effort GitHub refresh, detached because ls-remote + clone can spend 2x
+# TIMEOUT when offline and must not delay container startup.
+[ "${UNSLOTH_SKIP_NOTEBOOK_REFRESH:-0}" = "1" ] && exit 0
+command -v git >/dev/null 2>&1 || exit 0
+command -v sha256sum >/dev/null 2>&1 || exit 0
+if [ "${UNSLOTH_NB_REFRESH_CHILD:-0}" != "1" ]; then
+ # BEFORE the fork: the EXIT trap fired while the child was already copying
+ finalize
+ lock_release
+ UNSLOTH_NB_REFRESH_CHILD=1 "$0" >/dev/null 2>&1 &
+ exit 0
+fi
+
+# --- refresh child ---
+# the parent already finalized, so re-arm below only if this refresh rewrites anything
+_FINALIZED=1
+
+last="$(cat "$SYNCED" 2>/dev/null || true)"
+remote="$(timeout "$TIMEOUT" git ls-remote "$REMOTE" HEAD 2>/dev/null | cut -f1)"
+[ -z "$remote" ] && exit 0 # offline: keep what we have
+[ "$remote" = "$last" ] && exit 0
+
+TMP="$(mktemp -d)"
+if ! timeout "$TIMEOUT" git clone -q --depth 1 "$REMOTE" "$TMP" 2>/dev/null; then
+ rm -rf "$TMP"; exit 0 # network died mid-way: keep what we have
+fi
+
+# The refresh child reads the state the same way, and this is the copy that runs in
+# the default configuration. Without set -e the redirect below just fails, LAST stays
+# empty, every notebook is counted `kept` rather than recorded, and TMPSTATE publishes
+# EMPTY over a valid state with failed still 0, so the marker is stamped. Section 1b's
+# own recovery drops $SYNCED, which guarantees this child does not exit early and
+# walks straight into it.
+if [ -f "$STATE" ] && [ ! -r "$STATE" ]; then
+ echo "[unsloth-nb] the sync state in $DEST is unreadable; skipping the refresh rather than republishing it empty"
+ rm -rf "$TMP"
+ exit 0
+fi
+
+declare -A LAST
+if [ -f "$STATE" ]; then
+ while read -r h p; do
+ [ -n "${p:-}" ] && LAST["$p"]="$h"
+ done < "$STATE"
+fi
+
+# Beside $STATE, like the two writers above, NOT in /tmp. A sibling makes the publish
+# an atomic same-directory rename that cannot half-succeed, and it makes the state fail
+# with the notebooks instead of independently of them: a $DEST that is full or
+# read-only fails the notebook writes too, which already holds the marker back. From
+# /tmp the move was a cross-device copy that could fail on its own, after the notebooks
+# had landed, and no marker check can undo that -- the stale hashes then read every
+# freshly written notebook as user-edited for good.
+TMPSTATE="$STATE.tmp"
+# No /tmp fallback: it would fire in exactly the case the sibling exists to prevent.
+# $DEST unwritable while a notebook subdir still is publishes the new bytes and then
+# cannot record them, and run two reads every one of them as a user edit, which is
+# `kept`, not `failed`, so the marker IS stamped and they are stranded for good.
+# Nothing has been published yet here, so bailing costs only this cycle. Same shape as
+# record_state's abort above and the mid-clone bail below.
+# Clear a leftover first. A run killed between the truncate and the mv leaves one
+# behind, and if that run was a different uid (root once, then --user) it cannot be
+# truncated even though $DEST is writable, which would make the bail below permanent.
+# Unlinking needs write on $DEST, which the real bail case does not have, so this
+# cannot weaken the guard.
+rm -f "$TMPSTATE" 2>/dev/null || true
+if ! : > "$TMPSTATE" 2>/dev/null; then
+ echo "[unsloth-nb] the sync state could not be staged in $DEST; leaving the sync marker so the next start retries"
+ rm -rf "$TMP"
+ exit 0
+fi
+updated=0; kept=0; unchanged=0; failed=0
+# Every append to the staged state must be checked. Losing a record here (ENOSPC,
+# quota) while `failed` stays 0 publishes a truncated state AND advances the marker,
+# which is exactly the wedge described at the publish step below: the next boot exits
+# on remote == last, and once upstream moves, every notebook whose hash we dropped
+# reads as user-edited and is kept forever. Counting it as a failure reuses the retry
+# path the copy failures already take. The three sites that already increment `failed`
+# are left alone: their gate fires regardless of whether the append landed.
+record_tmpstate() {
+ printf '%s %s\n' "$1" "$2" >> "$TMPSTATE"
+}
+
+# A record we could not write cannot be left alone, whatever else went wrong first.
+# Counting the failure only withholds the marker for THIS run: the truncated state is
+# published regardless, so the next refresh finds no entry, reads the file as a user
+# edit, keeps it, sees nothing fail and stamps the marker over it. Removing our own
+# copy is the only recovery that does not need the disk space that just ran out, and
+# it is safe exactly while the file still hashes to what we last published. A
+# user-edited file is left alone, which is the outcome it would have had anyway.
+drop_unrecordable() {
+ local _d="$DEST/$1"
+ [ -e "$_d" ] || return 0
+ [ "$(hash_of "$_d")" = "${LAST[$1]:-}" ] || return 0
+ rm -f "$_d" 2>/dev/null || true
+}
+
+unrecorded() {
+ failed=$((failed + 1))
+ drop_unrecordable "$1"
+}
+while IFS= read -r -d '' f; do
+ rel="${f#"$TMP"/}"
+ case "$rel" in .git|.git/*) continue ;; esac
+ dst="$DEST/$rel"
+ if [ -e "$dst" ]; then
+ rec="${LAST[$rel]:-}"
+ if [ -z "$rec" ]; then
+ # An unrecorded file that is byte-identical to the clone is not a user
+ # edit. It is one WE published and then failed to record, which is what
+ # the rollback above leaves behind whenever it cannot unlink: a single
+ # FILE bind mount gives EBUSY there exactly as it does for the rename at
+ # line 562. Without this the file stays unrecorded for good, so the next
+ # refresh keeps reading it as a user edit and stamps the marker over it.
+ # Adopting the record costs nothing, because the bytes on disk already
+ # ARE the bytes we would publish, so nothing of the user's can be lost.
+ adopted="$(hash_of "$dst")"
+ if [ -n "$adopted" ] && [ "$adopted" = "$(hash_of "$f")" ]; then
+ record_tmpstate "$adopted" "$rel" || failed=$((failed + 1))
+ unchanged=$((unchanged + 1))
+ continue
+ fi
+ kept=$((kept + 1))
+ continue
+ fi
+ if [ -n "$rec" ] && [ "$(hash_of "$dst")" != "$rec" ]; then
+ record_tmpstate "$rec" "$rel" || unrecorded "$rel"
+ kept=$((kept + 1))
+ continue
+ fi
+ if [ -n "$rec" ] && middle_unchanged "$dst" "$f"; then
+ # a changed package spec is NOT cosmetic and falls through below
+ record_tmpstate "$rec" "$rel" || unrecorded "$rel"
+ unchanged=$((unchanged + 1))
+ continue
+ fi
+ elif [ -n "${LAST[$rel]:-}" ] && [ "${UNSLOTH_KEEP_DELETED_NOTEBOOKS:-0}" = "1" ]; then
+ record_tmpstate "${LAST[$rel]}" "$rel" || unrecorded "$rel"
+ kept=$((kept + 1))
+ continue
+ fi
+ mkdir_keep_owner "$(dirname "$dst")"
+ # Same-dir temp + rename: JupyterLab is already serving $DEST, and an in-place
+ # cp -a exposes half-written JSON and destroys a save made since the hash check.
+ new="$(dirname "$dst")/.unsloth_nb_new.$$"
+ if cp -a "$f" "$new" 2>/dev/null; then
+ # hash what is about to be PUBLISHED: re-reading $dst after the rename would
+ # record a save that landed meanwhile as the pristine version
+ staged="$(hash_of "$new")"
+ if [ -e "$dst" ] && [ "$(hash_of "$dst")" != "${LAST[$rel]:-}" ]; then
+ rm -f "$new"
+ record_tmpstate "${LAST[$rel]:-}" "$rel" || unrecorded "$rel"
+ kept=$((kept + 1))
+ continue
+ fi
+ stage_metadata "$new" "$dst"
+ # a single-FILE bind mount cannot be renamed over (EBUSY)
+ if mv -f "$new" "$dst" 2>/dev/null || { rm -f "$new"; cp_keep_meta "$f" "$dst"; }; then
+ # $staged, not hash_of "$dst": both branches write the bytes of "$f"
+ if record_tmpstate "$staged" "$rel"; then
+ updated=$((updated + 1))
+ else
+ failed=$((failed + 1))
+ # PUBLISHED but not recordable, the one combination that cannot be left
+ # alone. Withholding the marker is not enough: the truncated state is
+ # still published below, so the NEXT refresh reads this file as a user
+ # edit, keeps it, finds nothing failed and stamps the marker over it --
+ # unmanaged for good. Discarding the whole staged state instead would
+ # strand every notebook this run DID record, which is worse.
+ # We only get here when $dst was absent or hashed exactly to our own
+ # previous record, so it holds no user edit and removing it costs
+ # nothing: the next refresh re-copies and re-records it. The unlink
+ # also gives back the space that just ran out.
+ rm -f "$dst" 2>/dev/null || true
+ fi
+ else
+ # carry the PREVIOUS record forward, or the next refresh reads $dst as
+ # user-owned and keeps the stale copy forever
+ record_tmpstate "${LAST[$rel]:-}" "$rel" || drop_unrecordable "$rel"
+ failed=$((failed + 1))
+ fi
+ else
+ record_tmpstate "${LAST[$rel]:-}" "$rel" || drop_unrecordable "$rel"
+ failed=$((failed + 1))
+ fi
+done < <(find "$TMP" -type f -print0)
+
+# Upstream deleted or renamed it. The loop above only walks the CLONE, so without
+# this the copy we published stays on disk while its record is dropped: the next
+# refresh reads it as user-owned, and unsloth_nb_view.py files it under "Other
+# Notebooks" for good. Over the last year upstream deleted 10 and renamed 7 nb/
+# notebooks, so these accumulate. Only a file that still hashes to what WE wrote is
+# removed, so an edited notebook stays; it merely stops being managed, which it had
+# already stopped being.
+removed=0
+if [ "${#LAST[@]}" -gt 0 ]; then
+ # A case-only rename upstream looks like a deletion here, because the clone is on
+ # a case-sensitive filesystem while $DEST may be a macOS or Windows bind mount
+ # where the old path resolves to the file just published.
+ declare -A CLONED_LOWER=()
+ while IFS= read -r -d '' f; do
+ p="${f#"$TMP"/}"
+ case "$p" in .git|.git/*) continue ;; esac
+ CLONED_LOWER["${p,,}"]=1
+ done < <(find "$TMP" -type f -print0)
+ for rel in "${!LAST[@]}"; do
+ [ -e "$TMP/$rel" ] && continue
+ [ -n "${CLONED_LOWER[${rel,,}]:-}" ] && continue
+ dst="$DEST/$rel"
+ [ -f "$dst" ] || continue
+ [ -n "${LAST[$rel]}" ] || continue
+ [ "$(hash_of "$dst")" = "${LAST[$rel]}" ] || continue
+ if [ "${UNSLOTH_KEEP_REMOVED_NOTEBOOKS:-0}" = "1" ]; then
+ # Keep the record WITH the file, exactly as UNSLOTH_KEEP_DELETED_NOTEBOOKS
+ # does above. Skipping the whole block dropped the record of a file it had
+ # deliberately kept, so the next refresh read it as a user edit -- and
+ # turning the option back off never recovered it, because by then it is no
+ # longer in LAST.
+ # and do NOT drop it if that append fails. Every other caller can drop a
+ # file it could not record because the clone still holds a copy to
+ # re-publish next start. This one cannot: upstream DELETED it, so the
+ # file on disk is the last copy in existence and removing it destroys
+ # exactly what the option was set to preserve, unrecoverably -- not by a
+ # retry, not by turning the option back off. Counting it failed holds the
+ # marker back so the next start retries the record.
+ record_tmpstate "${LAST[$rel]}" "$rel" || failed=$((failed + 1))
+ continue
+ fi
+ if rm -f "$dst" 2>/dev/null; then
+ removed=$((removed + 1))
+ # one level, and never $DEST itself: `rmdir -p` would climb out of it
+ d="$(dirname "$dst")"
+ [ "$d" != "$DEST" ] && rmdir "$d" 2>/dev/null
+ else
+ # A writable single-FILE bind mount cannot be unlinked (EBUSY), the same
+ # case the publish above has to work around. The file stays, so its record
+ # has to stay with it: dropping it here would leave the stale copy on disk
+ # with nothing claiming it, and the next refresh would read it as
+ # user-owned and never retry. Counting it failed also holds the sync
+ # marker back, which is what makes the retry happen at all.
+ record_tmpstate "${LAST[$rel]}" "$rel" || drop_unrecordable "$rel"
+ failed=$((failed + 1))
+ fi
+ done
+ unset CLONED_LOWER
+fi
+
+# The state has to land before the marker does, so a failed publish holds the marker
+# back like any other write failure. Stamping over it wedges the tree for good: the
+# next boot exits on remote == last, and once upstream finally moves, the stale hashes
+# no longer match the notebooks this run just wrote, so every one of them reads as
+# user-edited and is kept forever.
+published=1
+mv "$TMPSTATE" "$STATE" 2>/dev/null || { rm -f "$TMPSTATE"; published=0; }
+# recording the commit after a failure makes the next boot exit on remote == last
+if [ "$failed" -eq 0 ] && [ "$published" -eq 1 ]; then
+ # Renamed into place like the state above: a root boot leaves the marker root-owned
+ # 0644, so a later --user boot could publish the state but not truncate the marker,
+ # and every start after that re-synced every notebook while reporting success.
+ { printf '%s\n' "$remote" > "$SYNCED.tmp" && mv -f "$SYNCED.tmp" "$SYNCED"; } 2>/dev/null || {
+ rm -f "$SYNCED.tmp" 2>/dev/null || true
+ echo "[unsloth-nb] the sync marker could not be written in $DEST; the next start will refresh again"
+ }
+elif [ "$published" -eq 0 ]; then
+ echo "[unsloth-nb] the sync state could not be written; leaving the sync marker so the next start retries"
+else
+ echo "[unsloth-nb] $failed notebook(s) could not be written; leaving the sync marker so the next start retries"
+fi
+rm -rf "$TMP"
+echo "[unsloth-nb] notebooks refreshed from GitHub: $updated updated, $kept kept (your edits), $unchanged kept (only header/footer changed upstream), $removed removed upstream"
+if [ "$updated" -gt 0 ] || [ "$removed" -gt 0 ]; then
+ _FINALIZED=0
+ finalize
+fi
+exit 0
diff --git a/install.sh b/install.sh
index ded02f4292d..fa26c7d2d40 100755
--- a/install.sh
+++ b/install.sh
@@ -3086,6 +3086,11 @@ case "$0" in
[ "$STUDIO_LOCAL_INSTALL" = true ] && [ -r "$0" ] && _REPO_IS_CHECKOUT=1 ;;
esac
+# Honor UNSLOTH_ZOO_REF so the Studio venv tracks the requested zoo (the Docker
+# publish workflow forwards one ref to both builds). Unset means main.
+_ZOO_REF="${UNSLOTH_ZOO_REF:-main}"
+_ZOO_GIT_SPEC="unsloth-zoo @ git+https://github.com/unslothai/unsloth-zoo@${_ZOO_REF}"
+
# ── Helper: find no-torch-runtime.txt (local repo or site-packages) ──
_find_no_torch_runtime() {
# Check local repo first (for --local installs)
@@ -5259,10 +5264,10 @@ if [ "$_MIGRATED" = true ]; then
if [ "$STUDIO_LOCAL_INSTALL" = true ]; then
substep "overlaying local repo (editable)..."
run_install_cmd "overlay local repo" uv pip install --python "$_VENV_PY" -e "$_REPO_ROOT" --no-deps
- substep "overlaying unsloth-zoo from git main..."
- run_install_cmd_retry "overlay unsloth-zoo (git main)" uv pip install --python "$_VENV_PY" \
+ substep "overlaying unsloth-zoo from git ${_ZOO_REF}..."
+ run_install_cmd_retry "overlay unsloth-zoo (git ${_ZOO_REF})" uv pip install --python "$_VENV_PY" \
--no-deps --reinstall-package unsloth-zoo \
- "unsloth-zoo @ git+https://github.com/unslothai/unsloth-zoo"
+ "$_ZOO_GIT_SPEC"
fi
if [ "$SKIP_TORCH" = false ] && [ "$_torch_index_is_rocm_family" = true ]; then
if _is_gfx906_bnb_skip; then
@@ -5456,10 +5461,10 @@ elif [ -n "$TORCH_INDEX_URL" ]; then
if [ "$STUDIO_LOCAL_INSTALL" = true ]; then
substep "overlaying local repo (editable)..."
run_install_cmd "overlay local repo" uv pip install --python "$_VENV_PY" -e "$_REPO_ROOT" --no-deps
- substep "overlaying unsloth-zoo from git main..."
- run_install_cmd_retry "overlay unsloth-zoo (git main)" uv pip install --python "$_VENV_PY" \
+ substep "overlaying unsloth-zoo from git ${_ZOO_REF}..."
+ run_install_cmd_retry "overlay unsloth-zoo (git ${_ZOO_REF})" uv pip install --python "$_VENV_PY" \
--no-deps --reinstall-package unsloth-zoo \
- "unsloth-zoo @ git+https://github.com/unslothai/unsloth-zoo"
+ "$_ZOO_GIT_SPEC"
fi
elif [ "$STUDIO_LOCAL_INSTALL" = true ]; then
run_install_cmd_retry "install unsloth (local)" uv pip install --python "$_VENV_PY" \
@@ -5467,10 +5472,10 @@ elif [ -n "$TORCH_INDEX_URL" ]; then
--upgrade-package unsloth "$_unsloth_release_install_spec" "unsloth-zoo>=2026.9.1"
substep "overlaying local repo (editable)..."
run_install_cmd "overlay local repo" uv pip install --python "$_VENV_PY" -e "$_REPO_ROOT" --no-deps
- substep "overlaying unsloth-zoo from git main..."
- run_install_cmd_retry "overlay unsloth-zoo (git main)" uv pip install --python "$_VENV_PY" \
+ substep "overlaying unsloth-zoo from git ${_ZOO_REF}..."
+ run_install_cmd_retry "overlay unsloth-zoo (git ${_ZOO_REF})" uv pip install --python "$_VENV_PY" \
--no-deps --reinstall-package unsloth-zoo \
- "unsloth-zoo @ git+https://github.com/unslothai/unsloth-zoo"
+ "$_ZOO_GIT_SPEC"
else
_unsloth_install_pkg="$PACKAGE_NAME"
if [ "$PACKAGE_NAME" = "unsloth" ] && [ -n "$_unsloth_desktop_install_spec" ]; then
@@ -5498,10 +5503,10 @@ else
run_install_cmd_retry "install unsloth (auto torch backend)" uv pip install --python "$_VENV_PY" "unsloth-zoo>=2026.9.1" "$_unsloth_release_install_spec" --torch-backend=auto
substep "overlaying local repo (editable)..."
run_install_cmd "overlay local repo" uv pip install --python "$_VENV_PY" -e "$_REPO_ROOT" --no-deps
- substep "overlaying unsloth-zoo from git main..."
- run_install_cmd_retry "overlay unsloth-zoo (git main)" uv pip install --python "$_VENV_PY" \
+ substep "overlaying unsloth-zoo from git ${_ZOO_REF}..."
+ run_install_cmd_retry "overlay unsloth-zoo (git ${_ZOO_REF})" uv pip install --python "$_VENV_PY" \
--no-deps --reinstall-package unsloth-zoo \
- "unsloth-zoo @ git+https://github.com/unslothai/unsloth-zoo"
+ "$_ZOO_GIT_SPEC"
else
case "$PACKAGE_NAME" in
unsloth)
diff --git a/studio/install_llama_prebuilt.py b/studio/install_llama_prebuilt.py
index 733544d61c0..0f2a31fab7a 100644
--- a/studio/install_llama_prebuilt.py
+++ b/studio/install_llama_prebuilt.py
@@ -541,6 +541,14 @@ _os_error_messages = _core._os_error_messages
is_busy_lock_error = _core.is_busy_lock_error
+def is_cross_device_error(exc: BaseException) -> bool:
+ """True for an EXDEV "cross-device link" rename failure, e.g. inside a Docker
+ build where the staging tree and the install dir land on different overlayfs
+ layers. Unlike a busy/in-use error, such a move is safely completed by copy +
+ remove of the (idle) source."""
+ return isinstance(exc, OSError) and exc.errno == errno.EXDEV
+
+
# Status logs default to stderr so resolver modes keep stdout machine-readable
# (setup.sh json.load()s the whole stdout). main() flips this for the install
# path, where PowerShell otherwise renders stderr as NativeCommandError noise.
@@ -4465,22 +4473,96 @@ def activate_staged_dir(staging_dir: Path, dst: Path) -> None:
``os.replace`` failure means the directory is genuinely in use, and a
silent copy + ``rmtree`` could partially delete a live install.
- Only busy/lock errors (``is_busy_lock_error``) trigger the copy; anything
- else (disk full, cross-device, missing path) re-raises so it cannot leave
- a partially copied install behind. A copy is preferred over retrying the
- rename because antivirus scans of large DLLs can outlast any reasonable
- retry window.
+ Only busy/lock errors (``is_busy_lock_error``) and cross-device links
+ (``is_cross_device_error``, hit when a Docker build lands the staging tree
+ and the install dir on different overlay layers) trigger the copy; anything
+ else (disk full, missing path) re-raises so it cannot leave a partially
+ copied install behind. A copy is preferred over retrying the rename because
+ antivirus scans of large DLLs can outlast any reasonable retry window.
"""
try:
os.replace(staging_dir, dst)
except OSError as exc:
- if not is_busy_lock_error(exc):
+ # busy/in-use (Windows AV) or cross-device (Docker overlayfs) are both safe to
+ # complete by copy + remove; anything else re-raises
+ if not (is_busy_lock_error(exc) or is_cross_device_error(exc)):
raise
log(f"os.replace failed ({exc!r}); falling back to file-by-file copy of staging tree")
- shutil.copytree(staging_dir, dst, dirs_exist_ok = True)
+ # symlinks = True, like the aside-move and rollback-restore copies below. The
+ # default DEREFERENCES every link, so each soname alias is written out as a
+ # full second copy of its library. Measured on the linux-x64-cuda12 bundle
+ # this branch exists for (Docker overlayfs EXDEV): 5 symlinks, 13.1 MiB
+ # duplicated. Not the headline number one might expect -- the 358 MB
+ # libggml-cuda.so is a regular file and is copied once either way -- but it is
+ # wasted bytes and it replaces the link topology the loader resolves against.
+ # dirs_exist_ok stays for the empty-dst case
+ # os.replace also accepts; a NON-empty dst never reaches here on one device
+ # (ENOTEMPTY re-raises above), and if a partially removed aside-move left one
+ # behind, os.symlink's FileExistsError fails the activation into the rollback
+ # path instead of silently half-merging two installs.
+ shutil.copytree(staging_dir, dst, dirs_exist_ok = True, symlinks = True)
remove_tree(staging_dir)
+def move_install_dir_aside(
+ src: Path,
+ dst: Path,
+ *,
+ busy_retry: bool = False,
+) -> None:
+ """Move an existing install dir to ``dst`` (a unique, non-existent sibling).
+
+ os.replace is the fast path, falling back to copy + remove on EXDEV. A busy/in-use
+ failure is deliberately NOT copy-faked: the source is a live install and a partial
+ copy + rmtree would be worse than failing.
+
+ ``busy_retry`` is opt-in per call site: the aside-move of the *live* install is the
+ one this installer most needs to survive, while the recovery path's move of an
+ already-failed tree has a cheaper answer (drop the tree) than blocking on a scanner.
+
+ Callers treat ``dst.exists()`` as proof of a COMPLETE tree, so the copy goes to a
+ temp sibling and is published with one atomic rename; a copy that dies halfway
+ leaves nothing at ``dst`` and ``src`` untouched.
+ """
+ try:
+ if busy_retry:
+ replace_with_busy_retry(src, dst)
+ else:
+ os.replace(src, dst)
+ except OSError as exc:
+ if not is_cross_device_error(exc):
+ raise
+ if _is_link_or_junction(src):
+ # copytree always follows the ROOT it is given, so copying a linked
+ # install would duplicate a checkout this installer does not own
+ log("install path is a link; not copying it aside")
+ raise
+ copy_tmp = dst.with_name(dst.name + ".copying")
+ counter = 0
+ while copy_tmp.exists():
+ counter += 1
+ copy_tmp = dst.with_name(f"{dst.name}.copying-{counter}")
+ log(f"os.replace cross-device ({exc!r}); copy+publish {src} -> {dst}")
+ try:
+ # symlinks = True, matching the rollback-restore copy below. The default
+ # DEREFERENCES links inside the tree, and a Linux llama.cpp bundle is full
+ # of soname links (libllama.so.0 -> libllama.so), so the aside copy would
+ # duplicate every shared library and, restored after a failed activation,
+ # replace the install's link topology with independent files. Safe here
+ # only because copy_tmp is a fresh uniquified path: combined with
+ # dirs_exist_ok it raises FileExistsError on any name the destination
+ # already holds, which is why the remaining dirs_exist_ok calls in this
+ # file (which merge into populated trees) cannot simply be given the same
+ # flag. activate_staged_dir can, because a dst os.replace refused is empty
+ # or absent.
+ shutil.copytree(src, copy_tmp, symlinks = True)
+ os.replace(copy_tmp, dst)
+ except BaseException:
+ remove_tree(copy_tmp)
+ raise
+ remove_tree(src)
+
+
def activate_install_tree(staging_dir: Path, install_dir: Path, host: HostInfo) -> None:
rollback_dir: Path | None = None
failed_dir: Path | None = None
@@ -4491,7 +4573,7 @@ def activate_install_tree(staging_dir: Path, install_dir: Path, host: HostInfo)
had_existing = True
rollback_dir = unique_install_side_path(install_dir, "rollback")
log(f"moving existing install to rollback path {rollback_dir}")
- replace_with_busy_retry(install_dir, rollback_dir)
+ move_install_dir_aside(install_dir, rollback_dir, busy_retry = True)
moved_aside = True
log(f"moved existing install to rollback path {rollback_dir.name}")
@@ -4526,7 +4608,10 @@ def activate_install_tree(staging_dir: Path, install_dir: Path, host: HostInfo)
failed_dir = unique_install_side_path(install_dir, "failed")
log(f"moving failed active install to {failed_dir}")
try:
- os.replace(install_dir, failed_dir)
+ # not a bare os.replace: in a Docker build the failed tree and
+ # the staging root can sit on different overlay layers, and EXDEV
+ # there must not cost the retained copy
+ move_install_dir_aside(install_dir, failed_dir)
except Exception as failed_move_exc:
failed_dir = None
log(f"failed active install could not be moved aside: {failed_move_exc}")
diff --git a/studio/install_python_stack.py b/studio/install_python_stack.py
index 62007701f56..ffede8b3bce 100644
--- a/studio/install_python_stack.py
+++ b/studio/install_python_stack.py
@@ -5565,6 +5565,30 @@ def _shared_base_requirements() -> Path | None:
return None
+_UNSLOTH_ZOO_GIT_URL = "unsloth-zoo @ git+https://github.com/unslothai/unsloth-zoo"
+
+
+def _unsloth_zoo_ref() -> str:
+ """The unsloth-zoo git ref the --local overlay installs.
+
+ UNSLOTH_ZOO_REF lets the Studio venv track the requested zoo instead of
+ always main, which is what the Docker build pins against and what
+ install.sh reads into _ZOO_REF. Unset means main.
+ """
+ return os.environ.get("UNSLOTH_ZOO_REF", "").strip() or "main"
+
+
+def _unsloth_zoo_git_spec() -> str:
+ """The pip requirement string for the unsloth-zoo overlay.
+
+ An unset UNSLOTH_ZOO_REF leaves the URL bare rather than appending @main: a
+ bare git URL already clones the default branch, so the default install is
+ byte for byte the one every caller and the staging path already expect.
+ """
+ ref = os.environ.get("UNSLOTH_ZOO_REF", "").strip()
+ return _UNSLOTH_ZOO_GIT_URL + ("@" + ref if ref else "")
+
+
def _overlay_local_core_package(
name: str,
local_repo: str,
@@ -5583,9 +5607,10 @@ def _overlay_local_core_package(
install_label = "Overlaying local repo (editable)"
args = ("-e", local_repo)
elif canonical == "unsloth-zoo":
- step_label = "overlaying unsloth-zoo from git main"
- install_label = "Overlaying unsloth-zoo from git main"
- args = ("--force-reinstall", "unsloth-zoo @ git+https://github.com/unslothai/unsloth-zoo")
+ zoo_ref = _unsloth_zoo_ref()
+ step_label = f"overlaying unsloth-zoo from git {zoo_ref}"
+ install_label = f"Overlaying unsloth-zoo from git {zoo_ref}"
+ args = ("--force-reinstall", _unsloth_zoo_git_spec())
else:
return False
_step(_LABEL, step_label)
@@ -5631,7 +5656,7 @@ def _overlay_source_spec(name: str, local_repo: str) -> str:
if canonical == "unsloth":
return local_repo
if canonical == "unsloth-zoo":
- return "unsloth-zoo @ git+https://github.com/unslothai/unsloth-zoo"
+ return _unsloth_zoo_git_spec()
return ""
@@ -6922,6 +6947,8 @@ def install_python_stack() -> int:
package_name = os.environ.get("STUDIO_PACKAGE_NAME", "unsloth")
# --local overlays a local repo checkout after updating deps.
local_repo = os.environ.get("STUDIO_LOCAL_REPO", "")
+ # read where the overlay runs, so UNSLOTH_ZOO_REF reaches the metadata-repair
+ # reinstall path too, not just the two calls below
# Clean-machine CI overlays only unsloth, not the full local source pair.
ci_source_overlay = os.environ.get("UNSLOTH_CI_SOURCE_OVERLAY", "")
# +1 for the anyio repair check (step 8b), +1 for the diffusers pin (step 11b, every platform)
diff --git a/tests/python/test_docker_build_ref_resolution.py b/tests/python/test_docker_build_ref_resolution.py
new file mode 100644
index 00000000000..a768fe33dfe
--- /dev/null
+++ b/tests/python/test_docker_build_ref_resolution.py
@@ -0,0 +1,125 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved.
+
+"""docker/build.sh must hand docker a COMMIT, not a branch name.
+
+Docker matches a RUN layer on the command string alone -- "the files updated in the
+container aren't examined to determine if a cache hit exists" -- so a build arg that
+stays "main" makes the pip-install-from-git layer a cache hit on every rebuild and the
+image keeps the commits of the first build while the build reports success. The publish
+workflow already freezes both refs with git ls-remote; the local script has to as well.
+"""
+
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+import pytest
+
+REPO_ROOT = Path(__file__).resolve().parents[2]
+BUILD_SH = REPO_ROOT / "docker" / "build.sh"
+
+pytestmark = pytest.mark.skipif(shutil.which("bash") is None, reason = "needs bash")
+
+UNSLOTH_SHA = "a" * 40
+ZOO_SHA = "b" * 40
+NB_SHA = "c" * 40
+
+
+def _stub(path: Path, body: str) -> None:
+ path.write_text("#!/usr/bin/env bash\n" + body, encoding = "utf-8")
+ path.chmod(0o755)
+
+
+def _run(
+ tmp_path: Path,
+ git_body: str,
+ env_extra: dict[str, str] | None = None,
+):
+ bin_dir = tmp_path / "bin"
+ bin_dir.mkdir()
+ args_file = tmp_path / "docker-args.txt"
+ _stub(bin_dir / "git", git_body)
+ _stub(bin_dir / "docker", f'printf "%s\\n" "$@" > {args_file}\n')
+ # no network: the llama.cpp tag lookup must not reach github from a unit test
+ _stub(bin_dir / "curl", "exit 1\n")
+
+ env = dict(os.environ)
+ env["PATH"] = f"{bin_dir}{os.pathsep}{env['PATH']}"
+ env.update(env_extra or {})
+ proc = subprocess.run(
+ ["bash", str(BUILD_SH)],
+ env = env,
+ capture_output = True,
+ text = True,
+ cwd = str(tmp_path),
+ )
+ assert proc.returncode == 0, proc.stdout + proc.stderr
+ argv = args_file.read_text(encoding = "utf-8").splitlines() if args_file.exists() else []
+ return proc, argv
+
+
+def _build_arg(argv: list[str], name: str) -> str:
+ for index, item in enumerate(argv):
+ if item == "--build-arg" and argv[index + 1].startswith(f"{name}="):
+ return argv[index + 1].split("=", 1)[1]
+ raise AssertionError(f"--build-arg {name} was never passed: {argv}")
+
+
+LS_REMOTE_STUB = f"""
+if [ "$1" = "ls-remote" ]; then
+ case "$2" in
+ *unsloth-zoo*) echo -e "{ZOO_SHA}\\tHEAD" ;;
+ *notebooks*) echo -e "{NB_SHA}\\tHEAD" ;;
+ *) echo -e "{UNSLOTH_SHA}\\tHEAD" ;;
+ esac
+ exit 0
+fi
+exit 0
+"""
+
+
+def test_the_default_main_refs_are_frozen_to_commits(tmp_path):
+ _proc, argv = _run(tmp_path, LS_REMOTE_STUB)
+ assert _build_arg(argv, "UNSLOTH_REF") == UNSLOTH_SHA, (
+ "a mutable 'main' build arg is byte-identical across rebuilds, so docker "
+ "reuses the cached install layer and silently ships a stale image"
+ )
+ assert _build_arg(argv, "UNSLOTH_ZOO_REF") == ZOO_SHA
+ # the baked notebooks are the same shape of mutable-ref RUN layer, and the
+ # publish workflow already freezes this one
+ assert _build_arg(argv, "UNSLOTH_NOTEBOOKS_REF") == NB_SHA
+
+
+def test_an_explicit_tag_is_frozen_too(tmp_path):
+ _proc, argv = _run(
+ tmp_path, LS_REMOTE_STUB, {"UNSLOTH_REF": "v2026.5.6", "UNSLOTH_ZOO_REF": "v2026.5.4"}
+ )
+ assert _build_arg(argv, "UNSLOTH_REF") == UNSLOTH_SHA
+ assert _build_arg(argv, "UNSLOTH_ZOO_REF") == ZOO_SHA
+
+
+def test_a_sha_is_passed_through_without_a_lookup(tmp_path):
+ sha = "c" * 40
+ _proc, argv = _run(
+ tmp_path,
+ 'if [ "$1" = "ls-remote" ]; then echo "ls-remote should not run" >&2; exit 3; fi\nexit 0\n',
+ {"UNSLOTH_REF": sha, "UNSLOTH_ZOO_REF": sha},
+ )
+ assert _build_arg(argv, "UNSLOTH_REF") == sha
+ assert _build_arg(argv, "UNSLOTH_ZOO_REF") == sha
+
+
+def test_an_unreachable_remote_warns_and_still_builds(tmp_path):
+ proc, argv = _run(tmp_path, 'if [ "$1" = "ls-remote" ]; then exit 128; fi\nexit 0\n')
+ assert _build_arg(argv, "UNSLOTH_REF") == "main", "offline: the name is passed through"
+ assert _build_arg(argv, "UNSLOTH_NOTEBOOKS_REF") == "main"
+ assert "unreachable" in proc.stdout + proc.stderr
+
+
+if __name__ == "__main__":
+ sys.exit(pytest.main([__file__, "-v"]))
diff --git a/tests/python/test_docker_cpu_fallback.py b/tests/python/test_docker_cpu_fallback.py
new file mode 100644
index 00000000000..86945773f9a
--- /dev/null
+++ b/tests/python/test_docker_cpu_fallback.py
@@ -0,0 +1,193 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved.
+"""The :latest cutover: unsloth/unsloth:latest is the Studio image, so a plain
+`docker run unsloth/unsloth` has to survive a host with no NVIDIA GPU.
+
+Two independent failure points, one per class below:
+ * the DAEMON rejects `--gpus` before the container exists (exit 125), so
+ entrypoint.sh never runs -- docker/run.sh has to stop asking for it;
+ * entrypoint.sh itself exits 1 without UNSLOTH_ALLOW_CPU, so the Studio image
+ has to default it on.
+"""
+
+import os
+import shutil
+import stat
+import subprocess
+
+import pytest
+
+_HERE = os.path.dirname(os.path.abspath(__file__))
+_DOCKER = os.path.join(os.path.dirname(os.path.dirname(_HERE)), "docker")
+
+_RUN_SH = os.path.join(_DOCKER, "run.sh")
+_STUDIO_DF = os.path.join(_DOCKER, "Dockerfile.studio")
+_BASE_DF = os.path.join(_DOCKER, "Dockerfile")
+_ENTRYPOINT = os.path.join(_DOCKER, "entrypoint.sh")
+
+
+def _stub(path, body):
+ with open(path, "w") as f:
+ f.write("#!/usr/bin/env bash\n" + body)
+ os.chmod(path, os.stat(path).st_mode | stat.S_IEXEC | stat.S_IXGRP | stat.S_IXOTH)
+
+
+def _invoke_run_sh(
+ tmp_path,
+ *,
+ nvidia,
+ amd,
+ groups = "both",
+):
+ """Run docker/run.sh with a recording `docker` stub and a staged /dev tree.
+
+ Returns the argv docker/run.sh would have handed to `docker run`.
+ """
+ bindir = tmp_path / "bin"
+ bindir.mkdir()
+ argv_log = tmp_path / "argv"
+
+ # `docker run` must not exec anything real; record argv and stop.
+ _stub(
+ str(bindir / "docker"),
+ 'if [ "$1" = "info" ]; then echo " Runtimes: io.containerd.runc.v2 runc"; exit 0; fi\n'
+ 'printf "%s\\n" "$@" > ' + str(argv_log) + "\nexit 0\n",
+ )
+ # nvidia-smi is ALWAYS shadowed. /usr/bin has to stay on PATH for cut/grep/getent,
+ # and a CI or dev host with a real GPU there would otherwise make the
+ # "no NVIDIA" case unreachable and pass this test vacuously.
+ if nvidia:
+ _stub(str(bindir / "nvidia-smi"), 'echo "GPU 0: NVIDIA H100 (UUID: GPU-abc)"\n')
+ else:
+ # driver present but zero GPUs: the harder of the two no-GPU shapes, and it
+ # covers the missing-binary shape too (same && chain, same outcome)
+ _stub(str(bindir / "nvidia-smi"), "exit 1\n")
+
+ # getent is ALWAYS shadowed too, for the same reason as nvidia-smi: this host has
+ # both video and render, so relying on the real one made the missing-group cases
+ # unreachable and the AMD test green for the wrong reason.
+ known = {"both": ("44", "992"), "video_only": ("44", None), "none": (None, None)}
+ vid, ren = known[groups]
+ _stub(
+ str(bindir / "getent"),
+ 'case "$2" in\n'
+ + (f' video) echo "video:x:{vid}:"; exit 0 ;;\n' if vid else " video) exit 2 ;;\n")
+ + (f' render) echo "render:x:{ren}:"; exit 0 ;;\n' if ren else " render) exit 2 ;;\n")
+ + "esac\nexit 2\n",
+ )
+
+ dev_root = tmp_path / "root"
+ (dev_root / "dev").mkdir(parents = True)
+ if nvidia:
+ (dev_root / "dev" / "nvidiactl").write_text("")
+ if amd:
+ (dev_root / "dev" / "kfd").write_text("")
+ (dev_root / "dev" / "dri").mkdir()
+
+ env = dict(os.environ)
+ # PATH is replaced, not prepended: a real nvidia-smi on this host would
+ # otherwise make the "no NVIDIA" case unreachable.
+ env["PATH"] = str(bindir) + ":/usr/bin:/bin"
+ env["UNSLOTH_DEV_ROOT"] = str(dev_root)
+ env["HOME"] = str(tmp_path / "home")
+ env["UNSLOTH_WORKDIR"] = str(tmp_path)
+ for leak in ("HF_TOKEN", "WANDB_API_KEY", "UNSLOTH_GPUS", "UNSLOTH_ALLOW_CPU"):
+ env.pop(leak, None)
+
+ # absolute: the "absent" case strips /usr/bin from PATH, so `bash` itself would
+ # not resolve either
+ proc = subprocess.run(
+ [shutil.which("bash") or "/bin/bash", _RUN_SH, "true"],
+ env = env,
+ capture_output = True,
+ text = True,
+ timeout = 120,
+ )
+ assert proc.returncode == 0, f"run.sh failed: {proc.stderr}"
+ return argv_log.read_text().splitlines(), proc.stderr
+
+
[email protected](shutil.which("bash") is None, reason = "bash required")
+class TestRunShDegradesWithoutNvidia:
+ def test_gpus_flag_is_dropped_when_the_host_has_no_nvidia_gpu(self, tmp_path):
+ """`--gpus all` on an NVIDIA-less host is exit 125 AT THE DAEMON, so the
+ container never starts and entrypoint.sh never gets to explain itself."""
+ argv, stderr = _invoke_run_sh(tmp_path, nvidia = False, amd = False)
+ assert "--gpus" not in argv, f"run.sh still passed --gpus: {argv}"
+ assert "no NVIDIA GPU on this host" in stderr
+
+ def test_amd_host_gets_the_render_nodes_with_numeric_gids(self, tmp_path):
+ """--group-add by NAME resolves inside the container, where the host's
+ video/render groups do not exist, so the gids must be numeric."""
+ argv, _ = _invoke_run_sh(tmp_path, nvidia = False, amd = True)
+ assert "--gpus" not in argv
+ assert "--device" in argv
+ assert "/dev/kfd" in argv and "/dev/dri" in argv
+ gids = [argv[i + 1] for i, a in enumerate(argv) if a == "--group-add"]
+ assert all(g.isdigit() for g in gids), f"non-numeric --group-add: {gids}"
+
+ def test_the_group_lookup_is_guarded_on_getent_existing(self):
+ """A host with no getent at all (busybox, some slim images) must skip the
+ lookup rather than fail it."""
+ body = open(_RUN_SH, encoding = "utf-8").read()
+ idx = body.index("getent group")
+ assert "command -v getent" in body[:idx]
+
+ @pytest.mark.parametrize("groups", ["none", "video_only"])
+ def test_a_missing_group_record_does_not_abort_the_run(self, tmp_path, groups):
+ """getent exits nonzero for a name that is not in NSS. Under `set -o pipefail`
+ that propagates out of the command substitution and `set -e` kills run.sh
+ before docker run, so the AMD fallback could never start on a host without a
+ render group. Degrade to whatever gids exist instead."""
+ argv, _ = _invoke_run_sh(tmp_path, nvidia = False, amd = True, groups = groups)
+ # the devices are the point; the gids are best-effort
+ assert "/dev/kfd" in argv and "/dev/dri" in argv
+ assert "--gpus" not in argv
+ gids = [argv[i + 1] for i, a in enumerate(argv) if a == "--group-add"]
+ assert all(g.isdigit() for g in gids), f"non-numeric --group-add: {gids}"
+ expected = {"none": 0, "video_only": 1}[groups]
+ assert len(gids) == expected, f"expected {expected} gids, got {gids}"
+
+ def test_an_nvidia_host_is_untouched(self, tmp_path):
+ """The degrade path must not fire where --gpus actually works."""
+ argv, _ = _invoke_run_sh(tmp_path, nvidia = True, amd = False)
+ assert "--gpus" in argv
+ assert "all" in argv
+ assert "/dev/kfd" not in argv
+
+
+class TestStudioImageAllowsCpu:
+ def test_studio_image_defaults_allow_cpu_on(self):
+ """:latest is the Studio image. Without this default every CPU-only, AMD
+ and Docker-Desktop user goes from working Studio to an exit 1."""
+ body = open(_STUDIO_DF, encoding = "utf-8").read()
+ env_lines = [
+ ln.strip()
+ for ln in body.splitlines()
+ if "UNSLOTH_ALLOW_CPU=1" in ln and not ln.strip().startswith("#")
+ ]
+ assert env_lines, "Dockerfile.studio does not default UNSLOTH_ALLOW_CPU=1"
+
+ 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()
+ offenders = [
+ ln.strip()
+ for ln in body.splitlines()
+ if "UNSLOTH_ALLOW_CPU=1" in ln and not ln.strip().startswith("#")
+ ]
+ assert not offenders, f"base image weakened the GPU check: {offenders}"
+
+ def test_entrypoint_reads_allow_cpu_from_the_environment(self):
+ """An image-level ENV and a `-e` flag reach the process identically, so the
+ entrypoint must read it from the environment with no `-e`-only handling."""
+ body = open(_ENTRYPOINT, encoding = "utf-8").read()
+ assert '"${UNSLOTH_ALLOW_CPU:-0}" == "1"' in body
+
+ def test_allow_cpu_only_applies_when_no_gpu_is_visible(self):
+ """The default must not weaken a GPU host: the CPU branch has to be gated
+ on nvidia-smi finding nothing, otherwise it would skip the torch checks."""
+ body = open(_ENTRYPOINT, encoding = "utf-8").read()
+ idx = body.index('"${UNSLOTH_ALLOW_CPU:-0}" == "1"')
+ branch = body[idx : idx + 400]
+ assert "nvidia-smi" in branch and "grep -q '^GPU'" in branch
diff --git a/tests/python/test_docker_labext_cell_nav.py b/tests/python/test_docker_labext_cell_nav.py
new file mode 100644
index 00000000000..80efbb1ded0
--- /dev/null
+++ b/tests/python/test_docker_labext_cell_nav.py
@@ -0,0 +1,56 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-Present the Unsloth team. See /studio/LICENSE.AGPL-3.0
+
+"""Colab-style arrow navigation must not swallow wrapped-line movement.
+
+`getCursorPosition().line` and `lineCount` are both LOGICAL, while JupyterLab wraps
+markdown and raw editors by default, so a one-line markdown header is
+line 0 == lineCount - 1 from every visual row and the wrapped rows are unreachable.
+
+CodeMirror's own answer is `EditorView.moveVertically(range, forward)`, which returns
+an unchanged head only at offset 0 / doc.length.
+
+A static source guard: the labextension is only built inside Dockerfile.studio.
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+import pytest
+
+REPO_ROOT = Path(__file__).resolve().parents[2]
+CELL_NAV = REPO_ROOT / "docker" / "jupyter" / "unsloth_labext" / "src" / "cellNav.ts"
+
+
[email protected](scope = "module")
+def source() -> str:
+ assert CELL_NAV.is_file(), f"missing {CELL_NAV}"
+ return CELL_NAV.read_text(encoding = "utf-8")
+
+
+def test_the_edit_mode_boundary_test_asks_codemirror_for_a_visual_line(source: str):
+ assert "moveVertically" in source, (
+ "the edit-mode boundary check must ask CodeMirror whether it can still "
+ "move one VISUAL line (EditorView.moveVertically); a logical lineCount "
+ "test makes the wrapped rows of a markdown cell unreachable"
+ )
+
+
+def test_the_visual_check_compares_screen_rows(source: str):
+ assert "coordsAtPos" in source, (
+ "moveVertically clamps to the document edge instead of returning the "
+ "same head, so the two positions have to be compared by visual row"
+ )
+
+
+def test_the_logical_line_test_is_only_a_fallback(source: str):
+ body = source[source.index("const editing = notebook.mode === 'edit'") :]
+ logical = re.search(r"editor\.lineCount - 1", body)
+ assert logical, "the non-CodeMirror fallback should still exist"
+ visual = re.search(r"moveVertically", body)
+ assert visual and visual.start() < logical.start(), (
+ "the visual-line test has to run first; the logical one is only for an "
+ "editor that is not a CodeMirrorEditor"
+ )
diff --git a/tests/python/test_docker_llama_cuda_backend.py b/tests/python/test_docker_llama_cuda_backend.py
new file mode 100644
index 00000000000..045f9b8ea79
--- /dev/null
+++ b/tests/python/test_docker_llama_cuda_backend.py
@@ -0,0 +1,100 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-Present the Unsloth team. See /studio/LICENSE.AGPL-3.0
+
+"""Regression guard for the llama.cpp CUDA backend inside the Docker image.
+
+The portable bundle dlopens libggml-cuda.so but carries none of the CUDA math
+libraries it links against, and with no libcublas on the loader path the backend
+fails to load SILENTLY: nothing printed, `--list-devices` empty, every GGUF request
+on the CPU. These pin the two Dockerfile halves that prevent it.
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+import pytest
+
+REPO_ROOT = Path(__file__).resolve().parents[2]
+DOCKERFILE = REPO_ROOT / "docker" / "Dockerfile"
+
+
[email protected](scope = "module")
+def dockerfile() -> str:
+ assert DOCKERFILE.is_file(), f"missing {DOCKERFILE}"
+ return DOCKERFILE.read_text(encoding = "utf-8")
+
+
+def test_cublas_dir_is_registered_with_the_loader(dockerfile: str):
+ conf = re.search(
+ r"ld\.so\.conf\.d/zz-unsloth-venv\.conf",
+ dockerfile,
+ )
+ assert conf, "the venv loader-config layer disappeared"
+ block = dockerfile[: conf.end()]
+ assert "$SP/nvidia/cublas/lib" in block, (
+ "libggml-cuda.so links against libcublas, which only exists in the venv's "
+ "wheel copy; without this entry the CUDA backend fails to dlopen and GGUF "
+ "silently runs on the CPU"
+ )
+
+
+def test_loader_config_is_not_ld_library_path(dockerfile: str):
+ # LD_LIBRARY_PATH is consulted BEFORE DT_RUNPATH and would let the venv's copies
+ # shadow llama.cpp's own $ORIGIN libs; ld.so.conf.d is consulted after
+ assert "ld.so.conf.d/zz-unsloth-venv.conf" in dockerfile
+ assert not re.search(
+ r"ENV\s+LD_LIBRARY_PATH=.*site-packages/nvidia",
+ dockerfile,
+ ), "the venv nvidia libs must not go on LD_LIBRARY_PATH"
+
+
+def test_build_fails_on_an_unresolved_cuda_backend(dockerfile: str):
+ assert "libggml-cuda.so" in dockerfile, "the CUDA backend guard disappeared"
+ guard = dockerfile[dockerfile.index("CUDA_SO=") :]
+ assert "ldd" in guard, "the guard must inspect the backend's dependencies"
+ assert "not found" in guard
+ assert "exit 1" in guard, "an unresolved backend must fail the build"
+ assert re.search(
+ r"grep -v .libcuda\\?\.so\\?\.1", guard
+ ), "libcuda.so.1 must be exempt from the guard or every build fails"
+
+
+def test_guard_installs_the_matching_cublas_major(dockerfile: str):
+ # the two arch bundles differ in CUDA major, so it must come from ldd
+ guard = dockerfile[dockerfile.index("CUDA_SO=") :]
+ assert (
+ "nvidia-cublas-cu${major}" in guard
+ ), "the guard must install the cublas major the bundle actually asks for"
+ assert "libcublas" in guard
+
+
+def test_guard_runs_after_the_prebuilt_is_fetched(dockerfile: str):
+ fetch = dockerfile.index("fetch_llama_prebuilt.py")
+ guard = dockerfile.index("CUDA_SO=")
+ assert fetch < guard, "the guard can only inspect a bundle that already exists"
+
+
+def test_flashinfer_jit_cache_tracks_flashinfer(dockerfile: str):
+ # flashinfer raises at import when jit-cache and python disagree, killing the vLLM
+ # EngineCore GRPO fast_inference runs on. A literal pin would drift.
+ assert (
+ "flashinfer-jit-cache==${FI_VER}" in dockerfile
+ ), "flashinfer-jit-cache must be pinned to the resolved flashinfer-python version"
+ assert not re.search(
+ r"flashinfer-jit-cache==[0-9]", dockerfile
+ ), "a literal flashinfer-jit-cache version will drift away from flashinfer-python"
+ assert "import flashinfer" in dockerfile, (
+ "the build must prove flashinfer imports, or a mismatch stays silent "
+ "until the first vLLM engine start"
+ )
+
+
+def test_cli_can_reach_the_studio_backend(dockerfile: str):
+ # unsloth_cli imports studio.backend.core.*, which needs structlog: a studio
+ # requirement, not an unsloth[huggingface] one, so the base venv must ask for it
+ assert '"structlog"' in dockerfile, "the base venv must install structlog for unsloth_cli"
+ assert (
+ "from studio.backend.core.export import ExportBackend" in dockerfile
+ ), "a build-time import guard must prove the CLI can reach the studio backend"
diff --git a/tests/python/test_docker_llama_prebuilt_probe.py b/tests/python/test_docker_llama_prebuilt_probe.py
new file mode 100644
index 00000000000..04f4f1576e4
--- /dev/null
+++ b/tests/python/test_docker_llama_prebuilt_probe.py
@@ -0,0 +1,102 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-Present the Unsloth team. See /studio/LICENSE.AGPL-3.0
+
+"""The llama-server sanity probe must not accept the loader's failure message.
+
+The probe asserts on the substring "version" in the binary's output, which is exactly
+the word the dynamic loader uses when it refuses to start one:
+
+ ./llama-server: /lib/x86_64-linux-gnu/libc.so.6: version `GLIBC_2.38' not
+ found (required by ./llama-server)
+
+The program never reaches main and exits nonzero, so the exit code is what separates
+the two cases. Driven end to end against the real probe with stub binaries on disk.
+"""
+
+from __future__ import annotations
+
+import importlib.util
+import os
+import shutil
+import stat
+from pathlib import Path
+
+import pytest
+
+REPO_ROOT = Path(__file__).resolve().parents[2]
+FETCH = REPO_ROOT / "docker" / "fetch_llama_prebuilt.py"
+
+GLIBC_FAILURE = (
+ "./llama-server: /lib/x86_64-linux-gnu/libc.so.6: version `GLIBC_2.38' "
+ "not found (required by ./llama-server)"
+)
+
+behavioural = pytest.mark.skipif(
+ shutil.which("bash") is None, reason = "needs bash for the stub binaries"
+)
+
+
+def fetch():
+ assert FETCH.is_file(), f"missing {FETCH}"
+ spec = importlib.util.spec_from_file_location("fetch_llama_under_test", FETCH)
+ mod = importlib.util.module_from_spec(spec)
+ spec.loader.exec_module(mod)
+ return mod
+
+
+def _stub(path: Path, output: str, rc: int) -> None:
+ # quoted heredoc: the message has a backtick an `echo` would run as a substitution
+ path.write_text(
+ "#!/usr/bin/env bash\n"
+ "cat >&2 <<'UNSLOTH_EOF'\n"
+ f"{output}\n"
+ "UNSLOTH_EOF\n"
+ f"exit {rc}\n",
+ encoding = "utf-8",
+ )
+ path.chmod(path.stat().st_mode | stat.S_IXUSR | stat.S_IXGRP | stat.S_IXOTH)
+
+
+def _stubs(install_dir: Path, *, server_output: str, server_rc: int) -> Path:
+ build_bin = install_dir / "build" / "bin"
+ build_bin.mkdir(parents = True, exist_ok = True)
+ _stub(install_dir / "llama-server", server_output, server_rc)
+ _stub(install_dir / "llama-quantize", "usage: llama-quantize [options]", 1)
+ _stub(build_bin / "llama-quantize", "usage: llama-quantize [options]", 1)
+ return build_bin
+
+
+@behavioural
+def test_a_loader_failure_is_not_accepted_as_a_version_banner(fetch, tmp_path):
+ build_bin = _stubs(tmp_path, server_output = GLIBC_FAILURE, server_rc = 1)
+ with pytest.raises(SystemExit) as exc:
+ fetch.sanity_check_binaries(str(tmp_path), str(build_bin))
+ assert "llama-server" in str(exc.value)
+ assert "exited 1" in str(exc.value)
+
+
+@behavioural
+def test_a_healthy_server_passes(fetch, tmp_path):
+ build_bin = _stubs(tmp_path, server_output = "version: 4589 (b9a9e6d)", server_rc = 0)
+ fetch.sanity_check_binaries(str(tmp_path), str(build_bin))
+
+
+@behavioural
+def test_the_quantize_probes_are_not_required_to_exit_zero(fetch, tmp_path):
+ build_bin = _stubs(tmp_path, server_output = "version: 4589 (b9a9e6d)", server_rc = 0)
+ _stub(tmp_path / "llama-quantize", "usage: llama-quantize [options]", 7)
+ fetch.sanity_check_binaries(str(tmp_path), str(build_bin))
+
+
+@behavioural
+def test_a_server_with_no_banner_at_all_still_fails(fetch, tmp_path):
+ build_bin = _stubs(tmp_path, server_output = "", server_rc = 0)
+ with pytest.raises(SystemExit) as exc:
+ fetch.sanity_check_binaries(str(tmp_path), str(build_bin))
+ assert "did not print 'version'" in str(exc.value)
+
+
+def test_the_loader_message_really_does_contain_the_substring():
+ # the premise: without it the exit-code check above is only belt and braces
+ assert "version" in GLIBC_FAILURE
diff --git a/tests/python/test_docker_nb_compat_pre_run_cell.py b/tests/python/test_docker_nb_compat_pre_run_cell.py
new file mode 100644
index 00000000000..afaa9e69644
--- /dev/null
+++ b/tests/python/test_docker_nb_compat_pre_run_cell.py
@@ -0,0 +1,329 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-Present the Unsloth team. See /studio/LICENSE.AGPL-3.0
+
+"""Regression tests for the IPython pre_run_cell hook in docker/unsloth_nb_compat.py.
+
+The hook only read the pip shim's marker file, which is a record of a PREVIOUS cell.
+The notebooks pin a new model by installing and importing in ONE cell, and the shim
+writes that marker from a child process partway through it, so the hook had already
+returned: the cell ran the base transformers and every later cell was answered with
+"already imported; cannot switch". The hook had no test coverage at all.
+"""
+
+from __future__ import annotations
+
+import importlib.util
+import os
+import sys
+from pathlib import Path
+from types import SimpleNamespace
+
+import pytest
+
+REPO_ROOT = Path(__file__).resolve().parents[2]
+COMPAT_PATH = REPO_ROOT / "docker" / "unsloth_nb_compat.py"
+RUN_PATH = REPO_ROOT / "docker" / "unsloth_run.py"
+
+PIN = "5.10.2"
+SIDECAR = "t_5_10_2"
+
+
+def sidecar_root(tmp_path):
+ root = tmp_path / "tf-sidecars"
+ for name in ("t_5_5_0", SIDECAR):
+ (root / name).mkdir(parents = True)
+ (root / ".vllm_min_transformers").write_text("5.5.0\n")
+ return root
+
+
+def compat(sidecar_root, tmp_path, monkeypatch):
+ """Fresh compat over fake sidecars, with sys.path and PYTHONPATH restored.
+
+ activate() mutates both, so without the teardown one test's sidecar leaks into the
+ next and a later assertion passes for the wrong reason.
+ """
+ monkeypatch.setenv("UNSLOTH_TF_SIDECAR_ROOT", str(sidecar_root))
+ monkeypatch.delenv("UNSLOTH_TF_SIDECAR_MIN", raising = False)
+ monkeypatch.setenv("UNSLOTH_NB_TF_MARKER", str(tmp_path / "marker" / "requested"))
+ monkeypatch.setenv("PYTHONPATH", "")
+ # activate() is a no-op once transformers is imported, and the session may well
+ # have imported it before this file runs, which made the first test in the file
+ # fail while the rest passed on the teardown of the one before it
+ monkeypatch.delitem(sys.modules, "transformers", raising = False)
+ path_before = list(sys.path)
+
+ spec = importlib.util.spec_from_file_location("unsloth_nb_compat_under_test", COMPAT_PATH)
+ mod = importlib.util.module_from_spec(spec)
+ spec.loader.exec_module(mod)
+ mod._sidecar_dir = str(sidecar_root / SIDECAR)
+ try:
+ yield mod
+ finally:
+ sys.path[:] = path_before
+
+
+def _fire(compat, source):
+ """Run the hook the way IPython does and report the activated directory."""
+ compat._pre_run_cell(SimpleNamespace(raw_cell = source))
+ return compat._sidecar_dir if compat._sidecar_dir in sys.path else None
+
+
+COMBINED_CELL = (
+ "# Muse Glimmer needs transformers 5.10.2. Run before anything imports it\n"
+ f'!pip install -q "transformers=={PIN}"\n'
+ "\n"
+ "import transformers\n"
+ 'print("transformers:", transformers.__version__)\n'
+)
+
+
+def test_a_combined_install_and_import_cell_gets_its_sidecar(compat):
+ assert _fire(compat, COMBINED_CELL) == compat._sidecar_dir
+
+
+def test_the_marker_only_hook_would_have_missed_it(compat):
+ """Non-vacuity. Reproduces the OLD hook body against the same cell: if this ever
+ activates, the test above proves nothing about the change."""
+ v = compat.requested_version()
+ assert v is None, "no previous cell has installed anything yet"
+ if v and "transformers" not in sys.modules:
+ compat.activate(v)
+ assert compat._sidecar_dir not in sys.path
+
+
+def test_the_marker_is_used_when_the_cell_pins_nothing_itself(compat, tmp_path):
+ marker = Path(os.environ["UNSLOTH_NB_TF_MARKER"])
+ marker.parent.mkdir(parents = True, exist_ok = True)
+ marker.write_text(PIN, encoding = "utf-8")
+ # a cell with no install at all, i.e. the shape the hook always handled
+ assert _fire(compat, "import transformers\n") == compat._sidecar_dir
+
+
+def test_the_cell_pin_outranks_a_stale_marker(compat, sidecar_root, tmp_path):
+ """The marker records an install that has ALREADY run. An earlier cell in the same
+ notebook can have pinned something else, and the marker path falls back to
+ pid-<pid> when the connection file cannot be read, so a recycled pid inherits a
+ stranger's pin. The cell about to run is the better authority either way."""
+ marker = Path(os.environ["UNSLOTH_NB_TF_MARKER"])
+ marker.parent.mkdir(parents = True, exist_ok = True)
+ marker.write_text("5.5.0", encoding = "utf-8")
+ other = str(sidecar_root / "t_5_5_0")
+
+ compat._pre_run_cell(SimpleNamespace(raw_cell = COMBINED_CELL))
+
+ assert compat._sidecar_dir in sys.path, "the cell's own pin was not honoured"
+ assert other not in sys.path, "the stale marker won over the cell about to run"
+
+
+ "cell",
+ [
+ pytest.param(f'# !pip install "transformers=={PIN}"\n', id = "commented-out"),
+ pytest.param(f'"""\n!pip install transformers=={PIN}\n"""\n', id = "docstring"),
+ pytest.param(f'note = "pip install transformers=={PIN}"\n', id = "string-literal"),
+ pytest.param(f'print("upgrade from transformers=={PIN} if it breaks")\n', id = "mention"),
+ pytest.param(f"REQUIRED = 'transformers=={PIN}'\n", id = "assigned-unused"),
+ pytest.param("import transformers\n", id = "no-pin-at-all"),
+ ],
+)
+def test_a_cell_that_installs_nothing_activates_nothing(compat, cell):
+ """A wrong sidecar is unrecoverable once transformers is imported, while no sidecar
+ only means the base venv, so anything ambiguous has to lose."""
+ assert _fire(compat, cell) is None
+
+
+ "cell",
+ [
+ pytest.param(f'!pip install "transformers=={PIN}"\n', id = "bang-pip"),
+ pytest.param(f"%pip install transformers=={PIN}\n", id = "pip-magic"),
+ pytest.param(f"!uv pip install -q transformers=={PIN}\n", id = "uv"),
+ pytest.param(f"!python -m pip install transformers=={PIN}\n", id = "python-m-pip"),
+ pytest.param(f"!pip install \\\n transformers=={PIN}\n", id = "continuation"),
+ pytest.param(f" !pip install transformers=={PIN}\n", id = "indented"),
+ ],
+)
+def test_every_real_install_shape_activates(compat, cell):
+ assert _fire(compat, cell) == compat._sidecar_dir
+
+
+def test_nothing_happens_once_transformers_is_imported(compat, capsys, monkeypatch):
+ monkeypatch.setitem(sys.modules, "transformers", SimpleNamespace(__version__ = "4.57.6"))
+ compat._pre_run_cell(SimpleNamespace(raw_cell = COMBINED_CELL))
+ assert compat._sidecar_dir not in sys.path
+ # the hook fires on EVERY cell, so it must not narrate on each one
+ assert capsys.readouterr().err == ""
+
+
+def test_a_hook_call_with_no_info_is_harmless(compat):
+ """IPython has passed the event object for a long time, but the parameter was
+ optional here before and a bare call must not raise."""
+ compat._pre_run_cell()
+ compat._pre_run_cell(SimpleNamespace())
+
+
+def test_pythonpath_does_not_accumulate_a_copy_per_cell(compat):
+ for _ in range(3):
+ compat.activate(PIN)
+ entries = os.environ["PYTHONPATH"].split(os.pathsep)
+ assert entries.count(compat._sidecar_dir) == 1, os.environ["PYTHONPATH"]
+
+
+def test_the_hook_is_registered_under_pre_run_cell(compat):
+ class _Events:
+ def __init__(self):
+ self.registered = []
+
+ def register(self, name, fn):
+ self.registered.append((name, fn))
+
+ class _Shell:
+ def __init__(self):
+ self.events = _Events()
+
+ shell = _Shell()
+ compat.get_ipython = lambda: shell
+ compat.register_ipython()
+ compat.register_ipython() # idempotent
+ assert shell.events.registered == [("pre_run_cell", compat._pre_run_cell)]
+
+
+def test_ipython_really_hands_the_hook_the_cell_source():
+ """Premise pin: the fix reads info.raw_cell, so IPython has to supply it."""
+ ipython = pytest.importorskip("IPython.core.interactiveshell")
+ seen = []
+ shell = ipython.InteractiveShell.instance()
+ try:
+ shell.events.register("pre_run_cell", lambda info: seen.append(info))
+ shell.run_cell("x = 1\n")
+ finally:
+ ipython.InteractiveShell.clear_instance()
+ assert seen, "pre_run_cell did not fire"
+ assert getattr(seen[0], "raw_cell", None) == "x = 1\n"
+
+
+def test_unsloth_run_scans_with_the_very_same_functions(compat, monkeypatch):
+ """One scanner, not two. unsloth_run used to own these, and a copy in each module
+ would let the headless kernel and the in-notebook hook pick different sidecars."""
+ monkeypatch.setitem(sys.modules, "unsloth_nb_compat", compat)
+ spec = importlib.util.spec_from_file_location("unsloth_run_same_scanner", RUN_PATH)
+ run = importlib.util.module_from_spec(spec)
+ spec.loader.exec_module(run)
+ assert run.compat is compat
+ for name in ("_PIN_RE", "_INSTALL_RE", "_strip_comment", "_live_source", "_install_lines"):
+ assert getattr(run, name) is getattr(compat, name), name
+ assert run._pin_from is compat.pin_from
+
+
+# pip accepts every PEP 503 spelling of a requirement name, and unsloth_pip_shim
+# canonicalises before it decides what to drop. A scanner that only knew the canonical
+# form therefore left the pin unseen while the install was still suppressed, and the
+# import in that same cell froze the base transformers for the life of the kernel.
+
+
+ "spec",
+ [
+ "transformers==" + PIN,
+ "Transformers==" + PIN,
+ "TRANSFORMERS==" + PIN,
+ "transformers[torch]==" + PIN,
+ "transformers [torch] == " + PIN,
+ " transformers == " + PIN,
+ ],
+)
+def test_every_spelling_the_shim_drops_is_a_pin(compat, spec):
+ assert compat.pin_in_cell("%pip install " + spec + "\nimport transformers\n") == PIN
+ assert _fire(compat, "%pip install " + spec + "\nimport transformers\n") is not None
+
+
+def test_the_shim_and_the_scanner_agree_on_the_name(compat):
+ """The two halves this item found apart. Read the shim's own canonicaliser rather
+ than restating its rule here, so a change on that side fails this instead of
+ drifting silently."""
+ shim_path = REPO_ROOT / "docker" / "unsloth_pip_shim.py"
+ spec = importlib.util.spec_from_file_location("unsloth_pip_shim_names", shim_path)
+ shim = importlib.util.module_from_spec(spec)
+ spec.loader.exec_module(shim)
+ for spelling in ("transformers", "Transformers", "TRANSFORMERS", "transformers[torch]"):
+ assert shim._canon(spelling + "==" + PIN) == "transformers", spelling
+ assert compat.pin_in_cell("!pip install " + spelling + "==" + PIN) == PIN, spelling
+ # and where the shim says a spelling is somebody else, so does the scanner: PEP 503
+ # collapses a run of `-_.` to one `-`, it does not delete it
+ for other in ("trans_formers", "trans.formers", "sentence-transformers"):
+ assert shim._canon(other + "==" + PIN) != "transformers", other
+ assert compat._norm_req(other) == shim._canon(other + "==" + PIN), other
+ assert compat.pin_in_cell("!pip install " + other + "==" + PIN) is None, other
+
+
+ "spec",
+ [
+ "transformers-stream-generator==" + PIN,
+ "sentence-transformers==" + PIN,
+ "trans-formers==" + PIN,
+ ],
+)
+def test_a_different_distribution_is_not_the_pin(compat, spec):
+ """Non-vacuity and the blast radius: matching the name loosely must not start
+ reading somebody else's version as the transformers pin."""
+ assert compat.pin_in_cell("%pip install " + spec) is None
+
+
+def test_a_pin_still_has_to_come_from_an_install_line(compat):
+ assert compat.pin_in_cell("# %pip install Transformers==" + PIN) is None
+ assert compat.pin_in_cell('doc = """\n%pip install Transformers==' + PIN + '\n"""\n') is None
+
+
+# A requirement whose PEP 508 marker is false is skipped outright by both real tools
+# ("Ignoring transformers: markers ... don't match your environment"), so it installs
+# nothing. Treating it as a pin activated a sidecar for a version the cell never got,
+# and activate() prepends that directory to sys.path AND to PYTHONPATH, so every child
+# process inherits it too.
+ "cell, expected",
+ [
+ ("!pip install transformers==5.5.0", "5.5.0"),
+ ("!pip install \"transformers==5.5.0; python_version < '3.0'\"", None),
+ ("!pip install \"transformers==5.5.0; sys_platform == 'win32'\"", None),
+ ("!pip install \"transformers==5.5.0; python_version >= '3.0'\"", "5.5.0"),
+ ("!pip install \"transformers==5.5.0; platform_system == 'Linux'\"", "5.5.0"),
+ ("!uv pip install \"transformers==5.5.0; implementation_name == 'pypy'\"", None),
+ # unquoted: the shell cuts the line at the `;`, so pip only ever sees the
+ # bare pin and it really is unconditional
+ ('!pip install transformers==5.5.0; python_version < "3.0"', "5.5.0"),
+ ],
+ ids = [
+ "no-marker",
+ "false-python",
+ "false-platform",
+ "true-python",
+ "true-system",
+ "false-implementation",
+ "unquoted-shell-splits",
+ ],
+)
+def test_a_false_environment_marker_is_not_a_pin(compat, cell, expected):
+ assert compat.pin_in_cell(cell) == expected
+
+
+def test_the_marker_veto_survives_without_packaging(compat, monkeypatch):
+ """packaging is optional in this module, as it already is for version ordering, so
+ losing it must fall back to the old behaviour rather than raise."""
+ import builtins
+
+ real_import = builtins.__import__
+
+ def _no_packaging(name, *a, **kw):
+ if name.startswith("packaging"):
+ raise ImportError("no packaging")
+ return real_import(name, *a, **kw)
+
+ monkeypatch.setattr(builtins, "__import__", _no_packaging)
+ assert compat.pin_in_cell("!pip install transformers==5.5.0") == "5.5.0"
+ assert (
+ compat.pin_in_cell("!pip install \"transformers==5.5.0; python_version < '3.0'\"")
+ == "5.5.0"
+ )
diff --git a/tests/python/test_docker_nb_install_cell_sig.py b/tests/python/test_docker_nb_install_cell_sig.py
new file mode 100644
index 00000000000..a308d4cb256
--- /dev/null
+++ b/tests/python/test_docker_nb_install_cell_sig.py
@@ -0,0 +1,376 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved.
+
+"""An upstream install-cell fix has to reach the container.
+
+`middle_digest` counted the whole generated install cell as boilerplate. Only half
+true: its comments and spacing churn every upstream build, but the package specs do
+not, and a pin bump lives entirely in that cell. SAME does not merely skip the copy,
+it re-records the OLD hash, so such a notebook never converges.
+"""
+
+from __future__ import annotations
+
+import importlib.util
+import json
+from pathlib import Path
+
+import pytest
+
+REPO_ROOT = Path(__file__).resolve().parents[2]
+SIG_PATH = REPO_ROOT / "docker" / "unsloth_nb_content_sig.py"
+
+_INSTALL = "!pip install --upgrade unsloth transformers==4.56.2\n"
+
+
[email protected](scope = "module")
+def sig():
+ assert SIG_PATH.is_file(), f"missing {SIG_PATH}"
+ spec = importlib.util.spec_from_file_location("unsloth_nb_content_sig_t", SIG_PATH)
+ mod = importlib.util.module_from_spec(spec)
+ spec.loader.exec_module(mod)
+ return mod
+
+
+def _write(path: Path, *sources) -> Path:
+ cells = []
+ for cell_type, text in sources:
+ cells.append({"cell_type": cell_type, "source": [text], "metadata": {}})
+ path.write_text(
+ json.dumps({"cells": cells, "metadata": {}, "nbformat": 4, "nbformat_minor": 5}),
+ encoding = "utf-8",
+ )
+ return path
+
+
+def _same(sig, tmp_path: Path, before, after) -> bool:
+ a = _write(tmp_path / "a.ipynb", *before)
+ b = _write(tmp_path / "b.ipynb", *after)
+ return sig.middle_digest(str(a)) == sig.middle_digest(str(b))
+
+
+def test_a_pin_bump_in_the_install_cell_is_visible(sig, tmp_path: Path):
+ assert not _same(
+ sig,
+ tmp_path,
+ [("code", _INSTALL), ("code", "print(1)\n")],
+ [("code", _INSTALL.replace("4.56.2", "5.5.0")), ("code", "print(1)\n")],
+ ), "a changed version pin must make the notebook refresh"
+
+
+def test_an_added_dependency_is_visible(sig, tmp_path: Path):
+ assert not _same(
+ sig,
+ tmp_path,
+ [("code", _INSTALL), ("code", "print(1)\n")],
+ [("code", _INSTALL.rstrip("\n") + " trl\n"), ("code", "print(1)\n")],
+ ), "an added package must make the notebook refresh"
+
+
+def test_a_removed_install_cell_is_visible(sig, tmp_path: Path):
+ assert not _same(
+ sig,
+ tmp_path,
+ [("code", _INSTALL), ("code", "!pip install extras\n"), ("code", "print(1)\n")],
+ [("code", _INSTALL), ("code", "print(1)\n")],
+ ), "dropping an install cell must make the notebook refresh"
+
+
+def test_cosmetic_install_churn_is_still_the_same(sig, tmp_path: Path):
+ # why the cell was skipped at all: upstream regenerates it every build
+ churned = (
+ "# regenerated by update_all_notebooks.py\n"
+ "\n"
+ "!pip install --upgrade unsloth transformers==4.56.2\n"
+ " # keep the pin in step with the sidecar\n"
+ )
+ assert _same(
+ sig,
+ tmp_path,
+ [("code", _INSTALL), ("code", "print(1)\n")],
+ [("code", churned), ("code", "print(1)\n")],
+ ), "comment/whitespace churn in the install cell must not force a refresh"
+
+
+def test_a_url_fragment_is_not_mistaken_for_a_comment(sig, tmp_path: Path):
+ # `#subdirectory=` selects the package, so stripping it hashes two installs alike
+ a = '!pip install "git+https://github.com/o/r#subdirectory=pkg_a"\n'
+ b = '!pip install "git+https://github.com/o/r#subdirectory=pkg_b"\n'
+ assert not _same(
+ sig, tmp_path, [("code", a), ("code", "print(1)\n")], [("code", b), ("code", "print(1)\n")]
+ ), "a #fragment inside a requirement is data, not a comment"
+
+
+def test_boilerplate_markdown_is_still_ignored(sig, tmp_path: Path):
+ assert _same(
+ sig,
+ tmp_path,
+ [("markdown", "To run this, press Runtime\n"), ("code", "print(1)\n")],
+ [("markdown", "To run this, press Runtime and Run all\n"), ("code", "print(1)\n")],
+ ), "the announcement block must still be excluded"
+
+
+def test_a_body_change_is_still_visible(sig, tmp_path: Path):
+ assert not _same(
+ sig,
+ tmp_path,
+ [("code", _INSTALL), ("code", "print(1)\n")],
+ [("code", _INSTALL), ("code", "print(2)\n")],
+ ), "a real code change must still make the notebook refresh"
+
+
+# `" ".join(line.split())` drops the LEADING whitespace too, but upstream's cell is an
+# `if "COLAB_" not in ...: / else:` block and the image is always the non-Colab branch,
+# so moving a line out of the `else:` body is functional, not churn.
+
+_UPSTREAM_HEAD = (
+ "%%capture\n"
+ "import os, re\n"
+ 'if "COLAB_" not in "".join(os.environ.keys()):\n'
+ " !pip install unsloth\n"
+ "else:\n"
+ ' !pip install sentencepiece protobuf "datasets==4.3.0" hf_transfer\n'
+ " !pip install --no-deps unsloth_zoo bitsandbytes accelerate peft trl triton unsloth\n"
+)
+
+
+def test_moving_an_install_line_out_of_the_colab_branch_is_visible(sig, tmp_path: Path):
+ # same lines, same order, one dedent: Colab-only becomes every runtime
+ inside = _UPSTREAM_HEAD + ' !pip install --no-deps --upgrade "torchao>=0.16.0"\n'
+ outside = _UPSTREAM_HEAD + '!pip install --no-deps --upgrade "torchao>=0.16.0"\n'
+ assert not _same(
+ sig,
+ tmp_path,
+ [("code", inside), ("code", "print(1)\n")],
+ [("code", outside), ("code", "print(1)\n")],
+ ), "dedenting an install line out of the Colab-only branch must force a refresh"
+
+
+def test_indenting_an_install_line_into_the_colab_branch_is_visible(sig, tmp_path: Path):
+ outside = _UPSTREAM_HEAD + '!pip install --no-deps --upgrade "torchao>=0.16.0"\n'
+ inside = _UPSTREAM_HEAD + ' !pip install --no-deps --upgrade "torchao>=0.16.0"\n'
+ assert not _same(
+ sig,
+ tmp_path,
+ [("code", outside), ("code", "print(1)\n")],
+ [("code", inside), ("code", "print(1)\n")],
+ ), "indenting an install line into the Colab-only branch must force a refresh"
+
+
+def test_indentation_churn_inside_the_cell_is_still_cosmetic(sig, tmp_path: Path):
+ churned = (
+ "%%capture\n"
+ "# regenerated by update_all_notebooks.py\n"
+ "import os, re\n"
+ "\n"
+ 'if "COLAB_" not in "".join(os.environ.keys()):\n'
+ "\t!pip install unsloth\n"
+ " # keep the pin in step with the sidecar\n"
+ "else:\n"
+ '\t!pip install sentencepiece protobuf "datasets==4.3.0" hf_transfer\n'
+ "\t!pip install --no-deps unsloth_zoo bitsandbytes accelerate peft trl triton unsloth\n"
+ )
+ assert _same(
+ sig,
+ tmp_path,
+ [("code", _UPSTREAM_HEAD), ("code", "print(1)\n")],
+ [("code", churned), ("code", "print(1)\n")],
+ ), "comment/blank/inner-spacing/tab churn at the same depth must stay SAME"
+
+
+# Classification was a substring search over the WHOLE cell text, and normalization
+# then flattened the whole cell. Four shipped notebooks (the NeMo-Gym family) route a
+# 200-line executable Python cell through it because a prose comment says
+# `uv pip install`, and the flattening was already collapsing YAML indentation inside
+# a string literal there.
+
+_NEMO_STYLE = (
+ "# Inside the .venv guard this cell used to carry, `uv pip install` was run here.\n"
+ "import subprocess\n"
+ "with open(cfg, 'w') as _f:\n"
+ " _f.write(\n"
+ ' "instruction_following:\\n"\n'
+ ' " resources_servers:\\n"\n'
+ ' " entrypoint: app.py\\n"\n'
+ " )\n"
+)
+
+
+def test_a_comment_mentioning_an_install_does_not_make_it_an_install_cell(sig):
+ cell = {"cell_type": "code", "source": [_NEMO_STYLE]}
+ assert not sig._is_install_code(
+ cell
+ ), "a 200-line Python cell was flattened because a comment named uv pip install"
+
+
+def test_yaml_nesting_inside_a_string_literal_is_not_cosmetic(sig, tmp_path: Path):
+ renested = _NEMO_STYLE.replace('" entrypoint', '" entrypoint')
+ assert renested != _NEMO_STYLE
+ assert not _same(
+ sig,
+ tmp_path,
+ [("code", _NEMO_STYLE), ("code", "print(1)\n")],
+ [("code", renested), ("code", "print(1)\n")],
+ ), "re-nesting a generated YAML key changes what the notebook writes"
+
+
+def test_a_string_literal_beside_a_real_install_is_still_compared(sig, tmp_path: Path):
+ """The reviewer's case: the cell really does install, so it is an install cell,
+ but the code around the install must not be flattened with it."""
+ before = _INSTALL + 'script = "echo # pip install foo"\n'
+ after = _INSTALL + 'script = "echo # pip install bar"\n'
+ assert not _same(
+ sig,
+ tmp_path,
+ [("code", before), ("code", "print(1)\n")],
+ [("code", after), ("code", "print(1)\n")],
+ ), "a `#` inside a string is data, not a comment"
+
+
+# the install LINE itself may carry a string literal once it chains code after the
+# install, and cutting at the quoted `#` dropped the rest of the line with it
+_COMPOUND = "!pip install foo && python -c 'print(\"a # b\")' && pip install bar==2.0\n"
+
+
+def test_a_quoted_hash_on_a_compound_install_line_is_data(sig, tmp_path: Path):
+ assert sig._is_install_line(_COMPOUND.strip(), False)
+ assert not _same(
+ sig,
+ tmp_path,
+ [("code", _COMPOUND), ("code", "print(1)\n")],
+ [("code", _COMPOUND.replace("# b", "# c")), ("code", "print(1)\n")],
+ ), "a `#` inside a quoted stretch of an install line is data, not a comment"
+
+
+def test_a_pin_after_a_quoted_hash_is_still_visible(sig, tmp_path: Path):
+ """The cost of cutting at the quoted `#`: every spec behind it vanished too."""
+ assert not _same(
+ sig,
+ tmp_path,
+ [("code", _COMPOUND), ("code", "print(1)\n")],
+ [("code", _COMPOUND.replace("bar==2.0", "bar==3.0")), ("code", "print(1)\n")],
+ ), "a changed pin behind a quoted `#` must still make the notebook refresh"
+
+
+def test_a_real_trailing_comment_on_an_install_line_is_still_cosmetic(sig, tmp_path: Path):
+ assert _same(
+ sig,
+ tmp_path,
+ [("code", _INSTALL.rstrip("\n") + " # install the stack\n"), ("code", "print(1)\n")],
+ [("code", _INSTALL.rstrip("\n") + " # bring in the stack\n"), ("code", "print(1)\n")],
+ ), "an unquoted trailing comment must stay cosmetic"
+
+
+def test_whitespace_inside_a_string_is_data_too(sig, tmp_path: Path):
+ assert not _same(
+ sig,
+ tmp_path,
+ [("code", _INSTALL + 'cfg = "a b"\n'), ("code", "print(1)\n")],
+ [("code", _INSTALL + 'cfg = "a b"\n'), ("code", "print(1)\n")],
+ )
+
+
+def test_a_shell_cell_needs_no_bang_prefix(sig, tmp_path: Path):
+ """`%%bash` makes the cell shell, so the marker needs no `!` prefix there."""
+ cell = {"cell_type": "code", "source": ["%%bash\npip install unsloth\n"]}
+ assert sig._is_install_code(cell)
+ churned = "%%bash\npip install unsloth\n# comment\n"
+ assert _same(
+ sig,
+ tmp_path,
+ [("code", "%%bash\npip install unsloth\n"), ("code", "print(1)\n")],
+ [("code", churned), ("code", "print(1)\n")],
+ )
+
+
+ "line",
+ [
+ "!pip install unsloth\n",
+ " !pip install unsloth\n",
+ "%pip install unsloth\n",
+ "%uv pip install unsloth\n",
+ "!uv pip install unsloth\n",
+ "!apt-get install -y ffmpeg\n",
+ ],
+)
+def test_every_real_invocation_still_counts_as_an_install_cell(sig, line):
+ assert sig._is_install_code({"cell_type": "code", "source": [line]}), line
+
+
+ "line",
+ [
+ "# pip install unsloth\n",
+ 'note = "pip install unsloth"\n',
+ "print('run pip install unsloth first')\n",
+ "subprocess.run(['bash', '-c', 'uv pip install foo'])\n",
+ ],
+)
+def test_a_mention_is_not_an_invocation(sig, line):
+ assert not sig._is_install_code({"cell_type": "code", "source": [line]}), line
+
+
+def test_pip3_is_deliberately_absent_from_the_markers(sig):
+ """`!pip3 install` matches no marker, and that predates this change. It is the safe
+ direction: an unrecognised install cell is compared byte for byte, so upstream
+ comment churn costs one extra refresh instead of hiding a spec change. Adding
+ "pip3 install" here would start eliding those cells, so it needs its own decision
+ rather than being tidied in."""
+ assert not any("pip3 install" == m for m in sig._INSTALL_MARKERS)
+ assert not sig._is_install_code({"cell_type": "code", "source": ["!pip3 install x\n"]})
+
+
+# `%%bash` used to qualify EVERY line of the cell, which is the same mistake as the
+# whole-cell substring search one level down: the marker only had to appear somewhere
+# on the line. `_normalize_install` then stripped the quoted `# ...` and collapsed the
+# spacing, both of which are data in shell, so an upstream edit to that string produced
+# SAME and the container kept running the old commands.
+
+_SHELL_MENTION = '%%bash\nmsg="pip install foo # bar"\necho "$msg"\n'
+
+
+def test_a_quoted_mention_in_a_shell_cell_is_not_a_command(sig, tmp_path: Path):
+ assert not sig._is_install_line('msg="pip install foo # bar"', True)
+ assert not _same(
+ sig,
+ tmp_path,
+ [("code", _SHELL_MENTION), ("code", "print(1)\n")],
+ [("code", _SHELL_MENTION.replace("# bar", "# baz")), ("code", "print(1)\n")],
+ ), "editing a quoted shell string changes what the cell runs"
+
+
+def test_an_operand_in_a_shell_cell_is_not_a_command(sig):
+ assert not sig._is_install_line("echo pip install foo", True)
+ assert not sig._is_install_line("grep -c 'x' pip install.log", True)
+
+
+ "line",
+ [
+ "pip install unsloth",
+ " pip install unsloth",
+ "sudo apt-get install -y ffmpeg",
+ "uv pip install unsloth",
+ "cd /tmp && pip install unsloth",
+ "mkdir -p x; pip install unsloth",
+ "PIP_NO_CACHE_DIR=1 pip install unsloth",
+ "python3 -m pip install unsloth",
+ "!pip install unsloth",
+ 'pip install "unsloth[all]"',
+ ],
+)
+def test_a_real_shell_invocation_still_counts(sig, line):
+ assert sig._is_install_line(line, True), line
+
+
+def test_the_whole_shipped_corpus_is_unaffected(sig):
+ """Blast radius, measured rather than asserted: all 1064 marker lines inside the
+ 152 `%%bash` cells of the 561 shipped notebooks open a command, so the narrowing
+ changes no digest today. It only removes the tail this item found."""
+ for line in (
+ "pip install -q unsloth",
+ "apt install -y git",
+ "conda install -c conda-forge x",
+ ):
+ assert sig._is_install_line(line, True), line
diff --git a/tests/python/test_docker_nb_ipython_profile_writable.py b/tests/python/test_docker_nb_ipython_profile_writable.py
new file mode 100644
index 00000000000..e780339e22e
--- /dev/null
+++ b/tests/python/test_docker_nb_ipython_profile_writable.py
@@ -0,0 +1,167 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved.
+
+"""The baked IPython profile must stay writable under `docker run --user <uid>`.
+
+`ENV IPYTHONDIR=/opt/unsloth-nb/ipython` is what makes the notebook startup hook
+load for EVERY kernel regardless of uid. But IPython does not fail loudly on a
+profile it cannot write: `IPython.paths.get_ipython_dir()` checks the directory
+with `os.access(..., W_OK)` and, when it is not writable, warns once on stderr and
+substitutes `tempfile.mkdtemp()`. A fresh temp directory has no `profile_default/
+startup/`, so the hook never runs -- no transformers sidecar activation, no
+`%pip` / `%uv` magic, no colab-compat -- and the notebook still executes, wrongly,
+with nothing in the output to say so.
+
+Making only the TOP directory writable is worse: `ProfileDir.check_dirs()` then
+creates `security/`, `log/`, `pid/` inside `profile_default` and raises
+PermissionError, which kills the kernel before it replies to kernel_info.
+
+So this replays the Dockerfile's own profile-setup commands into a temp tree,
+re-maps each path's OTHER bits onto its owner bits (which is exactly what a
+foreign uid sees), and then asks the installed IPython what it would really do.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+import shutil
+import stat
+import subprocess
+import sys
+import textwrap
+from pathlib import Path
+
+import pytest
+
+REPO_ROOT = Path(__file__).resolve().parents[2]
+DOCKER_DIR = REPO_ROOT / "docker"
+DOCKERFILE = DOCKER_DIR / "Dockerfile"
+
+_IPY_DIR = "/opt/unsloth-nb/ipython"
+
+
+def _profile_setup_commands() -> list[str]:
+ """The `mkdir` / `cp` / `chmod` steps of the RUN layer that builds the profile."""
+ text = DOCKERFILE.read_text(encoding = "utf-8")
+ # the layer is a single `RUN set -eux \` ... continuation block
+ start = text.index("COPY unsloth_nb_compat.py")
+ block = text[start : text.index("\nENV PATH=", start)]
+ joined = block.replace("\\\n", "\n")
+ cmds = []
+ for raw in joined.split("\n"):
+ line = raw.strip()
+ line = re.sub(r"^&&\s*", "", line)
+ if not line or _IPY_DIR not in line:
+ continue
+ if line.split(" ", 1)[0] not in ("mkdir", "cp", "chmod"):
+ continue
+ cmds.append(line)
+ return cmds
+
+
+def _as_foreign_uid(root: Path) -> None:
+ """Give every path the permissions a DIFFERENT uid would get.
+
+ The image builds this tree as root with a 022 umask, so a container started
+ with `--user <uid>` sees only the `other` bits. The test process owns the tree,
+ and `os.access` answers on the OWNER bits, so copy other->owner to make the
+ question the same one.
+ """
+ # deepest first: dropping a directory's owner bits would hide its children
+ paths = sorted([root, *root.rglob("*")], key = lambda p: len(p.parts), reverse = True)
+ for path in paths:
+ mode = stat.S_IMODE(path.stat().st_mode)
+ other = mode & 0o007
+ path.chmod((mode & ~0o700) | (other << 6))
+
+
+_PROBE = textwrap.dedent(
+ """
+ import json, os, sys
+ from IPython.paths import get_ipython_dir
+ from IPython.core.profiledir import ProfileDir
+
+ out = {"ipdir": get_ipython_dir(), "error": None, "startup": []}
+ try:
+ pd = ProfileDir.find_profile_dir_by_name(out["ipdir"], "default")
+ pd.check_dirs()
+ out["startup"] = sorted(os.listdir(pd.startup_dir))
+ except Exception as exc:
+ out["error"] = f"{type(exc).__name__}: {exc}"
+ print("PROBE" + json.dumps(out))
+ """
+)
+
+
[email protected](scope = "module")
+def staged_profile(tmp_path_factory):
+ pytest.importorskip("IPython")
+ root = tmp_path_factory.mktemp("unsloth-nb")
+ shutil.copy(DOCKER_DIR / "unsloth_ipython_startup.py", root / "unsloth_ipython_startup.py")
+ cmds = _profile_setup_commands()
+ assert cmds, "no profile setup commands found in the Dockerfile"
+ assert any(c.startswith("cp ") for c in cmds), "the startup hook is no longer copied in"
+ script = "set -eu\n" + "\n".join(c.replace("/opt/unsloth-nb", str(root)) for c in cmds)
+ subprocess.run(["bash", "-c", script], check = True)
+ _as_foreign_uid(root / "ipython")
+ yield root / "ipython"
+ # hand the owner bits back, or pytest cannot remove its own tmp tree
+ for path in sorted(root.rglob("*"), key = lambda p: len(p.parts), reverse = True):
+ try:
+ path.chmod(stat.S_IMODE(path.stat().st_mode) | 0o700)
+ except OSError:
+ pass
+
+
+def _probe(ipython_dir: Path) -> dict:
+ env = dict(os.environ)
+ env["IPYTHONDIR"] = str(ipython_dir)
+ env.pop("PYTHONWARNINGS", None)
+ proc = subprocess.run(
+ [sys.executable, "-c", _PROBE],
+ env = env,
+ capture_output = True,
+ text = True,
+ timeout = 300,
+ )
+ line = [l for l in proc.stdout.splitlines() if l.startswith("PROBE")]
+ assert line, f"probe produced no result:\n{proc.stdout}\n{proc.stderr}"
+ import json
+
+ return json.loads(line[0][len("PROBE") :])
+
+
+def test_ipython_keeps_the_baked_profile_for_a_non_root_uid(staged_profile: Path):
+ got = _probe(staged_profile)
+ assert got["ipdir"] == str(staged_profile), (
+ "IPython discarded IPYTHONDIR and fell back to "
+ f"{got['ipdir']}: the profile is not writable by a non-root uid, so the "
+ "startup hook silently does not load under `docker run --user <uid>`"
+ )
+ assert got["error"] is None, (
+ f"IPython could not use the baked profile: {got['error']}. The kernel dies "
+ "here; ProfileDir creates security/, log/ and pid/ inside profile_default"
+ )
+ assert (
+ "00-unsloth-nb.py" in got["startup"]
+ ), f"the startup hook is not in the profile IPython uses: {got['startup']}"
+
+
+def test_the_shared_startup_hook_stays_read_only(staged_profile: Path):
+ hook = staged_profile / "profile_default" / "startup" / "00-unsloth-nb.py"
+ assert hook.is_file()
+ for path in (hook, hook.parent):
+ mode = stat.S_IMODE(path.stat().st_mode)
+ assert not mode & 0o022, (
+ f"{path} is writable by other uids; the shared hook runs in every kernel "
+ "and must not be replaceable from a notebook"
+ )
+ # profile_default has to be world-writable for the test above to pass; without
+ # the sticky bit that also lets any uid rename startup/ out of the way
+ parent = stat.S_IMODE((staged_profile / "profile_default").stat().st_mode)
+ if parent & 0o002:
+ assert parent & stat.S_ISVTX, (
+ "profile_default is world-writable without the sticky bit, so any uid "
+ "can unlink or rename the read-only startup hook"
+ )
diff --git a/tests/python/test_docker_nb_populate_retry.py b/tests/python/test_docker_nb_populate_retry.py
new file mode 100644
index 00000000000..b88b372f05c
--- /dev/null
+++ b/tests/python/test_docker_nb_populate_retry.py
@@ -0,0 +1,588 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-Present the Unsloth team. See /studio/LICENSE.AGPL-3.0
+
+"""First-boot population must not claim a commit it did not finish copying.
+
+A `cp -a` that fails is skipped silently and gets no state entry, so phase 1b never
+restores it -- and stamping the commit anyway tells the phase 2 refresh it is already
+synced, so the notebook is gone for good on an offline container.
+
+Driven end to end against the real script with the refresh disabled. The blocked path
+is a plain FILE where a directory has to be, which is ENOTDIR for root too, so this
+cannot silently pass under a root CI container the way a chmod would.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import os
+import shutil
+import subprocess
+from pathlib import Path
+
+import pytest
+
+REPO_ROOT = Path(__file__).resolve().parents[2]
+SYNC = REPO_ROOT / "docker" / "unsloth_sync_notebooks.sh"
+
+TEMPLATE_COMMIT = "a" * 40
+
+behavioural = pytest.mark.skipif(
+ any(shutil.which(tool) is None for tool in ("bash", "sha256sum")),
+ reason = "needs bash and sha256sum",
+)
+
+
+def _sha256(path: Path) -> str:
+ return hashlib.sha256(path.read_bytes()).hexdigest()
+
+
+def _template(tmp_path: Path) -> Path:
+ template = tmp_path / "template"
+ (template / "sub").mkdir(parents = True)
+ (template / "a.ipynb").write_text("A", encoding = "utf-8")
+ (template / "sub" / "b.ipynb").write_text("B", encoding = "utf-8")
+ (template / ".unsloth_template_commit").write_text(TEMPLATE_COMMIT + "\n", encoding = "utf-8")
+ return template
+
+
+def _run(tmp_path: Path, template: Path, dest: Path) -> subprocess.CompletedProcess:
+ return subprocess.run(
+ ["bash", str(SYNC)],
+ capture_output = True,
+ text = True,
+ timeout = 300,
+ env = dict(
+ os.environ,
+ UNSLOTH_NOTEBOOKS_TEMPLATE = str(template),
+ UNSLOTH_NOTEBOOKS_DIR = str(dest),
+ # phase 2 needs a clone; the offline half must retry on its own
+ UNSLOTH_SKIP_NOTEBOOK_REFRESH = "1",
+ UNSLOTH_SKIP_NOTEBOOK_VIEW = "1",
+ UNSLOTH_KEEP_COLAB_INTRO = "1",
+ ),
+ )
+
+
+def _state(dest: Path) -> dict:
+ path = dest / ".unsloth_sync_state"
+ if not path.is_file():
+ return {}
+ out = {}
+ for line in path.read_text(encoding = "utf-8").splitlines():
+ parts = line.split(" ", 1)
+ if len(parts) == 2:
+ out[parts[1]] = parts[0]
+ return out
+
+
+@behavioural
+def test_a_failed_copy_leaves_the_commit_unstamped_and_retries_next_start(tmp_path: Path):
+ template = _template(tmp_path)
+ dest = tmp_path / "dest"
+ dest.mkdir()
+ # a regular file, so the copy into it is ENOTDIR for root too
+ (dest / "sub").write_text("blocked", encoding = "utf-8")
+
+ first = _run(tmp_path, template, dest)
+ assert first.returncode == 0, first.stdout + first.stderr
+
+ assert (dest / "a.ipynb").read_text(encoding = "utf-8") == "A"
+ assert "a.ipynb" in _state(dest)
+ assert "sub/b.ipynb" not in _state(dest), "a copy that failed must not be recorded"
+ assert not (dest / ".unsloth_sync_commit").exists(), (
+ "stamping the template commit after an incomplete populate makes the "
+ "phase 2 refresh exit early, so the missing notebook never comes back"
+ )
+ assert (dest / ".unsloth_sync_partial").exists()
+
+ (dest / "sub").unlink()
+
+ second = _run(tmp_path, template, dest)
+ assert second.returncode == 0, second.stdout + second.stderr
+
+ assert (dest / "sub" / "b.ipynb").read_text(encoding = "utf-8") == "B"
+ assert _state(dest)["sub/b.ipynb"] == _sha256(dest / "sub" / "b.ipynb")
+ assert _state(dest)["a.ipynb"] == _sha256(dest / "a.ipynb")
+ assert (dest / ".unsloth_sync_commit").read_text(encoding = "utf-8").strip() == (TEMPLATE_COMMIT)
+ assert not (dest / ".unsloth_sync_partial").exists()
+
+
+@behavioural
+def test_a_clean_populate_stamps_the_commit_and_does_not_re_run(tmp_path: Path):
+ template = _template(tmp_path)
+ dest = tmp_path / "dest"
+ dest.mkdir()
+
+ assert _run(tmp_path, template, dest).returncode == 0
+ assert (dest / ".unsloth_sync_commit").read_text(encoding = "utf-8").strip() == (TEMPLATE_COMMIT)
+ assert not (dest / ".unsloth_sync_partial").exists()
+ before = _state(dest)
+ assert set(before) == {"a.ipynb", "sub/b.ipynb"}
+
+ # a re-run of phase 1 would drop this file's managed record, so an identical
+ # state is what proves the block was skipped
+ (dest / "a.ipynb").write_text("edited", encoding = "utf-8")
+
+ assert _run(tmp_path, template, dest).returncode == 0
+ assert _state(dest) == before
+ assert (dest / "a.ipynb").read_text(encoding = "utf-8") == "edited"
+
+
+@behavioural
+def test_the_partial_marker_is_not_recorded_as_a_notebook(tmp_path: Path):
+ # record_state() walks every file under DEST, so a dotfile missing from its skip
+ # list reaches users as a notebook to sync
+ template = _template(tmp_path)
+ dest = tmp_path / "dest"
+ dest.mkdir()
+ (dest / "sub").write_text("blocked", encoding = "utf-8")
+
+ assert _run(tmp_path, template, dest).returncode == 0
+ assert (dest / ".unsloth_sync_partial").exists()
+ assert ".unsloth_sync_partial" not in _state(dest)
+
+ source = SYNC.read_text(encoding = "utf-8")
+ skip = source[source.index("record_state() {") :]
+ skip = skip[: skip.index("printf")]
+ assert ".unsloth_sync_partial" in skip
+
+
+@behavioural
+def test_the_retry_keeps_records_the_refresh_added(tmp_path: Path):
+ """A retry rebuilds the state from the TEMPLATE alone, so anything the refresh did
+ in between is thrown away: a template file whose bytes upstream changed now differs
+ from the template and hits the "kept existing user file" branch, and a notebook that
+ exists only upstream is never visited at all. Both become user-owned for good, while
+ the commit marker is stamped anyway so it looks converged."""
+ template = _template(tmp_path)
+ dest = tmp_path / "dest"
+ dest.mkdir()
+ (dest / "sub").write_text("blocked", encoding = "utf-8")
+
+ assert _run(tmp_path, template, dest).returncode == 0
+ assert (dest / ".unsloth_sync_partial").exists()
+
+ # what the refresh does between the two boots
+ (dest / "a.ipynb").write_text("A-v2-from-upstream", encoding = "utf-8")
+ (dest / "remote_only.ipynb").write_text("R", encoding = "utf-8")
+ (dest / ".unsloth_sync_state").write_text(
+ f"{_sha256(dest / 'a.ipynb')} a.ipynb\n"
+ f"{_sha256(dest / 'remote_only.ipynb')} remote_only.ipynb\n",
+ encoding = "utf-8",
+ )
+
+ (dest / "sub").unlink()
+ second = _run(tmp_path, template, dest)
+ assert second.returncode == 0, second.stdout + second.stderr
+
+ state = _state(dest)
+ assert state.get("a.ipynb") == _sha256(
+ dest / "a.ipynb"
+ ), "the refreshed copy is ours, not the user's; dropping its record freezes it"
+ assert state.get("remote_only.ipynb") == _sha256(
+ dest / "remote_only.ipynb"
+ ), "a notebook that exists only upstream is never walked by the populate loop"
+ assert state.get("sub/b.ipynb") == _sha256(dest / "sub" / "b.ipynb")
+ assert (dest / "a.ipynb").read_text(
+ encoding = "utf-8"
+ ) == "A-v2-from-upstream", "the retry must not overwrite the newer copy with the baked template"
+ assert len(state) == 3, state
+
+
+@behavioural
+def test_a_first_boot_records_only_what_it_populated(tmp_path: Path):
+ """Non-vacuity for the merge above: with no prior state there is nothing to carry
+ forward, so a stray file in DEST must not acquire a record."""
+ template = _template(tmp_path)
+ dest = tmp_path / "dest"
+ dest.mkdir()
+ (dest / "not_ours.ipynb").write_text("N", encoding = "utf-8")
+
+ assert _run(tmp_path, template, dest).returncode == 0
+ assert set(_state(dest)) == {"a.ipynb", "sub/b.ipynb"}
+
+
+# Phase 1b restores a notebook the user deleted from the BAKED template, and records
+# the template's hash for it. When the refresh had already moved that notebook past
+# the image, the restore silently walks it backwards -- and phase 2 exits on
+# `remote == last`, so the sync marker has to come off or it stays there until
+# upstream happens to commit again.
+
+UPSTREAM_COMMIT = "b" * 40
+
+
+def _restored_run(tmp_path: Path, template: Path, dest: Path, recorded: str, body: str | None):
+ """State says `recorded` for a.ipynb; `body` is what is on disk, None to delete it."""
+ (dest / ".unsloth_sync_state").write_text(
+ f"{recorded} a.ipynb\n{_sha256(template / 'sub' / 'b.ipynb')} sub/b.ipynb\n",
+ encoding = "utf-8",
+ )
+ (dest / ".unsloth_sync_commit").write_text(UPSTREAM_COMMIT + "\n", encoding = "utf-8")
+ if body is None:
+ (dest / "a.ipynb").unlink()
+ else:
+ (dest / "a.ipynb").write_text(body, encoding = "utf-8")
+ return _run(tmp_path, template, dest)
+
+
+@behavioural
+def test_a_notebook_restored_backwards_drops_the_sync_marker(tmp_path: Path):
+ template, dest = _template(tmp_path), tmp_path / "dest"
+ assert _run(tmp_path, template, dest).returncode == 0
+
+ # the refresh had taken a.ipynb past the baked "A"; the user then deletes it
+ run = _restored_run(tmp_path, template, dest, "c" * 64, None)
+ assert run.returncode == 0, run.stdout + run.stderr
+
+ assert (dest / "a.ipynb").read_text(encoding = "utf-8") == "A", "it was restored"
+ assert not (dest / ".unsloth_sync_commit").is_file(), (
+ "the marker survived a downgrade, so the refresh exits on remote == last and "
+ "the notebook stays on the image's older copy"
+ )
+ assert _state(dest)["a.ipynb"] == _sha256(template / "a.ipynb")
+ assert "1 needing a refresh" in run.stdout, run.stdout
+
+
+@behavioural
+def test_a_restore_that_changes_nothing_keeps_the_marker(tmp_path: Path):
+ """Non-vacuity and the cost control: an ordinary delete of a notebook that never
+ moved past the image must not force a full clone on the next start."""
+ template, dest = _template(tmp_path), tmp_path / "dest"
+ assert _run(tmp_path, template, dest).returncode == 0
+
+ run = _restored_run(tmp_path, template, dest, _sha256(template / "a.ipynb"), None)
+ assert run.returncode == 0, run.stdout + run.stderr
+
+ assert (dest / "a.ipynb").read_text(encoding = "utf-8") == "A"
+ assert (dest / ".unsloth_sync_commit").read_text(encoding = "utf-8").strip() == UPSTREAM_COMMIT
+ assert "0 needing a refresh" in run.stdout, run.stdout
+
+
+@behavioural
+def test_a_notebook_still_on_disk_is_not_touched(tmp_path: Path):
+ """The restore is only for files that are GONE; a user's edit stays and keeps the
+ marker, because nothing was walked backwards."""
+ template, dest = _template(tmp_path), tmp_path / "dest"
+ assert _run(tmp_path, template, dest).returncode == 0
+
+ run = _restored_run(tmp_path, template, dest, "c" * 64, "MY OWN WORK")
+ assert run.returncode == 0, run.stdout + run.stderr
+
+ assert (dest / "a.ipynb").read_text(encoding = "utf-8") == "MY OWN WORK"
+ assert (dest / ".unsloth_sync_commit").read_text(encoding = "utf-8").strip() == UPSTREAM_COMMIT
+
+
+# --- a stale state staging file the populate cannot truncate --------------------------
+# A run killed between the truncate and the mv leaves $STATE.tmp behind. When that run
+# was a different uid (root once, then `--user`) the populate cannot empty it, every
+# append fails, and the mv -- which needs write on DEST, not on the file -- publishes
+# the FOREIGN file as our state. 0444 on a file this uid owns reproduces that, since
+# open-for-write consults the owner bits.
+@behavioural
+def test_a_stale_unwritable_state_temp_is_not_published_as_our_state(tmp_path: Path):
+ template = _template(tmp_path)
+ dest = tmp_path / "dest"
+ dest.mkdir()
+ stale = dest / ".unsloth_sync_state.tmp"
+ stale.write_text("deadbeef stale.ipynb\n", encoding = "utf-8")
+ stale.chmod(0o444)
+
+ run = _run(tmp_path, template, dest)
+ assert run.returncode == 0, run.stdout + run.stderr
+
+ state = _state(dest)
+ assert (
+ "stale.ipynb" not in state
+ ), "a leftover from an interrupted run was adopted as the state of this one"
+ assert state == {
+ "a.ipynb": _sha256(dest / "a.ipynb"),
+ "sub/b.ipynb": _sha256(dest / "sub" / "b.ipynb"),
+ }, state
+ assert (dest / ".unsloth_sync_commit").read_text(encoding = "utf-8").strip() == TEMPLATE_COMMIT
+ assert not (dest / ".unsloth_sync_partial").exists()
+
+
+@behavioural
+def test_an_unstageable_state_leaves_the_marker_off_instead_of_copying(tmp_path: Path):
+ """Fail CLOSED when the staging path cannot be cleared either, exactly as the
+ refresh child does: notebooks we cannot record read as user edits on the next run,
+ which is `kept`, not `failed`, so the marker would be stamped over them for good.
+ A DIRECTORY at the staging path is unlinkable and untruncatable for root too."""
+ template = _template(tmp_path)
+ dest = tmp_path / "dest"
+ dest.mkdir()
+ (dest / ".unsloth_sync_state.tmp").mkdir()
+
+ run = _run(tmp_path, template, dest)
+ assert run.returncode == 0, run.stdout + run.stderr
+
+ assert not (dest / ".unsloth_sync_state").exists(), run.stdout + run.stderr
+ assert not (
+ dest / ".unsloth_sync_commit"
+ ).exists(), "stamping the commit here strands every notebook this run copied"
+ assert (dest / ".unsloth_sync_partial").exists()
+ assert not (dest / "a.ipynb").exists(), "nothing may be published without a record"
+ assert "could not be staged" in run.stdout, run.stdout
+
+
+# Staging the temp file proves DEST was writable ONCE, not that it stays so. A quota
+# or ENOSPC that lands on a post-copy `printf >> "$STATE.tmp"` leaves the notebook on
+# disk with no record, and an unrecorded file is read as a user edit and never
+# refreshed again -- while the marker is stamped anyway, because only `cp` failures
+# were counted. RLIMIT_FSIZE reproduces it without needing a real full filesystem:
+# the tiny notebooks copy fine, the growing state file is what hits the ceiling.
+def _run_capped(template: Path, dest: Path, max_bytes: int):
+ import resource
+ import signal
+
+ def _cap():
+ # SIGXFSZ would kill the script outright; the shell must SEE the write error
+ signal.signal(signal.SIGXFSZ, signal.SIG_IGN)
+ resource.setrlimit(resource.RLIMIT_FSIZE, (max_bytes, max_bytes))
+
+ return subprocess.run(
+ ["bash", str(SYNC)],
+ capture_output = True,
+ text = True,
+ timeout = 300,
+ preexec_fn = _cap,
+ env = dict(
+ os.environ,
+ UNSLOTH_NOTEBOOKS_TEMPLATE = str(template),
+ UNSLOTH_NOTEBOOKS_DIR = str(dest),
+ UNSLOTH_SKIP_NOTEBOOK_REFRESH = "1",
+ UNSLOTH_SKIP_NOTEBOOK_VIEW = "1",
+ UNSLOTH_KEEP_COLAB_INTRO = "1",
+ ),
+ )
+
+
+def _many_template(tmp_path: Path, count: int) -> Path:
+ template = tmp_path / "template"
+ template.mkdir(parents = True)
+ for i in range(count):
+ (template / f"n{i}.ipynb").write_text(f"N{i}", encoding = "utf-8")
+ (template / ".unsloth_template_commit").write_text(TEMPLATE_COMMIT + "\n", encoding = "utf-8")
+ return template
+
+
+@behavioural
+def test_a_failed_state_append_holds_back_the_commit_marker(tmp_path: Path):
+ """A record lost after a successful copy must count as a population failure."""
+ template = _many_template(tmp_path, 15)
+ dest = tmp_path / "dest"
+ dest.mkdir()
+
+ run = _run_capped(template, dest, 512)
+ assert run.returncode == 0, run.stdout + run.stderr
+
+ copied = sorted(p.name for p in dest.glob("*.ipynb"))
+ recorded = _state(dest)
+ assert len(copied) > len(
+ recorded
+ ), "the cap did not bite; this test proves nothing unless some append failed"
+ assert not (
+ dest / ".unsloth_sync_commit"
+ ).exists(), "notebooks copied but not recorded are user-owned for good once this is stamped"
+ assert (dest / ".unsloth_sync_partial").exists(), run.stdout
+
+
+@behavioural
+def test_the_retry_after_a_failed_append_converges(tmp_path: Path):
+ """And the retry must actually finish the job, not just defer forever."""
+ template = _many_template(tmp_path, 15)
+ dest = tmp_path / "dest"
+ dest.mkdir()
+
+ _run_capped(template, dest, 512)
+ assert not (dest / ".unsloth_sync_commit").exists()
+
+ run = _run(tmp_path, template, dest)
+ assert run.returncode == 0, run.stdout + run.stderr
+ assert len(_state(dest)) == 15, _state(dest)
+ assert (dest / ".unsloth_sync_commit").exists(), run.stdout
+ assert not (dest / ".unsloth_sync_partial").exists()
+
+
+# CLASS GUARD, not another instance test. An unchecked append to a staged state file
+# has now been found four separate times in this script: the populate copy loop, the
+# populate merge block, the refresh restore loop (RS_TMP) and the refresh publish loop
+# (TMPSTATE). Each time the record was lost while the failure counter stayed 0, so a
+# truncated state was published AND the commit marker advanced, which strands every
+# notebook whose hash was dropped. Rather than wait for the fifth, require every append
+# to a staged state file to be accounted for.
+_STAGED_STATE_TARGETS = ('>> "$STATE.tmp"', '>> "$TMPSTATE"', '>> "$RS_TMP"')
+
+# an append is accounted for if it handles its own failure, or if the very next lines
+# count one
+_ACCOUNTED = (
+ "|| populate_failed=",
+ "|| failed=",
+ "|| rs_ok=0",
+ "|| unrecorded ",
+ "|| drop_unrecordable ",
+ "populate_failed=$((populate_failed + 1))",
+ "failed=$((failed + 1))",
+ "rs_ok=0",
+)
+
+
+def _exempt_lines(lines):
+ """record_state() is dead code (no caller anywhere; the companion test below
+ keeps it that way), and record_tmpstate() is the shared helper whose whole job is
+ to perform the append and report the status its CALLERS must handle."""
+ out = set()
+ for name in ("record_state() {", "record_tmpstate() {"):
+ start = next(i for i, l in enumerate(lines) if l.startswith(name))
+ end = next(i for i in range(start, len(lines)) if lines[i] == "}")
+ out.update(range(start, end + 1))
+ return out
+
+
+def test_every_staged_state_append_is_checked():
+ lines = SYNC.read_text(encoding = "utf-8").splitlines()
+ exempt = _exempt_lines(lines)
+ unchecked = []
+ for i, line in enumerate(lines):
+ if i in exempt:
+ continue
+ if not any(t in line for t in _STAGED_STATE_TARGETS):
+ continue
+ window = " ".join(lines[i : i + 3])
+ if not any(marker in window for marker in _ACCOUNTED):
+ unchecked.append((i + 1, line.strip()))
+ assert not unchecked, (
+ "these appends to a staged state file neither handle their own failure nor "
+ "have one counted immediately after, so a lost record would still publish a "
+ "truncated state and advance the commit marker:\n"
+ + "\n".join(f" line {n}: {t}" for n, t in unchecked)
+ )
+
+
+def test_every_record_tmpstate_call_handles_a_failed_write():
+ """The class that keeps recurring is not the raw append, it is the UNHANDLED
+ record failure. Counting it is not enough on its own: the truncated state is
+ published either way, so the file must also be rolled back or the write retried.
+ Every call site has to say which."""
+ lines = SYNC.read_text(encoding = "utf-8").splitlines()
+ exempt = _exempt_lines(lines)
+ bare = []
+ for i, line in enumerate(lines):
+ if i in exempt or "record_tmpstate " not in line:
+ continue
+ stripped = line.strip()
+ if stripped.startswith("#"):
+ continue
+ if "||" in stripped or stripped.startswith("if record_tmpstate"):
+ continue
+ bare.append((i + 1, stripped))
+ assert not bare, (
+ "these record_tmpstate calls ignore a failed write, so the notebook stays on "
+ "disk with no record and the next refresh treats it as a user edit:\n"
+ + "\n".join(f" line {n}: {t}" for n, t in bare)
+ )
+
+
+def test_a_failed_record_can_roll_the_notebook_back():
+ """drop_unrecordable must only ever remove OUR copy, never a user edit."""
+ body = SYNC.read_text(encoding = "utf-8")
+ assert "drop_unrecordable() {" in body
+ fn = body[body.index("drop_unrecordable() {") :]
+ fn = fn[: fn.index("\n}")]
+ assert (
+ 'hash_of "$_d"' in fn and "${LAST[$1]:-}" in fn
+ ), "the rollback must be gated on the file still matching the last record"
+
+
+def test_the_marker_advance_is_gated_on_the_failure_counters():
+ """The guard above is only worth anything while the counters still hold the
+ marker back."""
+ body = SYNC.read_text(encoding = "utf-8")
+ assert '[ "$failed" -eq 0 ] && [ "$published" -eq 1 ]' in body
+ assert '[ "$populate_failed" -eq 0 ]' in body
+
+
+def test_record_state_is_still_uncalled():
+ """The exemption above depends on it. A call site makes its unchecked append live,
+ and it has a second problem waiting: its loop is a PIPELINE, so a failure counter
+ set inside would not survive the subshell."""
+ body = SYNC.read_text(encoding = "utf-8")
+ calls = [
+ ln.strip()
+ for ln in body.splitlines()
+ if "record_state" in ln
+ and not ln.startswith("record_state() {")
+ and not ln.lstrip().startswith("#")
+ ]
+ assert not calls, f"record_state gained a caller; the exemption is now unsound: {calls}"
+
+
+# Section 1b (restore deleted notebooks) rewrites the WHOLE state on every boot, and
+# it was the one state writer using mktemp instead of a sibling of $STATE. That gave
+# it /tmp (a different filesystem from $DEST in the shipped image, so the publish was
+# a cross-device copy that can leave a half-written state) and mode 0600 owned by
+# whoever booted. A root boot then left $STATE unreadable to a later `--user` boot,
+# and an unreadable $STATE is the dangerous input: there is no `set -e`, so the failed
+# redirect just skips the loop body and an EMPTY state gets published over a valid one.
+def _state_path(dest: Path) -> Path:
+ return dest / ".unsloth_sync_state"
+
+
+@behavioural
+def test_an_unreadable_state_is_never_replaced_by_an_empty_one(tmp_path: Path):
+ template = _template(tmp_path)
+ dest = tmp_path / "dest"
+ dest.mkdir()
+ assert _run(tmp_path, template, dest).returncode == 0
+ before = _state(dest)
+ assert before, "nothing to protect; the populate did not record anything"
+
+ _state_path(dest).chmod(0o000)
+ try:
+ run = _run(tmp_path, template, dest)
+ finally:
+ _state_path(dest).chmod(0o644)
+
+ assert run.returncode == 0, run.stdout + run.stderr
+ assert _state(dest) == before, (
+ "the state was replaced while unreadable; every notebook it described is now "
+ "read as a user edit and never updated again\n" + run.stdout + run.stderr
+ )
+ assert "unreadable" in run.stdout, run.stdout
+
+
+@behavioural
+def test_the_restore_loop_does_not_downgrade_the_state_file(tmp_path: Path):
+ """It runs on every boot, so a mode or owner change here compounds."""
+ template = _template(tmp_path)
+ dest = tmp_path / "dest"
+ dest.mkdir()
+ _run(tmp_path, template, dest)
+ first = _state_path(dest).stat().st_mode & 0o777
+
+ _run(tmp_path, template, dest) # a second boot re-runs section 1b
+ second = _state_path(dest).stat().st_mode & 0o777
+
+ assert second == first, f"the state mode changed across boots: {oct(first)} -> {oct(second)}"
+ assert second & 0o044, (
+ f"the state is not group/world readable ({oct(second)}); a root boot leaves it "
+ f"unreadable to a later --user boot, which is the input above"
+ )
+
+
+def test_every_state_writer_stages_beside_the_state_file():
+ """mktemp lands in /tmp, a different filesystem from $DEST under the documented
+ bind mount, so the publish stops being an atomic same-directory rename."""
+ body = SYNC.read_text(encoding = "utf-8")
+ assert 'RS_TMP="$STATE.tmp"' in body, "the restore loop must stage beside $STATE"
+ assert 'RS_TMP="$(mktemp)"' not in body
+
+
+def test_the_restore_publish_failure_is_not_silent():
+ """Its sibling branch three lines down is loud and drops the marker; this one used
+ to swallow the failure while the 'restored N' success message still printed."""
+ body = SYNC.read_text(encoding = "utf-8")
+ block = body[body.index('mv "$RS_TMP" "$STATE"') :][:600]
+ assert "could not be published" in block, block[:200]
+ assert 'rm -f "$SYNCED"' in block, block[:200]
diff --git a/tests/python/test_docker_nb_refresh_state_durability.py b/tests/python/test_docker_nb_refresh_state_durability.py
new file mode 100644
index 00000000000..9ac9e70a2d4
--- /dev/null
+++ b/tests/python/test_docker_nb_refresh_state_durability.py
@@ -0,0 +1,570 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved.
+"""A refreshed notebook must never end up on disk without a state record.
+
+That single combination is unrecoverable. Withholding the commit marker is not
+enough, because the truncated state is still published: the NEXT refresh reads the
+unrecorded notebook as a user edit, keeps it, finds nothing failed, and stamps the
+marker over it, so it is unmanaged for good.
+
+Driven end to end against the real script with a local repository standing in for
+upstream. RLIMIT_FSIZE fills the disk part-way through, sized so the clone still
+fits: git's index costs ceil((62 + len(path)) / 8) * 8 per entry while the state
+costs 67 + len(path), so a 17-character name makes the state outgrow the index and
+opens a window between them. Without that the clone always dies first and the state
+write is never reached.
+"""
+
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+from pathlib import Path
+
+import pytest
+
+REPO_ROOT = Path(__file__).resolve().parents[2]
+SYNC = REPO_ROOT / "docker" / "unsloth_sync_notebooks.sh"
+
+NOTEBOOKS = 500
+CAP_KIB = 40 # between the clone's 40067-byte index and the 42000-byte state
+
+needs_git = pytest.mark.skipif(
+ shutil.which("git") is None or shutil.which("sha256sum") is None,
+ reason = "the refresh path needs git and sha256sum",
+)
+
+
+def _upstream(tmp_path: Path) -> Path:
+ up = tmp_path / "up"
+ up.mkdir()
+ for i in range(1, NOTEBOOKS + 1):
+ (up / f"nb{i:09d}.ipynb").write_text("N", encoding = "utf-8")
+ env = dict(os.environ, GIT_CONFIG_GLOBAL = "/dev/null", GIT_CONFIG_SYSTEM = "/dev/null")
+ subprocess.run(["git", "init", "-q", "."], cwd = up, check = True, env = env)
+ subprocess.run(["git", "add", "-A"], cwd = up, check = True, env = env)
+ subprocess.run(
+ ["git", "-c", "user.name=t", "-c", "user.email=t@t", "commit", "-qm", "init"],
+ cwd = up,
+ check = True,
+ env = env,
+ )
+ return up
+
+
+def _template(tmp_path: Path) -> Path:
+ tpl = tmp_path / "tpl"
+ tpl.mkdir()
+ (tpl / "seed.ipynb").write_text("T", encoding = "utf-8")
+ (tpl / ".unsloth_template_commit").write_text("a" * 40 + "\n", encoding = "utf-8")
+ return tpl
+
+
+def _run(
+ tpl: Path,
+ dest: Path,
+ up: Path,
+ *,
+ cap_kib: int | None = None,
+ refresh: bool,
+ keep_removed: bool = False,
+):
+ def _cap():
+ import resource
+ import signal
+
+ # SIGXFSZ would kill the script; the shell has to SEE the write error
+ signal.signal(signal.SIGXFSZ, signal.SIG_IGN)
+ n = cap_kib * 1024
+ resource.setrlimit(resource.RLIMIT_FSIZE, (n, n))
+
+ env = dict(
+ os.environ,
+ UNSLOTH_NOTEBOOKS_TEMPLATE = str(tpl),
+ UNSLOTH_NOTEBOOKS_DIR = str(dest),
+ UNSLOTH_NOTEBOOKS_REPO = str(up),
+ UNSLOTH_SKIP_NOTEBOOK_VIEW = "1",
+ UNSLOTH_KEEP_COLAB_INTRO = "1",
+ )
+ if keep_removed:
+ env["UNSLOTH_KEEP_REMOVED_NOTEBOOKS"] = "1"
+ if refresh:
+ # run the refresh inline; the real one detaches and discards its output
+ env["UNSLOTH_NB_REFRESH_CHILD"] = "1"
+ else:
+ env["UNSLOTH_SKIP_NOTEBOOK_REFRESH"] = "1"
+ return subprocess.run(
+ ["bash", str(SYNC)],
+ capture_output = True,
+ text = True,
+ timeout = 600,
+ env = env,
+ preexec_fn = _cap if cap_kib else None,
+ )
+
+
+def _recorded(dest: Path) -> set[str]:
+ state = dest / ".unsloth_sync_state"
+ if not state.exists():
+ return set()
+ out = set()
+ for line in state.read_text(encoding = "utf-8").splitlines():
+ _, _, rel = line.partition(" ")
+ if rel:
+ out.add(rel)
+ return out
+
+
+def _published(dest: Path) -> set[str]:
+ return {p.name for p in dest.glob("*.ipynb")}
+
+
+@needs_git
+def test_no_notebook_is_published_without_a_record(tmp_path: Path):
+ """The invariant. A file we wrote but could not record is the unrecoverable
+ state, so it must be rolled back rather than left behind."""
+ tpl, dest, up = _template(tmp_path), tmp_path / "dest", _upstream(tmp_path)
+ dest.mkdir()
+ _run(tpl, dest, up, refresh = False)
+
+ run = _run(tpl, dest, up, cap_kib = CAP_KIB, refresh = True)
+ assert "could not be written" in run.stdout, (
+ "the cap did not bite; this test proves nothing unless some append failed\n"
+ + run.stdout
+ + run.stderr
+ )
+
+ orphans = _published(dest) - _recorded(dest) - {"seed.ipynb"}
+ assert not orphans, (
+ f"{len(orphans)} notebook(s) on disk with no state record; the next refresh "
+ f"reads them as user edits and stops updating them: {sorted(orphans)[:5]}"
+ )
+
+
+@needs_git
+def test_the_next_refresh_recovers_everything_that_was_rolled_back(tmp_path: Path):
+ """Rollback is only correct if the retry actually restores them."""
+ tpl, dest, up = _template(tmp_path), tmp_path / "dest", _upstream(tmp_path)
+ dest.mkdir()
+ _run(tpl, dest, up, refresh = False)
+
+ first = _run(tpl, dest, up, cap_kib = CAP_KIB, refresh = True)
+ assert "could not be written" in first.stdout, first.stdout + first.stderr
+ # strictly fewer than the full set: `< NOTEBOOKS + 1` was vacuous, since the
+ # run yields NOTEBOOKS either way and seed.ipynb is dropped as deleted upstream
+ assert (
+ len(_published(dest)) < NOTEBOOKS
+ ), "nothing was rolled back, so the retry below proves nothing"
+
+ second = _run(tpl, dest, up, refresh = True)
+ assert "kept (your edits)" in second.stdout, second.stdout
+ kept = int(second.stdout.split("updated, ")[1].split(" kept")[0])
+ assert kept == 0, (
+ f"{kept} notebook(s) became user-owned after a disk-full refresh; they would "
+ f"never be updated again\n{second.stdout}"
+ )
+ # seed.ipynb is template-only, so the refresh drops it as deleted upstream
+ assert len(_recorded(dest)) == NOTEBOOKS, sorted(_recorded(dest))[:5]
+
+
+def _commit_upstream_change(up: Path):
+ """A second commit so the next refresh does not exit early on remote == last."""
+ (up / f"nb{NOTEBOOKS + 1:09d}.ipynb").write_text("N", encoding = "utf-8")
+ env = dict(os.environ, GIT_CONFIG_GLOBAL = "/dev/null", GIT_CONFIG_SYSTEM = "/dev/null")
+ subprocess.run(["git", "add", "-A"], cwd = up, check = True, env = env)
+ subprocess.run(
+ ["git", "-c", "user.name=t", "-c", "user.email=t@t", "commit", "-qm", "more"],
+ cwd = up,
+ check = True,
+ env = env,
+ )
+
+
+@needs_git
+def test_a_user_edited_notebook_is_never_rolled_back(tmp_path: Path):
+ """The rollback removes OUR copy so a lost record is recoverable. It must never
+ touch a notebook the user changed.
+
+ Every SECOND notebook is edited, not every twenty-fifth. The cap bites near the
+ end of the walk, so a sparse edited set can miss the failing range entirely and
+ the rollback is then never asked about a user edit -- which is how the first
+ version of this test passed without executing the code it named. The assertion
+ that some pristine notebook WAS removed is what keeps it honest.
+ """
+ tpl, dest, up = _template(tmp_path), tmp_path / "dest", _upstream(tmp_path)
+ dest.mkdir()
+ _run(tpl, dest, up, refresh = False)
+ _run(tpl, dest, up, refresh = True) # uncapped: everything published and recorded
+ assert len(_published(dest)) == NOTEBOOKS
+
+ edited = {f"nb{i:09d}.ipynb" for i in range(2, NOTEBOOKS + 1, 2)}
+ for name in edited:
+ (dest / name).write_text("USER EDIT", encoding = "utf-8")
+ pristine = {f"nb{i:09d}.ipynb" for i in range(1, NOTEBOOKS + 1, 2)}
+ _commit_upstream_change(up)
+
+ run = _run(tpl, dest, up, cap_kib = CAP_KIB, refresh = True)
+ assert "could not be written" in run.stdout, run.stdout + run.stderr
+
+ survivors = _published(dest)
+ # non-vacuity: the rollback has to have actually fired somewhere in this run
+ assert pristine - survivors, (
+ "no notebook was rolled back, so this test never asked the rollback about a "
+ "user edit and proves nothing"
+ )
+ lost = edited - survivors
+ assert not lost, f"user edits destroyed by the rollback: {sorted(lost)[:5]}"
+ for name in sorted(edited):
+ assert (dest / name).read_text(
+ encoding = "utf-8"
+ ) == "USER EDIT", f"{name} was overwritten while the disk was full"
+
+
+# ---------------------------------------------------------------------------
+# The refresh child reads $STATE too, and IT is the copy that runs by default.
+# The guard added for the section 1b reader did not cover it, and the test that
+# was supposed to prove it passed only because its helper sets
+# UNSLOTH_SKIP_NOTEBOOK_REFRESH=1. These deliberately do not.
+# ---------------------------------------------------------------------------
+def _json_upstream(tmp_path: Path, count: int) -> Path:
+ """Valid notebook JSON, so the body-aware comparison can report SAME and the
+ `unchanged` branch is reachable. With one-byte files it never is, which is why
+ the rollback below had no coverage."""
+ import json
+
+ up = tmp_path / "up"
+ up.mkdir()
+ body = json.dumps(
+ {
+ "cells": [
+ {
+ "cell_type": "code",
+ "source": ["print(1)\n"],
+ "metadata": {},
+ "outputs": [],
+ "execution_count": None,
+ }
+ ],
+ "metadata": {},
+ "nbformat": 4,
+ "nbformat_minor": 5,
+ }
+ )
+ for i in range(1, count + 1):
+ (up / f"nb{i:09d}.ipynb").write_text(body, encoding = "utf-8")
+ env = dict(os.environ, GIT_CONFIG_GLOBAL = "/dev/null", GIT_CONFIG_SYSTEM = "/dev/null")
+ subprocess.run(["git", "init", "-q", "."], cwd = up, check = True, env = env)
+ subprocess.run(["git", "add", "-A"], cwd = up, check = True, env = env)
+ subprocess.run(
+ ["git", "-c", "user.name=t", "-c", "user.email=t@t", "commit", "-qm", "init"],
+ cwd = up,
+ check = True,
+ env = env,
+ )
+ return up
+
+
+@needs_git
+def test_the_refresh_child_never_republishes_an_unreadable_state_as_empty(tmp_path: Path):
+ """No UNSLOTH_SKIP_NOTEBOOK_REFRESH here: that flag is what hid this."""
+ tpl, dest, up = _template(tmp_path), tmp_path / "dest", _upstream(tmp_path)
+ dest.mkdir()
+ _run(tpl, dest, up, refresh = False)
+ _run(tpl, dest, up, refresh = True)
+ before = _recorded(dest)
+ assert len(before) == NOTEBOOKS
+
+ state = dest / ".unsloth_sync_state"
+ state.chmod(0o000)
+ try:
+ run = _run(tpl, dest, up, refresh = True)
+ finally:
+ state.chmod(0o644)
+
+ assert run.returncode == 0, run.stdout + run.stderr
+ assert state.stat().st_size > 0, (
+ "the refresh child published an EMPTY state over a valid one; every notebook "
+ "it described is now read as a user edit and frozen\n" + run.stdout
+ )
+ assert _recorded(dest) == before, run.stdout
+ assert "0 updated" not in run.stdout, (
+ "the refresh ran with an empty LAST, which is the defect itself\n" + run.stdout
+ )
+
+
+@needs_git
+def test_a_failed_record_on_an_unchanged_notebook_rolls_it_back(tmp_path: Path):
+ """drop_unrecordable's removal, which nothing exercised before.
+
+ Its other call sites either hand it a user-edited file (hash gate declines) or a
+ missing one (early return), so the suite could call it seven times and roll back
+ zero. The `unchanged` branch is the reachable one that must actually remove.
+ """
+ tpl, dest = _template(tmp_path), tmp_path / "dest"
+ up = _json_upstream(tmp_path, NOTEBOOKS)
+ dest.mkdir()
+ _run(tpl, dest, up, refresh = False)
+ _run(tpl, dest, up, refresh = True)
+ assert len(_published(dest)) == NOTEBOOKS
+
+ _commit_upstream_change(up)
+ run = _run(tpl, dest, up, cap_kib = CAP_KIB, refresh = True)
+ assert "could not be written" in run.stdout, run.stdout + run.stderr
+ assert "kept (only header/footer changed upstream)" in run.stdout, run.stdout
+
+ survivors = _published(dest)
+ rolled_back = NOTEBOOKS - len([n for n in survivors if n.startswith("nb")])
+ assert rolled_back > 0, (
+ "no unchanged notebook was rolled back, so drop_unrecordable's removal is "
+ "still unexercised\n" + run.stdout
+ )
+ # and the retry has to restore them
+ second = _run(tpl, dest, up, refresh = True)
+ assert len(_published(dest)) == NOTEBOOKS + 1, second.stdout
+
+
+@needs_git
+def test_keeping_a_removed_notebook_keeps_its_record_too(tmp_path: Path):
+ """UNSLOTH_KEEP_REMOVED_NOTEBOOKS kept the FILE and dropped its RECORD, so the
+ next refresh read it as a user edit -- and turning the option back off never
+ recovered it, because by then it is no longer in the state."""
+ tpl, dest, up = _template(tmp_path), tmp_path / "dest", _upstream(tmp_path)
+ dest.mkdir()
+ _run(tpl, dest, up, refresh = False)
+ _run(tpl, dest, up, refresh = True)
+ victim = f"nb{1:09d}.ipynb"
+ assert victim in _recorded(dest)
+
+ (up / victim).unlink()
+ env = dict(os.environ, GIT_CONFIG_GLOBAL = "/dev/null", GIT_CONFIG_SYSTEM = "/dev/null")
+ subprocess.run(["git", "add", "-A"], cwd = up, check = True, env = env)
+ subprocess.run(
+ ["git", "-c", "user.name=t", "-c", "user.email=t@t", "commit", "-qm", "del"],
+ cwd = up,
+ check = True,
+ env = env,
+ )
+
+ run = _run(tpl, dest, up, refresh = True, keep_removed = True)
+ assert (dest / victim).exists(), "the opt-out did not keep the file: " + run.stdout
+ assert victim in _recorded(dest), (
+ "the file was kept but its record was dropped, so the next refresh reads a "
+ "notebook the user never touched as a user edit\n" + run.stdout
+ )
+
+
+@needs_git
+def test_an_unrecorded_notebook_identical_to_upstream_is_adopted(tmp_path: Path):
+ """When the publish rollback cannot unlink -- a single-FILE bind mount gives
+ EBUSY there, the same case the rename at line 562 already works around -- the
+ published bytes stay on disk with no record, and no further append is possible in
+ that run. Rolling the bytes back instead would not help, because the file is
+ still unrecorded and so still read as a user edit, and discarding the staged
+ state would strand every notebook the run DID record. The only repair is for a
+ later refresh to notice that a file identical to the clone was never a user edit
+ and take it back under management."""
+ tpl, dest, up = _template(tmp_path), tmp_path / "dest", _upstream(tmp_path)
+ dest.mkdir()
+ _run(tpl, dest, up, refresh = False)
+ _run(tpl, dest, up, refresh = True)
+
+ orphan = f"nb{7:09d}.ipynb"
+ state = dest / ".unsloth_sync_state"
+ surviving = [
+ ln
+ for ln in state.read_text(encoding = "utf-8").splitlines()
+ if not ln.endswith(" " + orphan)
+ ]
+ state.write_text("\n".join(surviving) + "\n", encoding = "utf-8")
+ # the run that lost the record withheld the marker, so the next start refreshes
+ (dest / ".unsloth_sync_commit").unlink(missing_ok = True)
+ assert orphan not in _recorded(dest)
+ assert (dest / orphan).exists()
+
+ run = _run(tpl, dest, up, refresh = True)
+ assert orphan in _recorded(dest), (
+ "a notebook byte-identical to the clone but missing from the state was read "
+ "as a user edit, so it stays unmanaged and stops tracking upstream for "
+ "good\n" + run.stdout + run.stderr
+ )
+
+
+@needs_git
+def test_a_genuinely_edited_unrecorded_notebook_is_still_left_alone(tmp_path: Path):
+ """The adoption above must key on the content matching the clone EXACTLY. An
+ unrecorded file whose bytes differ is the real user-edit case and must keep its
+ hands-off treatment."""
+ tpl, dest, up = _template(tmp_path), tmp_path / "dest", _upstream(tmp_path)
+ dest.mkdir()
+ _run(tpl, dest, up, refresh = False)
+ _run(tpl, dest, up, refresh = True)
+
+ orphan = f"nb{7:09d}.ipynb"
+ state = dest / ".unsloth_sync_state"
+ surviving = [
+ ln
+ for ln in state.read_text(encoding = "utf-8").splitlines()
+ if not ln.endswith(" " + orphan)
+ ]
+ state.write_text("\n".join(surviving) + "\n", encoding = "utf-8")
+ (dest / ".unsloth_sync_commit").unlink(missing_ok = True)
+ (dest / orphan).write_text("MINE, do not touch", encoding = "utf-8")
+
+ run = _run(tpl, dest, up, refresh = True)
+ assert (dest / orphan).read_text(encoding = "utf-8") == "MINE, do not touch", (
+ "an unrecorded notebook the user had edited was overwritten\n" + run.stdout + run.stderr
+ )
+ assert orphan not in _recorded(dest), (
+ "an unrecorded notebook the user had edited was adopted into the state\n" + run.stdout
+ )
+
+
+def _head(up: Path) -> str:
+ env = dict(os.environ, GIT_CONFIG_GLOBAL = "/dev/null", GIT_CONFIG_SYSTEM = "/dev/null")
+ out = subprocess.run(
+ ["git", "rev-parse", "HEAD"],
+ cwd = up,
+ check = True,
+ env = env,
+ capture_output = True,
+ text = True,
+ )
+ return out.stdout.strip()
+
+
+def _delete_upstream(up: Path, victim: str) -> None:
+ (up / victim).unlink()
+ env = dict(os.environ, GIT_CONFIG_GLOBAL = "/dev/null", GIT_CONFIG_SYSTEM = "/dev/null")
+ subprocess.run(["git", "add", "-A"], cwd = up, check = True, env = env)
+ subprocess.run(
+ ["git", "-c", "user.name=t", "-c", "user.email=t@t", "commit", "-qm", "del"],
+ cwd = up,
+ check = True,
+ env = env,
+ )
+
+
+@needs_git
+def test_a_kept_removed_notebook_survives_a_failed_state_append(tmp_path: Path):
+ """Every other caller may delete a notebook it could not record, because the clone
+ still holds a copy to re-publish next start. This one may not: upstream DELETED
+ the file, so the copy in $DEST is the last one in existence. Dropping it destroys
+ exactly what UNSLOTH_KEEP_REMOVED_NOTEBOOKS was set to preserve, and no retry
+ recovers it -- not with the option on, not with it off, because by then it is in
+ neither the clone nor the state."""
+ tpl, dest, up = _template(tmp_path), tmp_path / "dest", _upstream(tmp_path)
+ dest.mkdir()
+ _run(tpl, dest, up, refresh = False)
+ _run(tpl, dest, up, refresh = True)
+ victim = f"nb{1:09d}.ipynb"
+ assert victim in _recorded(dest)
+ _delete_upstream(up, victim)
+
+ # The cap has to let the main loop's 499 records through and fail on the removal
+ # loop's single extra append, or the run aborts before ever reaching the branch.
+ # A record costs 67 + len(rel) = 84 B, so the window is 499*84 = 41916 <= cap <
+ # 500*84 = 42000, and 41 KiB = 41984 is the only multiple of 1024 inside it.
+ run = _run(tpl, dest, up, cap_kib = 41, refresh = True, keep_removed = True)
+
+ assert (dest / victim).exists(), (
+ "the last surviving copy of a notebook the user asked to KEEP was deleted "
+ "because its record would not fit\n" + run.stdout + run.stderr
+ )
+ assert not (dest / ".unsloth_sync_commit").exists() or (
+ dest / ".unsloth_sync_commit"
+ ).read_text(encoding = "utf-8").strip() != _head(up), (
+ "the record was lost but the run still counted as a success and stamped the "
+ "marker, so the next start exits early instead of retrying\n" + run.stdout
+ )
+
+
+# ---------------------------------------------------------------------------
+# Section 1b and the populate retry, both driven with the refresh switched off so
+# only the parent's own state writers are in play.
+# ---------------------------------------------------------------------------
+def _big_template(tmp_path: Path, count: int) -> Path:
+ tpl = tmp_path / "tpl"
+ tpl.mkdir()
+ for i in range(1, count + 1):
+ (tpl / f"nb{i:09d}.ipynb").write_text("N", encoding = "utf-8")
+ (tpl / ".unsloth_template_commit").write_text("a" * 40 + "\n", encoding = "utf-8")
+ return tpl
+
+
+@needs_git
+def test_an_abandoned_restore_puts_the_tree_back(tmp_path: Path):
+ """Section 1b restores notebooks that are missing, then rewrites the state. When
+ that rewrite is abandoned the old state is kept, and it describes the tree as it
+ was BEFORE the restores -- so the restored files have to go back too. Leaving them
+ means the next refresh sees baked content where the state holds post-refresh
+ hashes and reads every one as a user edit."""
+ tpl, dest, up = _big_template(tmp_path, NOTEBOOKS), tmp_path / "dest", _upstream(tmp_path)
+ dest.mkdir()
+ _run(tpl, dest, up, refresh = False)
+ before = _recorded(dest)
+ assert len(before) == NOTEBOOKS
+
+ # the LAST 50, so they straddle the point where the appends start failing;
+ # victims processed before it are all restored no matter what the guard does
+ victims = [f"nb{i:09d}.ipynb" for i in range(NOTEBOOKS - 49, NOTEBOOKS + 1)]
+ for name in victims:
+ (dest / name).unlink()
+
+ run = _run(tpl, dest, up, cap_kib = CAP_KIB, refresh = False)
+ assert run.returncode == 0, run.stdout + run.stderr
+ assert "could not be rewritten" in run.stdout, (
+ "the cap did not bite in section 1b; this test proves nothing\n" + run.stdout
+ )
+
+ assert _recorded(dest) == before, "the old state must be kept intact\n" + run.stdout
+ still_there = [n for n in victims if (dest / n).exists()]
+ assert not still_there, (
+ f"{len(still_there)} notebook(s) were restored while the state that describes "
+ f"them was abandoned, so the next refresh reads them as user edits: "
+ f"{still_there[:5]}"
+ )
+
+ # and it must STOP restoring once the rewrite is known to be doomed, rather than
+ # keep touching the tree and rely on the undo to clean up after it
+ restored = (
+ int(run.stdout.split("restored ")[1].split(" ")[0]) if "restored " in run.stdout else 0
+ )
+ assert restored < len(victims), (
+ f"section 1b restored all {restored} notebooks after deciding the state could "
+ f"not be written; the guard is evaluated once instead of per iteration"
+ )
+
+
+@needs_git
+def test_a_lost_merge_record_does_not_publish_the_short_state(tmp_path: Path):
+ """The merge loop is the only source of records for notebooks that exist upstream
+ but not in the baked template. Nothing can re-derive them, so a lost one must
+ abandon the staged state rather than publish it and merely withhold the marker.
+ A failed COPY is different and still publishes, because the next boot re-walks the
+ template."""
+ tpl, dest, up = _big_template(tmp_path, NOTEBOOKS), tmp_path / "dest", _upstream(tmp_path)
+ dest.mkdir()
+ _run(tpl, dest, up, refresh = False)
+
+ # notebooks the refresh had added: present in $DEST and in the state, absent from
+ # the baked template, so only the merge loop can carry their records forward
+ state = dest / ".unsloth_sync_state"
+ extra = [f"up_only_{i:04d}.ipynb" for i in range(100)]
+ import hashlib
+
+ with state.open("a", encoding = "utf-8") as f:
+ for name in extra:
+ (dest / name).write_text("U", encoding = "utf-8")
+ f.write(hashlib.sha256(b"U").hexdigest() + " " + name + "\n")
+ (dest / ".unsloth_sync_partial").write_text("", encoding = "utf-8")
+
+ run = _run(tpl, dest, up, cap_kib = CAP_KIB + 2, refresh = False)
+ assert run.returncode == 0, run.stdout + run.stderr
+
+ survived = _recorded(dest)
+ lost = [n for n in extra if n not in survived]
+ assert not lost, (
+ f"{len(lost)} upstream-only record(s) were dropped and the short state was "
+ f"published anyway; nothing can re-derive them: {lost[:5]}\n" + run.stdout
+ )
diff --git a/tests/python/test_docker_nb_strip_colab_durability.py b/tests/python/test_docker_nb_strip_colab_durability.py
new file mode 100644
index 00000000000..492af69a589
--- /dev/null
+++ b/tests/python/test_docker_nb_strip_colab_durability.py
@@ -0,0 +1,280 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-Present the Unsloth team. See /studio/LICENSE.AGPL-3.0
+
+"""A cleaned notebook must never outlive the record of what it was cleaned to.
+
+The migration published every notebook and then wrote the state once at the end. Lose
+that single write and every cleaned notebook no longer matches its record, so the
+refresh reads a hash mismatch as a user edit, carries the stale record forward and
+stops applying upstream updates to it for good, while the migration prints success and
+exits 0. On the first boot after this ships the migration touches the whole set at
+once, so a docker stop or an ENOSPC anywhere in that window stranded all of them.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import importlib.util
+import json
+import os
+from pathlib import Path
+
+import pytest
+
+REPO_ROOT = Path(__file__).resolve().parents[2]
+STRIP_PATH = REPO_ROOT / "docker" / "unsloth_nb_strip_colab.py"
+
+INTRO = (
+ 'To run this, press "*Runtime*" and press "*Run all*" on a **free** '
+ "Tesla T4 Google Colab instance!\n"
+)
+# json.dumps escapes the quotes in INTRO, so the raw sentence never appears in the file
+# text; this fragment does, and only in the intro.
+MARK = "Tesla T4 Google Colab instance"
+
+
[email protected](scope = "module")
+def strip():
+ assert STRIP_PATH.is_file(), f"missing {STRIP_PATH}"
+ spec = importlib.util.spec_from_file_location("unsloth_nb_strip_durability", STRIP_PATH)
+ mod = importlib.util.module_from_spec(spec)
+ spec.loader.exec_module(mod)
+ return mod
+
+
+def _sha256(path: Path) -> str:
+ return hashlib.sha256(path.read_bytes()).hexdigest()
+
+
+def _notebook(path: Path, tag: str) -> None:
+ path.parent.mkdir(parents = True, exist_ok = True)
+ path.write_text(
+ json.dumps(
+ {
+ "cells": [
+ {"cell_type": "markdown", "source": [INTRO], "metadata": {}},
+ {
+ "cell_type": "code",
+ "source": [f"print({tag!r})\n"],
+ "metadata": {},
+ "outputs": [],
+ "execution_count": None,
+ },
+ ],
+ "metadata": {"widgets": {"stale": True}},
+ "nbformat": 4,
+ "nbformat_minor": 5,
+ }
+ ),
+ encoding = "utf-8",
+ )
+
+
+def tree(tmp_path: Path):
+ dest = tmp_path / "dest"
+ names = [f"nb/n{i}.ipynb" for i in range(4)]
+ lines = []
+ for i, rel in enumerate(names):
+ _notebook(dest / rel, f"cell-{i}")
+ lines.append(f"{_sha256(dest / rel)} {rel}")
+ state = dest / ".unsloth_sync_state"
+ state.write_text("\n".join(lines) + "\n", encoding = "utf-8")
+ return dest, state, names
+
+
+def _state(state: Path) -> dict:
+ out = {}
+ for line in state.read_text(encoding = "utf-8").splitlines():
+ parts = line.split(" ", 1)
+ if len(parts) == 2:
+ out[parts[1]] = parts[0]
+ return out
+
+
+def _orphans(dest: Path, state: Path, names) -> list:
+ """Notebooks on disk whose bytes no longer match what the state file records.
+ Every one of these is permanently frozen from the refresh's point of view."""
+ recorded = _state(state)
+ return [rel for rel in names if recorded.get(rel) != _sha256(dest / rel)]
+
+
+def test_the_migration_records_what_it_published(strip, tree):
+ dest, state, names = tree
+ assert strip.migrate(str(state), str(dest)) == 0
+ assert _orphans(dest, state, names) == []
+ for rel in names:
+ assert MARK not in (dest / rel).read_text(encoding = "utf-8")
+
+
+def test_a_failing_state_write_publishes_nothing(strip, tree, monkeypatch):
+ """The whole point of the ordering: if the record cannot be written, the notebook
+ must not be cleaned either, so the disk still matches and the next start retries."""
+ dest, state, names = tree
+ monkeypatch.setattr(strip, "_write_state", lambda *a, **k: False)
+
+ assert strip.migrate(str(state), str(dest)) == 0
+
+ assert _orphans(dest, state, names) == []
+ for rel in names:
+ assert MARK in (dest / rel).read_text(encoding = "utf-8"), rel
+ assert not list((dest / "nb").glob("*.tmp")), "a staged copy was left behind"
+
+
+def test_a_state_write_that_fails_partway_strands_nothing(strip, tree, monkeypatch):
+ """The realistic shape: the disk fills, or the container is stopped, midway."""
+ dest, state, names = tree
+ real = strip._write_state
+ calls = {"n": 0}
+
+ def _fail_after_two(path, lines):
+ calls["n"] += 1
+ if calls["n"] > 2:
+ return False
+ return real(path, lines)
+
+ monkeypatch.setattr(strip, "_write_state", _fail_after_two)
+
+ assert strip.migrate(str(state), str(dest)) == 0
+
+ assert _orphans(dest, state, names) == []
+ cleaned = [rel for rel in names if MARK not in (dest / rel).read_text(encoding = "utf-8")]
+ assert len(cleaned) == 2, cleaned
+ assert not list((dest / "nb").glob("*.tmp"))
+
+
+def test_the_rest_is_cleaned_on_the_next_start(strip, tree, monkeypatch):
+ dest, state, names = tree
+ real = strip._write_state
+ calls = {"n": 0}
+
+ def _fail_after_two(path, lines):
+ calls["n"] += 1
+ return real(path, lines) if calls["n"] <= 2 else False
+
+ monkeypatch.setattr(strip, "_write_state", _fail_after_two)
+ strip.migrate(str(state), str(dest))
+ monkeypatch.setattr(strip, "_write_state", real)
+
+ assert strip.migrate(str(state), str(dest)) == 0
+
+ assert _orphans(dest, state, names) == []
+ for rel in names:
+ assert MARK not in (dest / rel).read_text(encoding = "utf-8"), rel
+
+
+def test_a_notebook_that_fails_to_publish_gives_its_record_back(strip, tree, monkeypatch):
+ """The inverted window. It is one notebook rather than all of them, and it is
+ undone by rewriting that entry, which is why this ordering is the safe one."""
+ dest, state, names = tree
+ before = dict(_state(state))
+ monkeypatch.setattr(strip, "_publish", lambda tmp, path, prev: strip._unlink(tmp) or False)
+
+ assert strip.migrate(str(state), str(dest)) == 0
+
+ assert _state(state) == before, "a record was left pointing at bytes never published"
+ assert _orphans(dest, state, names) == []
+ assert not list((dest / "nb").glob("*.tmp"))
+
+
+def test_the_state_write_is_fsynced_before_the_rename(strip, tmp_path, monkeypatch):
+ """A rename made visible before its content is durable strands the notebooks the
+ same way a failed write does."""
+ order = []
+ real_fsync = os.fsync
+ real_replace = os.replace
+
+ monkeypatch.setattr(os, "fsync", lambda fd: order.append("fsync") or real_fsync(fd))
+ monkeypatch.setattr(os, "replace", lambda a, b: order.append("replace") or real_replace(a, b))
+
+ target = tmp_path / "state"
+ assert strip._write_state(str(target), ["a b"]) is True
+ assert order == ["fsync", "replace"], order
+ assert target.read_text(encoding = "utf-8") == "a b\n"
+
+
+def test_malformed_and_unmanaged_lines_survive_verbatim(strip, tmp_path):
+ dest = tmp_path / "dest"
+ _notebook(dest / "nb/x.ipynb", "x")
+ state = dest / ".unsloth_sync_state"
+ state.write_text(
+ "not-a-record\n"
+ f"{_sha256(dest / 'nb/x.ipynb')} nb/x.ipynb\n"
+ "deadbeef nb/gone.ipynb\n",
+ encoding = "utf-8",
+ )
+
+ assert strip.migrate(str(state), str(dest)) == 0
+
+ lines = state.read_text(encoding = "utf-8").splitlines()
+ assert lines[0] == "not-a-record"
+ assert lines[2] == "deadbeef nb/gone.ipynb"
+ assert lines[1] == f"{_sha256(dest / 'nb/x.ipynb')} nb/x.ipynb"
+
+
+def test_a_publish_cut_off_after_its_record_is_recovered(strip, tree, monkeypatch):
+ """The window the ordering leaves behind, and the reason it is not the old one.
+
+ Between os.replace on the state file and os.replace on the notebook the record
+ describes the cleaned bytes while the file still holds the pristine ones. Every
+ later run reads that as a user edit and carries the stale record forward, so the
+ notebook stops receiving upstream updates for good. It is one notebook rather than
+ the whole set, and unlike a real edit it can be told apart and finished.
+ """
+ dest, state, names = tree
+
+ def _killed(tmp, path, before):
+ strip._unlink(tmp)
+ raise KeyboardInterrupt # docker stop, between the two renames
+
+ monkeypatch.setattr(strip, "_publish", _killed)
+ with pytest.raises(KeyboardInterrupt):
+ strip.migrate(str(state), str(dest))
+ monkeypatch.undo()
+
+ stranded = _orphans(dest, state, names)
+ assert stranded, "precondition: a record ran ahead of its notebook"
+ for rel in stranded:
+ assert MARK in (dest / rel).read_text(encoding = "utf-8"), rel
+
+ assert strip.migrate(str(state), str(dest)) == 0
+
+ assert _orphans(dest, state, names) == []
+ for rel in names:
+ assert MARK not in (dest / rel).read_text(encoding = "utf-8"), rel
+
+
+def test_a_real_user_edit_is_still_left_alone(strip, tree):
+ """The blast radius. Recovery must not become a licence to rewrite a notebook
+ whose hash stopped matching for the ordinary reason."""
+ dest, state, names = tree
+ rel = names[0]
+ path = dest / rel
+ nb = json.loads(path.read_text(encoding = "utf-8"))
+ nb["cells"].append(
+ {
+ "cell_type": "code",
+ "source": ["print('mine')\n"],
+ "metadata": {},
+ "outputs": [],
+ "execution_count": None,
+ }
+ )
+ path.write_text(json.dumps(nb), encoding = "utf-8")
+ mine = path.read_text(encoding = "utf-8")
+ recorded = _state(state)[rel]
+
+ assert strip.migrate(str(state), str(dest)) == 0
+
+ assert path.read_text(encoding = "utf-8") == mine, "the user's notebook was rewritten"
+ assert _state(state)[rel] == recorded
+
+
+def test_the_recovery_keys_on_reproducing_the_record(strip, tree):
+ """Non-vacuity: cleaning the file has to land on the recorded hash exactly, which
+ only the interrupted publish can do, so nothing else is touched."""
+ dest, state, names = tree
+ path = dest / names[0]
+
+ assert strip._resume(str(path), "0" * 64) is False
+ assert MARK in path.read_text(encoding = "utf-8")
diff --git a/tests/python/test_docker_nb_strip_colab_race.py b/tests/python/test_docker_nb_strip_colab_race.py
new file mode 100644
index 00000000000..a9393967e42
--- /dev/null
+++ b/tests/python/test_docker_nb_strip_colab_race.py
@@ -0,0 +1,221 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-Present the Unsloth team. See /studio/LICENSE.AGPL-3.0
+
+"""The Colab-intro cleanup must not overwrite a save it did not see.
+
+`strip_notebook` read the file, serialised the cleaned copy and then `os.replace`d it
+unconditionally, while JupyterLab was already serving $DEST. A save landing in that
+window was destroyed, and `migrate` then recorded the cleaned hash, so the state
+machine treats the notebook as pristine forever after.
+"""
+
+from __future__ import annotations
+
+import copy
+import importlib.util
+import json
+from pathlib import Path
+
+import pytest
+
+REPO_ROOT = Path(__file__).resolve().parents[2]
+STRIP_PATH = REPO_ROOT / "docker" / "unsloth_nb_strip_colab.py"
+
+INTRO = 'To run this, press "*Runtime*" and press "*Run all*" on a **free** Tesla T4 Google Colab instance!\n'
+
+
[email protected](scope = "module")
+def strip():
+ assert STRIP_PATH.is_file(), f"missing {STRIP_PATH}"
+ spec = importlib.util.spec_from_file_location("unsloth_nb_strip_race", STRIP_PATH)
+ mod = importlib.util.module_from_spec(spec)
+ spec.loader.exec_module(mod)
+ return mod
+
+
+def notebook(*sources):
+ return {
+ "cells": [
+ {"cell_type": "markdown", "metadata": {}, "source": list(src)} for src in sources
+ ],
+ "metadata": {},
+ "nbformat": 4,
+ "nbformat_minor": 5,
+ }
+
+
+def write(path: Path, nb) -> None:
+ path.write_text(json.dumps(nb, indent = 1, ensure_ascii = False) + "\n", encoding = "utf-8")
+
+
+def racing(strip, tmp_path: Path):
+ real_dump = strip.json.dump
+ state = {"save": None, "path": None, "fired": 0}
+
+ def dump(obj, fp, *args, **kwargs):
+ out = real_dump(obj, fp, *args, **kwargs)
+ if state["save"] is not None and state["fired"] == 0:
+ state["fired"] = 1
+ Path(state["path"]).write_text(state["save"], encoding = "utf-8") # Ctrl+S
+ return out
+
+ strip.json.dump = dump
+ try:
+ yield state
+ finally:
+ strip.json.dump = real_dump
+
+
+def test_a_save_during_the_cleanup_is_not_overwritten(strip, racing, tmp_path: Path):
+ path = tmp_path / "Llama.ipynb"
+ write(path, notebook([INTRO, "\n", "# Llama\n"]))
+
+ edited = notebook([INTRO, "\n", "# Llama\n", "\n", "my own notes, saved from JupyterLab\n"])
+ racing["save"] = json.dumps(edited, indent = 1, ensure_ascii = False) + "\n"
+ racing["path"] = str(path)
+
+ strip.strip_notebook(str(path))
+
+ on_disk = json.loads(path.read_text(encoding = "utf-8"))
+ assert on_disk == edited, (
+ "the user's save landed after strip_notebook read the file and was "
+ "overwritten by the cleaned copy of the OLD content; the sync contract "
+ "is that user edits always win"
+ )
+
+
+def test_the_recorded_hash_still_matches_the_file_after_a_racing_save(
+ strip, racing, tmp_path: Path
+):
+ # migrate() rewrites STATE with the post-strip hash, so a clobbered save is also
+ # recorded as pristine and every later refresh overwrites it again
+ dest = tmp_path / "unsloth-notebooks"
+ dest.mkdir()
+ path = dest / "Llama.ipynb"
+ write(path, notebook([INTRO, "\n", "# Llama\n"]))
+ before = strip._sha256(str(path))
+ state = tmp_path / ".unsloth_sync_state"
+ state.write_text(f"{before} Llama.ipynb\n", encoding = "utf-8")
+
+ edited = notebook([INTRO, "\n", "# Llama\n", "\n", "my own notes\n"])
+ racing["save"] = json.dumps(edited, indent = 1, ensure_ascii = False) + "\n"
+ racing["path"] = str(path)
+
+ strip.migrate(str(state), str(dest))
+
+ recorded = state.read_text(encoding = "utf-8").split(" ", 1)[0]
+ on_disk = strip._sha256(str(path))
+ assert json.loads(path.read_text(encoding = "utf-8")) == edited
+ assert recorded != on_disk, (
+ "a file the user saved during the cleanup must NOT end up recorded as "
+ "managed-and-pristine, or the next refresh overwrites it too"
+ )
+
+
+def test_the_normal_no_race_cleanup_still_strips_and_rewrites(strip, tmp_path: Path):
+ path = tmp_path / "Llama.ipynb"
+ original = notebook([INTRO, "\n", "# Llama\n"])
+ write(path, copy.deepcopy(original))
+
+ assert strip.strip_notebook(str(path)) is True
+ cleaned = json.loads(path.read_text(encoding = "utf-8"))
+ assert cleaned["cells"][0]["source"] == ["# Llama\n"]
+ assert strip.strip_notebook(str(path)) is False # idempotent
+
+
+def racing_after_replace(strip, tmp_path: Path):
+ """The OTHER window: after os.replace published, before migrate() hashes."""
+ real_replace = strip.os.replace
+ state = {"save": None, "path": None, "fired": 0}
+
+ def replace(src, dst, *args, **kwargs):
+ out = real_replace(src, dst, *args, **kwargs)
+ if state["save"] is not None and state["fired"] == 0 and str(dst) == state["path"]:
+ state["fired"] = 1
+ Path(state["path"]).write_text(state["save"], encoding = "utf-8") # Ctrl+S
+ return out
+
+ strip.os.replace = replace
+ try:
+ yield state
+ finally:
+ strip.os.replace = real_replace
+
+
+def test_a_save_landing_after_the_replace_is_not_recorded_as_pristine(
+ strip, racing_after_replace, tmp_path: Path
+):
+ # rename(2) is atomic, but migrate()'s re-read of the published file is not
+ dest = tmp_path / "unsloth-notebooks"
+ dest.mkdir()
+ path = dest / "Llama.ipynb"
+ write(path, notebook([INTRO, "\n", "# Llama\n"]))
+ before = strip._sha256(str(path))
+ state = tmp_path / ".unsloth_sync_state"
+ state.write_text(f"{before} Llama.ipynb\n", encoding = "utf-8")
+
+ edited = notebook([INTRO, "\n", "# Llama\n", "\n", "saved right after the replace\n"])
+ racing_after_replace["save"] = json.dumps(edited, indent = 1, ensure_ascii = False) + "\n"
+ racing_after_replace["path"] = str(path)
+
+ strip.migrate(str(state), str(dest))
+
+ assert (
+ racing_after_replace["fired"] == 1
+ ), "the window was never exercised; this test would pass vacuously"
+ recorded = state.read_text(encoding = "utf-8").split(" ", 1)[0]
+ assert json.loads(path.read_text(encoding = "utf-8")) == edited
+ assert recorded != strip._sha256(
+ str(path)
+ ), "the user's own save was recorded as the cleaned, sync-owned version"
+
+
+def test_the_recorded_hash_is_the_cleaned_copy_when_nobody_races(strip, tmp_path: Path):
+ # over-reach guard: STATE must adopt the cleaned hash, or every boot re-strips it
+ dest = tmp_path / "unsloth-notebooks"
+ dest.mkdir()
+ path = dest / "Llama.ipynb"
+ write(path, notebook([INTRO, "\n", "# Llama\n"]))
+ state = tmp_path / ".unsloth_sync_state"
+ state.write_text(f"{strip._sha256(str(path))} Llama.ipynb\n", encoding = "utf-8")
+
+ strip.migrate(str(state), str(dest))
+
+ recorded = state.read_text(encoding = "utf-8").split(" ", 1)[0]
+ assert recorded == strip._sha256(str(path))
+
+
+def test_cleanup_keeps_the_notebooks_owner_and_mode(strip, tmp_path: Path):
+ """A bind-mounted notebook matching the baked template is managed WITHOUT being
+ copied, so the host user keeps owning it -- and os.replace swaps the directory
+ entry, so a root-written staging file would hand it back root-owned."""
+ import os
+ import stat as _stat
+
+ nb_path = tmp_path / "Managed.ipynb"
+ nb_path.write_text(
+ json.dumps(
+ {
+ "cells": [
+ {
+ "cell_type": "markdown",
+ "source": ["To run this, press *Runtime* > Run all\n"],
+ }
+ ],
+ "metadata": {},
+ "nbformat": 4,
+ "nbformat_minor": 5,
+ }
+ ),
+ encoding = "utf-8",
+ )
+ os.chmod(nb_path, 0o640)
+ before = _stat.S_IMODE(os.stat(nb_path).st_mode)
+ assert before == 0o640
+
+ assert strip.strip_notebook(str(nb_path)) is True
+ after = _stat.S_IMODE(os.stat(nb_path).st_mode)
+ assert after == before, f"cleanup changed the mode {oct(before)} -> {oct(after)}"
+ assert "To run this" not in nb_path.read_text(encoding = "utf-8")
diff --git a/tests/python/test_docker_nb_strip_colab_scope.py b/tests/python/test_docker_nb_strip_colab_scope.py
new file mode 100644
index 00000000000..6b472b73c47
--- /dev/null
+++ b/tests/python/test_docker_nb_strip_colab_scope.py
@@ -0,0 +1,135 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-Present the Unsloth team. See /studio/LICENSE.AGPL-3.0
+
+"""Regression guard for the Colab-intro strip in the Unsloth Docker image.
+
+cells[0] alone misses two shapes: the badge in cells[0] with the sentence in cells[1],
+and the sentence wrapped in a single-line HTML comment.
+
+The widening has to stay narrow: the scan stops at the first non-markdown cell so it
+never reaches prose between code cells, it stays idempotent, and it must leave
+unsloth_nb_content_sig's middle digest alone or the boot refresh re-strips forever.
+"""
+
+from __future__ import annotations
+
+import copy
+import importlib.util
+import json
+from pathlib import Path
+
+import pytest
+
+REPO_ROOT = Path(__file__).resolve().parents[2]
+STRIP_PATH = REPO_ROOT / "docker" / "unsloth_nb_strip_colab.py"
+
+INTRO = 'To run this, press "*Runtime*" and press "*Run all*" on a **free** Tesla T4 Google Colab instance!\n'
+BADGE = '<a href="https://colab.research.google.com/github/unslothai/notebooks/blob/main/nb/X.ipynb">badge</a>\n'
+
+
[email protected](scope = "module")
+def strip():
+ assert STRIP_PATH.is_file(), f"missing {STRIP_PATH}"
+ spec = importlib.util.spec_from_file_location("unsloth_nb_strip_under_test", STRIP_PATH)
+ mod = importlib.util.module_from_spec(spec)
+ spec.loader.exec_module(mod)
+ return mod
+
+
+def md(*lines):
+ return {"cell_type": "markdown", "metadata": {}, "source": list(lines)}
+
+
+def code(src):
+ return {
+ "cell_type": "code",
+ "metadata": {},
+ "execution_count": None,
+ "outputs": [],
+ "source": [src],
+ }
+
+
+def nb(*cells):
+ return {"cells": list(cells), "metadata": {}, "nbformat": 4, "nbformat_minor": 5}
+
+
+def text(cell):
+ src = cell.get("source", "")
+ return "".join(src) if isinstance(src, list) else src
+
+
+def has_intro(notebook):
+ return any("to run this, press" in text(c).lower() for c in notebook["cells"])
+
+
+def test_intro_in_cell_zero_is_still_stripped(strip):
+ doc = nb(md(INTRO, "\n", BADGE), code("print(1)"))
+ assert strip._strip_intro(doc) is True
+ assert not has_intro(doc)
+ assert BADGE in text(doc["cells"][0]), "the badge row must survive the strip"
+
+
+def test_intro_in_cell_one_behind_the_badge_is_stripped(strip):
+ doc = nb(md(BADGE), md(INTRO, "\n", "You will learn how to do data prep.\n"), code("print(1)"))
+ assert strip._strip_intro(doc) is True
+ assert not has_intro(doc)
+ assert "You will learn how to do data prep.\n" in text(doc["cells"][1])
+
+
+def test_intro_inside_a_single_line_html_comment_is_stripped(strip):
+ commented = "<!-- " + INTRO.rstrip("\n") + " -->\n"
+ doc = nb(md(commented, '<div class="align-center">\n'), code("print(1)"))
+ assert strip._strip_intro(doc) is True
+ assert not has_intro(doc)
+ assert '<div class="align-center">\n' in text(doc["cells"][0])
+
+
+def test_multi_line_html_comment_is_left_alone(strip):
+ # half-removing a multi-line comment leaves a `<!--` that swallows the cell
+ doc = nb(md("<!-- " + INTRO, "still inside the comment\n", "-->\n"), code("print(1)"))
+ assert strip._strip_intro(doc) is False
+ assert has_intro(doc)
+
+
+def test_strip_stops_at_the_first_code_cell(strip):
+ # a markdown cell AFTER code is prose, not the header block
+ later = md("Explanation.\n", INTRO)
+ doc = nb(md(BADGE), code("print(1)"), later)
+ assert strip._strip_intro(doc) is False
+ assert text(doc["cells"][2]) == "Explanation.\n" + INTRO
+
+
+def test_strip_is_idempotent(strip):
+ doc = nb(md(BADGE), md(INTRO, "\n", "rest\n"), code("print(1)"))
+ assert strip._strip_intro(doc) is True
+ once = copy.deepcopy(doc)
+ assert strip._strip_intro(doc) is False, "a second boot must be a no-op"
+ assert doc == once
+
+
+def test_a_notebook_without_the_intro_is_untouched(strip):
+ doc = nb(md(BADGE, "# Title\n"), code("print(1)"))
+ before = copy.deepcopy(doc)
+ assert strip._strip_intro(doc) is False
+ assert doc == before
+
+
+def test_source_given_as_a_string_is_handled(strip):
+ doc = nb(
+ {"cell_type": "markdown", "metadata": {}, "source": BADGE},
+ {"cell_type": "markdown", "metadata": {}, "source": INTRO + "\nrest\n"},
+ code("print(1)"),
+ )
+ assert strip._strip_intro(doc) is True
+ assert not has_intro(doc)
+ assert isinstance(doc["cells"][1]["source"], str)
+
+
+def test_end_to_end_write_back_is_valid_json(strip, tmp_path):
+ p = tmp_path / "N.ipynb"
+ p.write_text(json.dumps(nb(md(BADGE), md(INTRO, "\n", "rest\n"), code("print(1)"))))
+ assert strip.strip_notebook(str(p)) is True
+ reloaded = json.loads(p.read_text())
+ assert not has_intro(reloaded)
+ assert strip.strip_notebook(str(p)) is False
diff --git a/tests/python/test_docker_nb_sync_publish_ownership.py b/tests/python/test_docker_nb_sync_publish_ownership.py
new file mode 100644
index 00000000000..d801669208a
--- /dev/null
+++ b/tests/python/test_docker_nb_sync_publish_ownership.py
@@ -0,0 +1,492 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-Present the Unsloth team. See /studio/LICENSE.AGPL-3.0
+
+"""The GitHub refresh must not take a bind-mounted notebook away from its owner.
+
+rename(2) swaps the DIRECTORY ENTRY, so the staged inode's root:root 0644 becomes the
+published file's identity -- and a host-owned file really can be under sync
+management, since first-boot populate adopts one matching the baked template WITHOUT
+copying. `cp -a` onto an existing inode chowns it too; plain `cp` does not.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import stat
+import subprocess
+from pathlib import Path
+
+import pytest
+
+REPO_ROOT = Path(__file__).resolve().parents[2]
+SYNC = REPO_ROOT / "docker" / "unsloth_sync_notebooks.sh"
+
+pytestmark = pytest.mark.skipif(
+ shutil.which("bash") is None
+ or shutil.which("git") is None
+ or shutil.which("sha256sum") is None,
+ reason = "needs bash, git and sha256sum",
+)
+
+REL = "nb/Llama.ipynb"
+HOST_MODE = 0o640
+
+
+def _nb(code: str) -> str:
+ return json.dumps(
+ {
+ "cells": [
+ {"cell_type": "code", "source": ["!pip install unsloth\n"], "metadata": {}},
+ {"cell_type": "code", "source": [code], "metadata": {}},
+ ],
+ "metadata": {},
+ "nbformat": 4,
+ "nbformat_minor": 5,
+ }
+ )
+
+
+V1 = _nb("model = FastLanguageModel.from_pretrained('llama-3')\n")
+V2 = _nb("model = FastLanguageModel.from_pretrained('llama-4')\n")
+
+
+def _git(*args, cwd: Path):
+ subprocess.run(
+ ["git", "-c", "user.email=t@t", "-c", "user.name=t", *args],
+ cwd = str(cwd),
+ check = True,
+ capture_output = True,
+ )
+
+
+def _world(tmp_path: Path) -> tuple[Path, Path, Path]:
+ template = tmp_path / "template"
+ (template / "nb").mkdir(parents = True)
+ (template / REL).write_text(V1, encoding = "utf-8")
+ (template / ".unsloth_template_commit").write_text("old\n", encoding = "utf-8")
+
+ dest = tmp_path / "dest"
+ (dest / "nb").mkdir(parents = True)
+ (dest / REL).write_text(V1, encoding = "utf-8")
+ os.chmod(dest / REL, HOST_MODE)
+
+ remote = tmp_path / "remote"
+ (remote / "nb").mkdir(parents = True)
+ (remote / REL).write_text(V2, encoding = "utf-8")
+ _git("init", "-q", "-b", "main", cwd = remote)
+ _git("add", "-A", cwd = remote)
+ _git("commit", "-qm", "bump", cwd = remote)
+ return template, dest, remote
+
+
+def _run(
+ tmp_path: Path,
+ template: Path,
+ dest: Path,
+ remote: Path,
+ *,
+ path_prefix = None,
+):
+ env = dict(os.environ)
+ env.update(
+ UNSLOTH_NOTEBOOKS_TEMPLATE = str(template),
+ UNSLOTH_NOTEBOOKS_DIR = str(dest),
+ UNSLOTH_NOTEBOOKS_REPO = str(remote),
+ UNSLOTH_NB_REFRESH_CHILD = "1",
+ UNSLOTH_SKIP_NOTEBOOK_VIEW = "1",
+ UNSLOTH_KEEP_COLAB_INTRO = "1",
+ )
+ if path_prefix is not None:
+ env["PATH"] = str(path_prefix) + os.pathsep + env["PATH"]
+ return subprocess.run(
+ ["bash", str(SYNC)],
+ capture_output = True,
+ text = True,
+ env = env,
+ timeout = 120,
+ )
+
+
+def _assert_refreshed_and_still_the_owners(dest: Path, res):
+ live = dest / REL
+ assert (
+ live.read_text(encoding = "utf-8") == V2
+ ), f"the upstream change must reach the container; stdout={res.stdout!r} stderr={res.stderr!r}"
+ mode = stat.S_IMODE(live.stat().st_mode)
+ assert mode == HOST_MODE, (
+ f"the published notebook kept mode 0o{mode:o}, not the host user's "
+ f"0o{HOST_MODE:o}: the refresh replaced their file's identity with the "
+ f"freshly cloned copy's"
+ )
+
+
+def test_the_refresh_keeps_the_destinations_metadata(tmp_path: Path):
+ template, dest, remote = _world(tmp_path)
+ res = _run(tmp_path, template, dest, remote)
+ _assert_refreshed_and_still_the_owners(dest, res)
+
+
+def test_the_ebusy_fallback_keeps_the_destinations_metadata(tmp_path: Path):
+ # an `mv` that refuses only the staging rename models a single-FILE bind mount
+ binp = tmp_path / "bin"
+ binp.mkdir()
+ stub = binp / "mv"
+ stub.write_text(
+ '#!/usr/bin/env bash\ncase "$*" in *.unsloth_nb_new.*) exit 1 ;; esac\nexec /bin/mv "$@"\n',
+ encoding = "utf-8",
+ )
+ stub.chmod(0o755)
+
+ template, dest, remote = _world(tmp_path)
+ res = _run(tmp_path, template, dest, remote, path_prefix = binp)
+ _assert_refreshed_and_still_the_owners(dest, res)
+
+
+def test_the_owner_half_is_applied_too(tmp_path: Path):
+ src = SYNC.read_text(encoding = "utf-8")
+ block = src[src.index("stage_metadata() {") : src.index("cp_keep_meta() {")]
+ assert 'chmod --reference="$2" "$1"' in block
+ assert 'chown --reference="$2" "$1"' in block
+ assert block.count("|| true") == 2, (
+ "both must be best effort: a filesystem that refuses them must not cost "
+ "the user their refresh"
+ )
+ # This used to assert `[ -e "$2" ] || return 0`, i.e. that a brand-new
+ # notebook was left alone. That was the defect: with nothing to inherit
+ # from, the early return published the clone's root:root 0644 and the host
+ # user could not edit a notebook upstream had just added. It now falls
+ # through to own_like_dir instead.
+ assert 'if [ ! -e "$2" ]; then' in block
+ assert (
+ "own_like_dir" in block
+ ), "a brand-new notebook must take the owner of the directory it lands in"
+
+
+ os.geteuid() == 0,
+ reason = "root holds CAP_DAC_OVERRIDE, so chmod 0500 does not stop the write",
+)
+def test_a_failed_publish_does_not_claim_the_commit_is_synced(tmp_path: Path):
+ """A publish that cannot be written must stay retryable: stamping $SYNCED anyway
+ short-circuits the next boot on `remote == last`. Skipped under root, which
+ bypasses the chmod (CAP_DAC_OVERRIDE)."""
+ template, dest, remote = _world(tmp_path)
+ nb_dir = dest / "nb"
+ os.chmod(nb_dir, 0o500) # publish into nb/ now fails, DEST root stays writable
+ try:
+ res = _run(tmp_path, template, dest, remote)
+ finally:
+ os.chmod(nb_dir, 0o700)
+
+ head = subprocess.run(
+ ["git", "rev-parse", "HEAD"],
+ cwd = remote,
+ capture_output = True,
+ text = True,
+ check = True,
+ ).stdout.strip()
+ synced = dest / ".unsloth_sync_commit"
+ marker = synced.read_text(encoding = "utf-8").strip() if synced.exists() else ""
+ assert marker != head, (
+ "the sync marker was advanced to the upstream commit even though the "
+ "publish failed, so the next start short-circuits on remote == last and "
+ f"never retries; marker={marker!r} stdout={res.stdout!r} "
+ f"stderr={res.stderr!r}"
+ )
+ assert (dest / REL).read_text(encoding = "utf-8") == V1
+
+
+ os.geteuid() == 0,
+ reason = "root holds CAP_DAC_OVERRIDE, so a read-only marker does not stop the write",
+)
+def test_a_marker_the_user_cannot_truncate_is_still_advanced(tmp_path: Path):
+ """A root boot leaves the marker root-owned 0644 inside a directory the host user
+ owns. A later --user boot renames the state into place fine but `> marker` fails
+ on the truncate, so the refresh reported success while the marker stayed behind
+ and every start after that re-synced every notebook. Modelled here with a
+ read-only marker, which fails the same open(O_TRUNC)."""
+ template, dest, remote = _world(tmp_path)
+ synced = dest / ".unsloth_sync_commit"
+ synced.write_text("stale\n", encoding = "utf-8")
+ os.chmod(synced, 0o444)
+ try:
+ res = _run(tmp_path, template, dest, remote)
+ finally:
+ os.chmod(synced, 0o644)
+
+ head = subprocess.run(
+ ["git", "rev-parse", "HEAD"],
+ cwd = remote,
+ capture_output = True,
+ text = True,
+ check = True,
+ ).stdout.strip()
+ assert res.returncode == 0, res.stderr
+ assert (dest / REL).read_text(encoding = "utf-8") == V2
+ assert synced.read_text(encoding = "utf-8").strip() == head, (
+ "the refresh published every notebook but left the marker at the old commit, "
+ "so every later start re-syncs the whole tree; "
+ f"stdout={res.stdout!r} stderr={res.stderr!r}"
+ )
+ assert not (dest / ".unsloth_sync_commit.tmp").exists()
+ assert "Permission denied" not in res.stderr
+
+
+# mkdir(2) gives a new DIRECTORY the caller's uid and only setgid carries down, so a
+# category folder upstream adds lands root:root and the user cannot write into it
+
+SYNC_SH = REPO_ROOT / "docker" / "unsloth_sync_notebooks.sh"
+
+
+def _function_block(source: str, name: str) -> str:
+ start = source.index(f"{name}() {{")
+ end = source.index("\n}\n", start) + len("\n}\n")
+ return source[start:end]
+
+
+def _drive_mkdir_keep_owner(tmp_path: Path, target: Path) -> list:
+ source = SYNC_SH.read_text(encoding = "utf-8")
+ block = _function_block(source, "mkdir_keep_owner")
+
+ bin_dir = tmp_path / "bin"
+ bin_dir.mkdir(exist_ok = True)
+ log = tmp_path / "chown.log"
+ shim = bin_dir / "chown"
+ shim.write_text(
+ f'#!/usr/bin/env bash\nprintf "%s\\n" "$*" >> "{log}"\nexit 0\n',
+ encoding = "utf-8",
+ )
+ shim.chmod(0o755)
+
+ driver = tmp_path / "driver.sh"
+ driver.write_text(
+ "#!/usr/bin/env bash\nset -u\n" + block + f'\nmkdir_keep_owner "{target}"\n',
+ encoding = "utf-8",
+ )
+ result = subprocess.run(
+ ["bash", str(driver)],
+ capture_output = True,
+ text = True,
+ timeout = 120,
+ env = dict(os.environ, PATH = f"{bin_dir}{os.pathsep}" + os.environ["PATH"]),
+ )
+ assert result.returncode == 0, result.stdout + result.stderr
+ if not log.exists():
+ return []
+ return [line for line in log.read_text(encoding = "utf-8").splitlines() if line]
+
+
[email protected](shutil.which("bash") is None, reason = "needs bash")
+def test_every_created_notebook_directory_is_chowned_to_its_nearest_ancestor(tmp_path: Path):
+ anchor = tmp_path / "notebooks"
+ anchor.mkdir()
+ target = anchor / "AMD" / "vision"
+
+ calls = _drive_mkdir_keep_owner(tmp_path, target)
+
+ assert target.is_dir(), "the directory still has to be created"
+ assert calls == [
+ f"--reference={anchor} {anchor / 'AMD'}",
+ f"--reference={anchor} {target}",
+ ], f"both created levels must be fixed, outermost first: {calls}"
+
+
[email protected](shutil.which("bash") is None, reason = "needs bash")
+def test_an_existing_notebook_directory_is_left_alone(tmp_path: Path):
+ existing = tmp_path / "notebooks"
+ existing.mkdir()
+ assert _drive_mkdir_keep_owner(tmp_path, existing) == []
+
+
+def test_every_directory_creating_site_routes_through_the_helper():
+ """Four sites create $DEST or a directory inside it; none may call bare mkdir."""
+ source = SYNC_SH.read_text(encoding = "utf-8")
+ # The WHOLE file, not just what follows the helper: `mkdir -p "$DEST"` sat above
+ # it, and the root it created as root:root is the anchor every other site
+ # inherits from, so scoping this scan to the tail is what let that one through.
+ stray = [
+ line.strip() for line in source.splitlines() if "mkdir -p" in line and '"$DEST' in line
+ ]
+ assert not stray, f"these still create a directory as root inside $DEST: {stray}"
+ body = source[source.index("mkdir_keep_owner() {") :]
+ body = body[body.index("\n}\n") :] # everything after the helper itself
+ # Real invocations only: counting the substring also counted the word where a
+ # comment merely names the helper, so prose could satisfy or break this.
+ calls = [
+ line.strip() for line in body.splitlines() if line.strip().startswith("mkdir_keep_owner ")
+ ]
+ assert len(calls) == 4, (
+ "expected the notebook root, populate, restore and publish to route "
+ f"through the helper: {calls}"
+ )
+
+
+# --- a notebook that has no destination to inherit from -------------------------
+# stage_metadata returned early when $2 did not exist, so a notebook upstream had
+# just added kept the clone's root:root 0644 through the rename, and the two
+# `cp -a` copies in populate/restore kept the TEMPLATE's. unsloth_run.py's
+# _stage_metadata has had a new-file branch for this since the earlier ownership
+# fix; the shell twin did not.
+
+
+def _drive_sh(tmp_path: Path, snippet: str, *funcs: str) -> list:
+ """Run shipped shell functions with `chown` replaced by a recorder on PATH."""
+ source = SYNC_SH.read_text(encoding = "utf-8")
+ blocks = "\n".join(_function_block(source, name) for name in funcs)
+
+ bin_dir = tmp_path / "bin"
+ bin_dir.mkdir(exist_ok = True)
+ log = tmp_path / "chown.log"
+ shim = bin_dir / "chown"
+ shim.write_text(
+ f'#!/usr/bin/env bash\nprintf "%s\\n" "$*" >> "{log}"\nexit 0\n',
+ encoding = "utf-8",
+ )
+ shim.chmod(0o755)
+
+ driver = tmp_path / "driver.sh"
+ driver.write_text(
+ "#!/usr/bin/env bash\nset -u\numask 022\n" + blocks + "\n" + snippet, encoding = "utf-8"
+ )
+ result = subprocess.run(
+ ["bash", str(driver)],
+ capture_output = True,
+ text = True,
+ timeout = 120,
+ env = dict(os.environ, PATH = f"{bin_dir}{os.pathsep}" + os.environ["PATH"]),
+ )
+ assert result.returncode == 0, result.stdout + result.stderr
+ if not log.exists():
+ return []
+ return [line for line in log.read_text(encoding = "utf-8").splitlines() if line]
+
+
[email protected](shutil.which("bash") is None, reason = "needs bash")
+def test_a_brand_new_notebook_gets_the_destination_directorys_owner(tmp_path: Path):
+ dest_dir = tmp_path / "nb"
+ dest_dir.mkdir()
+ staged = dest_dir / ".unsloth_nb_new.1"
+ staged.write_text("{}", encoding = "utf-8")
+ os.chmod(staged, 0o600) # what the clone / mkstemp hands over
+
+ calls = _drive_sh(
+ tmp_path,
+ f'stage_metadata "{staged}" "{dest_dir / "new.ipynb"}"\n',
+ "own_like_dir",
+ "stage_metadata",
+ )
+
+ assert calls == [
+ f"--reference={dest_dir} {staged}"
+ ], f"a new notebook must take the owner of the directory it lands in: {calls}"
+ # 0666 & ~022, the mode a plain write would have produced.
+ assert stat.S_IMODE(os.stat(staged).st_mode) == 0o644, oct(
+ stat.S_IMODE(os.stat(staged).st_mode)
+ )
+
+
[email protected](shutil.which("bash") is None, reason = "needs bash")
+def test_an_existing_notebook_still_inherits_from_the_file_not_the_directory(tmp_path: Path):
+ dest_dir = tmp_path / "nb"
+ dest_dir.mkdir()
+ live = dest_dir / "x.ipynb"
+ live.write_text("old", encoding = "utf-8")
+ staged = dest_dir / ".unsloth_nb_new.1"
+ staged.write_text("{}", encoding = "utf-8")
+
+ calls = _drive_sh(
+ tmp_path,
+ f'stage_metadata "{staged}" "{live}"\n',
+ "own_like_dir",
+ "stage_metadata",
+ )
+
+ assert calls == [f"--reference={live} {staged}"], (
+ "the existing-destination branch must keep copying from the FILE, which "
+ "is what preserves a mode the user chose themselves"
+ )
+
+
+def test_both_template_copies_hand_the_file_to_the_host_user():
+ """The sibling guard: populate and restore both `cp -a` from the template,
+ which preserves its root:root 0644, so each needs the ownership fix. Fixing
+ the publish path alone is how this class of bug keeps coming back."""
+ source = SYNC_SH.read_text(encoding = "utf-8")
+ copies = [
+ i
+ for i, line in enumerate(source.splitlines())
+ if 'cp -a "$TEMPLATE/$rel" "$DEST/$rel"' in line
+ ]
+ assert len(copies) == 2, f"expected the populate and restore copies, got {copies}"
+ lines = source.splitlines()
+ for i in copies:
+ window = "\n".join(lines[i : i + 4])
+ assert (
+ "own_like_dir" in window
+ ), f"the copy at line {i + 1} publishes the template's root:root mode"
+
+
+# --- the notebook root itself ---------------------------------------------------
+# `mkdir -p "$DEST"` ran as root before any helper was involved, so on first boot
+# under a host-owned bind mount (UNSLOTH_NOTEBOOKS_DIR=/workspace/host/notebooks,
+# with -v $PWD:/workspace/host) the notebook root landed root:root. Every later
+# mkdir_keep_owner anchors on the NEAREST EXISTING ancestor and own_like_dir copies
+# the owner of the directory a file lands in, so that one root:root directory is
+# then inherited by every category folder and every notebook underneath it, and the
+# host user cannot edit or delete their own notebooks. unsloth_run.py's
+# _makedirs_as_host has always chowned the leaf it creates; the shell twin did not.
+
+
[email protected](shutil.which("bash") is None, reason = "needs bash")
+def test_the_notebook_root_is_created_with_its_ancestors_owner(tmp_path: Path):
+ template = tmp_path / "template"
+ (template / "nb").mkdir(parents = True)
+ (template / REL).write_text(V1, encoding = "utf-8")
+ (template / ".unsloth_template_commit").write_text("old\n", encoding = "utf-8")
+
+ host = tmp_path / "host" # the bind mount, owned by the host user
+ host.mkdir()
+ dest = host / "notebooks" # first boot: does not exist yet
+
+ bin_dir = tmp_path / "bin"
+ bin_dir.mkdir()
+ log = tmp_path / "chown.log"
+ shim = bin_dir / "chown"
+ shim.write_text(
+ f'#!/usr/bin/env bash\nprintf "%s\\n" "$*" >> "{log}"\nexit 0\n',
+ encoding = "utf-8",
+ )
+ shim.chmod(0o755)
+
+ env = dict(os.environ)
+ env.update(
+ UNSLOTH_NOTEBOOKS_TEMPLATE = str(template),
+ UNSLOTH_NOTEBOOKS_DIR = str(dest),
+ UNSLOTH_SKIP_NOTEBOOK_REFRESH = "1",
+ UNSLOTH_SKIP_NOTEBOOK_VIEW = "1",
+ UNSLOTH_KEEP_COLAB_INTRO = "1",
+ PATH = f"{bin_dir}{os.pathsep}" + os.environ["PATH"],
+ )
+ res = subprocess.run(
+ ["bash", str(SYNC)],
+ capture_output = True,
+ text = True,
+ env = env,
+ timeout = 120,
+ )
+
+ assert (
+ dest / REL
+ ).is_file(), f"populate must still run; stdout={res.stdout!r} stderr={res.stderr!r}"
+ calls = [
+ line
+ for line in (log.read_text(encoding = "utf-8").splitlines() if log.exists() else [])
+ if line
+ ]
+ assert f"--reference={host} {dest}" in calls, (
+ "the notebook root was created as root:root, so every directory and "
+ f"notebook under it inherits root ownership from it: {calls}"
+ )
diff --git a/tests/python/test_docker_nb_sync_race.py b/tests/python/test_docker_nb_sync_race.py
new file mode 100644
index 00000000000..aeb4339caf9
--- /dev/null
+++ b/tests/python/test_docker_nb_sync_race.py
@@ -0,0 +1,368 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-Present the Unsloth team. See /studio/LICENSE.AGPL-3.0
+
+"""Regression guard for the notebook-sync race in the Unsloth Docker image.
+
+The parent's `trap finalize EXIT` ran while the detached refresh child was copying
+into the same tree, and the lost writes were permanent: a notebook copied while the
+parent hashed it got a recorded hash that no longer matched, so every later boot read
+it as user-edited and skipped it.
+
+The refresh stays detached and the ORDERING is fixed instead.
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+import pytest
+
+REPO_ROOT = Path(__file__).resolve().parents[2]
+SYNC = REPO_ROOT / "docker" / "unsloth_sync_notebooks.sh"
+
+
[email protected](scope = "module")
+def sync() -> str:
+ assert SYNC.is_file(), f"missing {SYNC}"
+ return SYNC.read_text(encoding = "utf-8")
+
+
+def test_the_refresh_is_still_detached(sync: str):
+ # a synchronous refresh would pass every other test here and regress boot time
+ assert re.search(
+ r'UNSLOTH_NB_REFRESH_CHILD=1 "\$0" >/dev/null 2>&1 &', sync
+ ), "the GitHub refresh must stay a detached child"
+
+
+def test_an_exclusive_lock_serialises_the_two_processes(sync: str):
+ assert "lock_acquire()" in sync and "lock_release()" in sync
+ assert re.search(
+ r"flock -w \"\$LOCK_WAIT\" 9", sync
+ ), "the lock must be a real exclusive flock, and must not block forever"
+
+
+def test_the_lock_is_taken_before_anything_mutates_the_tree(sync: str):
+ lock = sync.index("\nlock_acquire\n")
+ populate = sync.index("# 1) First-boot populate")
+ assert lock < populate, (
+ "populate / restore / refresh all rewrite the state file; the lock has to "
+ "cover them, not just the strip"
+ )
+
+
+def test_a_missing_flock_degrades_instead_of_hanging(sync: str):
+ block = sync[sync.index("lock_acquire()") : sync.index("lock_release()")]
+ assert "command -v flock" in block and "return 0" in block, (
+ "a host without flock, or a $DEST that cannot hold the lock file, must "
+ "fall back to running unlocked rather than failing the boot"
+ )
+
+
+def test_the_parent_finalizes_before_it_forks(sync: str):
+ fork = sync.index('UNSLOTH_NB_REFRESH_CHILD=1 "$0"')
+ block = sync[sync.index('if [ "${UNSLOTH_NB_REFRESH_CHILD:-0}" != "1" ]; then') : fork]
+ assert re.search(r"^\s*finalize\s*$", block, re.M), (
+ "the strip and view rebuild must be done BEFORE the child exists; running "
+ "them from the EXIT trap after the fork is the race itself"
+ )
+
+
+def test_finalize_runs_at_most_once(sync: str):
+ block = sync[sync.index("finalize() {") : sync.index("trap 'finalize; lock_release' EXIT")]
+ assert (
+ '[ "$_FINALIZED" = "1" ] && return 0' in block
+ ), "the explicit pre-fork call and the EXIT trap must not strip twice"
+ assert "_FINALIZED=1" in block
+
+
+def test_the_exit_trap_still_covers_the_early_exits(sync: str):
+ assert "trap 'finalize; lock_release' EXIT" in sync
+
+
+def test_the_child_does_not_repeat_the_parents_finalize(sync: str):
+ tail = sync[sync.index("# --- refresh child ---") :]
+ assert re.search(r"^_FINALIZED=1\s*$", tail, re.M), (
+ "the parent already stripped and built the view for the tree as it "
+ "stands; an unconditional second pass makes an up-to-date boot noisy"
+ )
+
+
+def test_the_child_re_arms_the_finalize_only_after_it_changes_the_tree(sync: str):
+ tail = sync[sync.index("refreshed from GitHub") :]
+ assert re.search(
+ r'if \[ "\$updated" -gt 0 \] \|\| \[ "\$removed" -gt 0 \]; then'
+ r"\s*\n\s*_FINALIZED=0\s*\n\s*finalize",
+ tail,
+ ), (
+ "freshly copied notebooks arrive with the upstream Colab intro and have to be "
+ "stripped, and a notebook deleted upstream leaves a link in the categorized "
+ "view, but neither justifies a second pass over a tree nothing touched"
+ )
+
+
+def test_the_re_arm_is_still_conditional(sync: str):
+ """Non-vacuity for the test above: an unconditional finalize makes an up-to-date
+ boot noisy, which is why it is gated at all."""
+ tail = sync[sync.index("refreshed from GitHub") :]
+ assert "_FINALIZED=0" in tail
+ assert re.search(r"if \[[^\n]*\]; then\s*\n\s*_FINALIZED=0", tail), tail
+
+
+def test_the_lock_file_is_not_recorded_as_a_notebook(sync: str):
+ block = sync[sync.index("record_state() {") :]
+ block = block[: block.index("\n}")]
+ assert re.search(r"\.unsloth_sync\.lock[|)][^\n]*continue", block), (
+ "the lock file lives in $DEST next to the state file and must be excluded "
+ "from the managed-file state like the other metadata"
+ )
+
+
+def test_the_lock_lives_beside_the_state_it_protects(sync: str):
+ assert re.search(r'^LOCK="\$DEST/\.unsloth_sync\.lock"', sync, re.M), (
+ "keeping the lock in $DEST also serialises two containers sharing the "
+ "notebooks volume, which /tmp would not"
+ )
+
+
+# entrypoint.sh runs `sync_notebooks` then `exec "$@"`, so the child is still copying
+# while JupyterLab serves the same tree, and `cp -a` writes THROUGH the destination
+# inode: half-written JSON to a reader, and a save after the hash check destroyed.
+
+
+def test_the_refresh_publishes_each_notebook_atomically(sync: str):
+ block = sync[sync.index("while IFS= read -r -d '' f; do") :]
+ block = block[: block.index("done < <(find")]
+ assert re.search(
+ r'cp -a "\$f" "\$new"', block
+ ), "the refresh must copy into a staging file, not onto the live notebook"
+ assert re.search(
+ r'mv -f "\$new" "\$dst"', block
+ ), "the staged copy must be published with an atomic rename"
+
+
+def test_the_staging_file_is_hidden_and_beside_the_destination(sync: str):
+ assert re.search(r'new="\$\(dirname "\$dst"\)/\.unsloth_nb_new\.\$\$"', sync), (
+ "the staging file must be dot-prefixed (invisible in the file browser), "
+ "per-PID (two containers on one volume) and in the destination directory "
+ "(a rename cannot cross filesystems)"
+ )
+
+
+def test_the_recorded_hash_is_rechecked_immediately_before_publishing(sync: str):
+ block = sync[sync.index("while IFS= read -r -d '' f; do") :]
+ block = block[: block.index("done < <(find")]
+ recheck = block.index('cp -a "$f" "$new"')
+ assert re.search(
+ r'if \[ -e "\$dst" \] && \[ "\$\(hash_of "\$dst"\)" != "\$\{LAST\[\$rel\]:-\}" \]',
+ block[recheck:],
+ ), (
+ "the earlier check sits before middle_unchanged (a python subprocess), so "
+ "the hash has to be re-read once the staging copy is complete or a save "
+ "made in between is silently overwritten"
+ )
+
+
+def test_a_pristine_pre_existing_file_is_not_rewritten_on_first_boot(sync: str):
+ block = sync[sync.index('if [ ! -f "$STATE" ] || [ -f "$PARTIAL" ]; then') :]
+ block = block[: block.index('mv "$STATE.tmp" "$STATE"')]
+ assert "kept existing user file" in block
+ # RECORDED, not copied: cp -a would stamp root:root onto the host user's file
+ same = block.index("kept existing user file")
+ tail = block[same:]
+ assert tail.index("$STATE.tmp") < tail.index('cp -a "$TEMPLATE/$rel"'), (
+ "an existing file with the template's exact bytes must be recorded as "
+ "managed without being copied over"
+ )
+
+
+def test_the_recorded_hash_is_the_staged_copy_not_the_published_file(sync: str):
+ # rename(2) is atomic, but a hash taken AFTER it is a second unprotected read
+ block = sync[sync.index("while IFS= read -r -d '' f; do") :]
+ block = block[: block.index("done < <(find")]
+ assert re.search(
+ r'staged="\$\(hash_of "\$new"\)"', block
+ ), "the published hash must be taken from the staging copy"
+ assert block.index('staged="$(hash_of "$new")"') < block.index(
+ 'mv -f "$new" "$dst"'
+ ), "the staged hash must be taken BEFORE the rename that publishes it"
+ publish = block.index('mv -f "$new" "$dst"')
+ tail = block[publish:]
+ # the append goes through record_tmpstate now, which checks the write; what this
+ # test guards is unchanged, that the value recorded is $staged and not a re-read
+ assert re.search(
+ r"(printf '%s %s\\n'|record_tmpstate) \"\$staged\" \"\$rel\"", tail
+ ), "the state line must record the staged hash, not a re-read of $dst"
+ assert not re.search(r"printf '%s %s\\n' \"\$\(hash_of \"\$dst\"\)\"", tail), (
+ "re-reading $dst after the rename adopts whatever save landed in that "
+ "window as the pristine version"
+ )
+
+
+# the same race end to end, with an `mv` shim that renames for real and then writes
+# the user's bytes: the Ctrl+S that lands inside the window
+
+import hashlib # noqa: E402
+import os # noqa: E402
+import shutil # noqa: E402
+import subprocess # noqa: E402
+
+_NEEDS = ("bash", "git", "sha256sum", "mv")
+
+behavioural = pytest.mark.skipif(
+ any(shutil.which(tool) is None for tool in _NEEDS),
+ reason = "needs bash, git, sha256sum and mv",
+)
+
+
+def _sha256(path: Path) -> str:
+ return hashlib.sha256(path.read_bytes()).hexdigest()
+
+
+def _git(cwd: Path, *args: str) -> None:
+ subprocess.run(
+ ["git", *args],
+ cwd = cwd,
+ check = True,
+ capture_output = True,
+ env = dict(
+ os.environ,
+ GIT_AUTHOR_NAME = "t",
+ GIT_AUTHOR_EMAIL = "t@e",
+ GIT_COMMITTER_NAME = "t",
+ GIT_COMMITTER_EMAIL = "t@e",
+ ),
+ )
+
+
+def _remote_with(tmp_path: Path, body: str) -> Path:
+ remote = tmp_path / "remote"
+ remote.mkdir()
+ _git(remote, "init", "-q", "-b", "main")
+ (remote / "x.ipynb").write_text(body, encoding = "utf-8")
+ _git(remote, "add", "x.ipynb")
+ _git(remote, "commit", "-qm", "one")
+ return remote
+
+
+def _advance(remote: Path, body: str) -> None:
+ (remote / "x.ipynb").write_text(body, encoding = "utf-8")
+ _git(remote, "add", "x.ipynb")
+ _git(remote, "commit", "-qm", "next")
+
+
+def _env(tmp_path: Path, remote: Path, dest: Path, *, save_bytes: str | None) -> dict:
+ bin_dir = tmp_path / "bin"
+ bin_dir.mkdir(exist_ok = True)
+ real_mv = shutil.which("mv")
+ shim = bin_dir / "mv"
+ if save_bytes is None:
+ shim.write_text(f'#!/usr/bin/env bash\nexec "{real_mv}" "$@"\n', encoding = "utf-8")
+ else:
+ shim.write_text(
+ "#!/usr/bin/env bash\n"
+ f'"{real_mv}" "$@" || exit $?\n'
+ 'dst="${@: -1}"\n'
+ f'if [ "$dst" = "{dest / "x.ipynb"}" ] && [ ! -e "{tmp_path / ".fired"}" ]; then\n'
+ f' : > "{tmp_path / ".fired"}"\n'
+ f' printf %s {save_bytes!r} > "$dst"\n'
+ "fi\n",
+ encoding = "utf-8",
+ )
+ shim.chmod(0o755)
+ return dict(
+ os.environ,
+ PATH = f"{bin_dir}{os.pathsep}" + os.environ["PATH"],
+ UNSLOTH_NB_REFRESH_CHILD = "1",
+ UNSLOTH_NOTEBOOKS_TEMPLATE = str(tmp_path / "template"),
+ UNSLOTH_NOTEBOOKS_DIR = str(dest),
+ UNSLOTH_NOTEBOOKS_REPO = str(remote),
+ UNSLOTH_SKIP_NOTEBOOK_VIEW = "1",
+ UNSLOTH_KEEP_COLAB_INTRO = "1",
+ UNSLOTH_NOTEBOOK_BODY_AWARE = "0",
+ )
+
+
+def _recorded(dest: Path) -> str:
+ for line in (dest / ".unsloth_sync_state").read_text().splitlines():
+ parts = line.split(" ", 1)
+ if len(parts) == 2 and parts[1] == "x.ipynb":
+ return parts[0]
+ return ""
+
+
+def _seed(tmp_path: Path, body: str) -> Path:
+ template = tmp_path / "template"
+ template.mkdir(exist_ok = True)
+ (template / "x.ipynb").write_text(body, encoding = "utf-8")
+ dest = tmp_path / "dest"
+ dest.mkdir()
+ (dest / "x.ipynb").write_text(body, encoding = "utf-8")
+ (dest / ".unsloth_sync_state").write_text(
+ f"{_sha256(dest / 'x.ipynb')} x.ipynb\n", encoding = "utf-8"
+ )
+ (dest / ".unsloth_sync_commit").write_text("0" * 40 + "\n", encoding = "utf-8")
+ return dest
+
+
+@behavioural
+def test_a_save_landing_after_the_rename_is_not_recorded_as_pristine(tmp_path: Path):
+ remote = _remote_with(tmp_path, "v1")
+ _advance(remote, "v2")
+ dest = _seed(tmp_path, "v1")
+ subprocess.run(
+ ["bash", str(SYNC)],
+ env = _env(tmp_path, remote, dest, save_bytes = "USER EDIT"),
+ capture_output = True,
+ text = True,
+ timeout = 180,
+ )
+ live = (dest / "x.ipynb").read_text()
+ assert live == "USER EDIT", f"the shim did not land the save: {live!r}"
+ assert _recorded(dest) != _sha256(
+ dest / "x.ipynb"
+ ), "the user's own save was recorded as the sync-owned pristine version"
+ assert (
+ _recorded(dest) == hashlib.sha256(b"v2").hexdigest()
+ ), "the recorded hash must be the bytes this refresh published"
+
+
+@behavioural
+def test_a_save_in_that_window_survives_the_next_refresh(tmp_path: Path):
+ remote = _remote_with(tmp_path, "v1")
+ _advance(remote, "v2")
+ dest = _seed(tmp_path, "v1")
+ subprocess.run(
+ ["bash", str(SYNC)],
+ env = _env(tmp_path, remote, dest, save_bytes = "USER EDIT"),
+ capture_output = True,
+ text = True,
+ timeout = 180,
+ )
+ _advance(remote, "v3")
+ subprocess.run(
+ ["bash", str(SYNC)],
+ env = _env(tmp_path, remote, dest, save_bytes = None),
+ capture_output = True,
+ text = True,
+ timeout = 180,
+ )
+ assert (
+ dest / "x.ipynb"
+ ).read_text() == "USER EDIT", "the user's notebook edit was overwritten by the upstream refresh"
+
+
+@behavioural
+def test_an_unraced_refresh_still_publishes_and_records_upstream(tmp_path: Path):
+ remote = _remote_with(tmp_path, "v1")
+ _advance(remote, "v2")
+ dest = _seed(tmp_path, "v1")
+ subprocess.run(
+ ["bash", str(SYNC)],
+ env = _env(tmp_path, remote, dest, save_bytes = None),
+ capture_output = True,
+ text = True,
+ timeout = 180,
+ )
+ assert (dest / "x.ipynb").read_text() == "v2"
+ assert _recorded(dest) == hashlib.sha256(b"v2").hexdigest()
diff --git a/tests/python/test_docker_nb_sync_upstream_removal.py b/tests/python/test_docker_nb_sync_upstream_removal.py
new file mode 100644
index 00000000000..fe5b9194383
--- /dev/null
+++ b/tests/python/test_docker_nb_sync_upstream_removal.py
@@ -0,0 +1,398 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-Present the Unsloth team. See /studio/LICENSE.AGPL-3.0
+
+"""A notebook deleted or renamed upstream has to leave the tree.
+
+The refresh loop walks the CLONE, so a file that vanished upstream is never visited,
+and the state file is then REPLACED by what that loop recorded. The copy we published
+stays on disk with no record, the next refresh reads it as user-owned, and
+unsloth_nb_view.py files it under "Other Notebooks" for good. Upstream deleted 10 and
+renamed 7 nb/ notebooks in the last year, so they accumulate.
+
+Only a file that still hashes to what the sync itself wrote is removed, which is what
+keeps a user's edit safe, so that is asserted here rather than assumed.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import os
+import shutil
+import subprocess
+from pathlib import Path
+
+import pytest
+
+REPO_ROOT = Path(__file__).resolve().parents[2]
+SYNC = REPO_ROOT / "docker" / "unsloth_sync_notebooks.sh"
+
+behavioural = pytest.mark.skipif(
+ any(shutil.which(tool) is None for tool in ("bash", "git", "sha256sum")),
+ reason = "needs bash, git and sha256sum",
+)
+
+
+def _sha256(path: Path) -> str:
+ return hashlib.sha256(path.read_bytes()).hexdigest()
+
+
+def _git(cwd: Path, *args: str) -> None:
+ subprocess.run(
+ ["git", *args],
+ cwd = cwd,
+ check = True,
+ capture_output = True,
+ env = dict(
+ os.environ,
+ GIT_AUTHOR_NAME = "t",
+ GIT_AUTHOR_EMAIL = "t@e",
+ GIT_COMMITTER_NAME = "t",
+ GIT_COMMITTER_EMAIL = "t@e",
+ ),
+ )
+
+
+FILES = {
+ "nb/keep.ipynb": "keep-v1",
+ "nb/doomed.ipynb": "doomed-v1",
+ "nb/edited.ipynb": "edited-v1",
+}
+
+
+def _setup(tmp_path: Path):
+ remote = tmp_path / "remote"
+ (remote / "nb").mkdir(parents = True)
+ for rel, body in FILES.items():
+ (remote / rel).write_text(body, encoding = "utf-8")
+ _git(remote, "init", "-q", "-b", "main")
+ _git(remote, "add", "-A")
+ _git(remote, "commit", "-qm", "one")
+
+ template = tmp_path / "template"
+ (template / "nb").mkdir(parents = True)
+ dest = tmp_path / "dest"
+ (dest / "nb").mkdir(parents = True)
+ lines = []
+ for rel, body in FILES.items():
+ (template / rel).write_text(body, encoding = "utf-8")
+ (dest / rel).write_text(body, encoding = "utf-8")
+ lines.append(f"{_sha256(dest / rel)} {rel}")
+ (dest / ".unsloth_sync_state").write_text("\n".join(lines) + "\n", encoding = "utf-8")
+ return remote, template, dest
+
+
+def _advance(remote: Path):
+ """Upstream drops two notebooks and changes the third."""
+ (remote / "nb" / "doomed.ipynb").unlink()
+ (remote / "nb" / "edited.ipynb").unlink()
+ (remote / "nb" / "keep.ipynb").write_text("keep-v2", encoding = "utf-8")
+ _git(remote, "add", "-A")
+ _git(remote, "commit", "-qm", "two")
+
+
+def _refresh(tmp_path: Path, remote: Path, template: Path, dest: Path, **extra):
+ return subprocess.run(
+ ["bash", str(SYNC)],
+ capture_output = True,
+ text = True,
+ timeout = 300,
+ env = dict(
+ os.environ,
+ UNSLOTH_NB_REFRESH_CHILD = "1",
+ UNSLOTH_NOTEBOOKS_TEMPLATE = str(template),
+ UNSLOTH_NOTEBOOKS_DIR = str(dest),
+ UNSLOTH_NOTEBOOKS_REPO = str(remote),
+ UNSLOTH_SKIP_NOTEBOOK_VIEW = "1",
+ UNSLOTH_KEEP_COLAB_INTRO = "1",
+ **extra,
+ ),
+ )
+
+
+def _state(dest: Path) -> dict:
+ path = dest / ".unsloth_sync_state"
+ out = {}
+ if path.is_file():
+ for line in path.read_text(encoding = "utf-8").splitlines():
+ parts = line.split(" ", 1)
+ if len(parts) == 2:
+ out[parts[1]] = parts[0]
+ return out
+
+
+@behavioural
+def test_a_pristine_notebook_deleted_upstream_is_removed(tmp_path: Path):
+ remote, template, dest = _setup(tmp_path)
+ _advance(remote)
+ # the user edited one of the two that upstream dropped
+ (dest / "nb" / "edited.ipynb").write_text("MY OWN WORK", encoding = "utf-8")
+
+ run = _refresh(tmp_path, remote, template, dest)
+ assert run.returncode == 0, run.stdout + run.stderr
+
+ assert not (
+ dest / "nb" / "doomed.ipynb"
+ ).exists(), "the notebook upstream deleted is still on disk, so the view keeps listing it"
+ assert (dest / "nb" / "edited.ipynb").read_text(
+ encoding = "utf-8"
+ ) == "MY OWN WORK", "a file that no longer hashes to what we wrote is the user's, edited or not"
+ assert (dest / "nb" / "keep.ipynb").read_text(encoding = "utf-8") == "keep-v2"
+
+ state = _state(dest)
+ assert "nb/doomed.ipynb" not in state
+ assert state["nb/keep.ipynb"] == _sha256(dest / "nb" / "keep.ipynb")
+ assert "1 removed upstream" in run.stdout, run.stdout
+
+
+@behavioural
+def test_the_removal_can_be_turned_off(tmp_path: Path):
+ """Non-vacuity as well as the opt-out: with the switch on, the same run leaves it."""
+ remote, template, dest = _setup(tmp_path)
+ _advance(remote)
+
+ run = _refresh(tmp_path, remote, template, dest, UNSLOTH_KEEP_REMOVED_NOTEBOOKS = "1")
+ assert run.returncode == 0, run.stdout + run.stderr
+
+ assert (dest / "nb" / "doomed.ipynb").exists()
+ assert "0 removed upstream" in run.stdout, run.stdout
+
+
+@behavioural
+def test_a_case_only_rename_does_not_delete_the_file_just_published(tmp_path: Path):
+ """The clone is case-sensitive while the destination may be a macOS or Windows bind
+ mount, so the old path would resolve to the file the refresh has just written."""
+ remote, template, dest = _setup(tmp_path)
+ _git(remote, "mv", "nb/doomed.ipynb", "nb/Doomed.ipynb")
+ _git(remote, "commit", "-qm", "rename case only")
+
+ run = _refresh(tmp_path, remote, template, dest)
+ assert run.returncode == 0, run.stdout + run.stderr
+
+ assert (dest / "nb" / "Doomed.ipynb").exists()
+ assert "0 removed upstream" in run.stdout, run.stdout
+
+
+@behavioural
+def test_nothing_is_removed_when_upstream_removed_nothing(tmp_path: Path):
+ remote, template, dest = _setup(tmp_path)
+ (remote / "nb" / "keep.ipynb").write_text("keep-v2", encoding = "utf-8")
+ _git(remote, "add", "-A")
+ _git(remote, "commit", "-qm", "two")
+
+ run = _refresh(tmp_path, remote, template, dest)
+ assert run.returncode == 0, run.stdout + run.stderr
+
+ for rel in FILES:
+ assert (dest / rel).exists(), rel
+ assert "0 removed upstream" in run.stdout, run.stdout
+
+
+def _refuse_rm(tmp_path: Path, target: Path) -> Path:
+ """A `rm` earlier on PATH that fails for one path, the way a writable single-FILE
+ bind mount fails with EBUSY. The publish above already works around that case for
+ rename, so it is not hypothetical here."""
+ bindir = tmp_path / "bin"
+ bindir.mkdir(exist_ok = True)
+ stub = bindir / "rm"
+ stub.write_text(
+ "#!/bin/sh\n"
+ 'for a in "$@"; do\n'
+ f' [ "$a" = "{target}" ] && exit 1\n'
+ "done\n"
+ 'exec /bin/rm "$@"\n',
+ encoding = "utf-8",
+ )
+ stub.chmod(0o755)
+ return bindir
+
+
+@behavioural
+def test_a_removal_that_cannot_be_unlinked_keeps_its_record_and_retries(tmp_path: Path):
+ """Ignoring the failure dropped the record while leaving the file, which is the
+ exact state the removal exists to prevent: the next refresh reads the stale copy as
+ user-owned and never tries again. It also left `failed` at zero, so the sync marker
+ was stamped and the next start exited before it looked."""
+ remote, template, dest = _setup(tmp_path)
+ _advance(remote)
+ # upstream dropped this one too, but the user owns it now, so doomed is the only
+ # removal candidate and the counters below are about it alone
+ (dest / "nb" / "edited.ipynb").write_text("MY OWN WORK", encoding = "utf-8")
+ doomed = dest / "nb" / "doomed.ipynb"
+ bindir = _refuse_rm(tmp_path, doomed)
+
+ run = _refresh(
+ tmp_path, remote, template, dest, PATH = f"{bindir}{os.pathsep}{os.environ['PATH']}"
+ )
+ assert run.returncode == 0, run.stdout + run.stderr
+
+ assert doomed.exists(), "precondition: the stub refused the unlink"
+ assert _state(dest).get("nb/doomed.ipynb") == _sha256(
+ doomed
+ ), "the file stayed but its record was dropped, so it is now unmanaged"
+ assert "0 removed upstream" in run.stdout, run.stdout
+ assert not (
+ dest / ".unsloth_sync_commit"
+ ).is_file(), "the commit was stamped over a failure, so the next start exits before retrying"
+
+ run2 = _refresh(tmp_path, remote, template, dest)
+ assert run2.returncode == 0, run2.stdout + run2.stderr
+ assert not doomed.exists()
+ assert "nb/doomed.ipynb" not in _state(dest)
+ assert "1 removed upstream" in run2.stdout, run2.stdout
+
+
+@behavioural
+def test_the_successful_removal_still_stamps_the_commit(tmp_path: Path):
+ """Non-vacuity for the assertion above: without the stub the same run records it,
+ so the marker check is testing the failure and not the environment."""
+ remote, template, dest = _setup(tmp_path)
+ _advance(remote)
+ (dest / "nb" / "edited.ipynb").write_text("MY OWN WORK", encoding = "utf-8")
+
+ run = _refresh(tmp_path, remote, template, dest)
+ assert run.returncode == 0, run.stdout + run.stderr
+
+ assert (dest / ".unsloth_sync_commit").is_file()
+ assert "1 removed upstream" in run.stdout, run.stdout
+
+
+def _refuse_mv_to(tmp_path: Path, target: Path) -> Path:
+ """An `mv` earlier on PATH that fails for one destination, the way a full or
+ read-only /workspace fails when the state file is published. Every other move,
+ including the same-dir rename each notebook is published with, passes through."""
+ bindir = tmp_path / "bin"
+ bindir.mkdir(exist_ok = True)
+ stub = bindir / "mv"
+ stub.write_text(
+ "#!/bin/sh\n"
+ 'for a in "$@"; do\n'
+ f' [ "$a" = "{target}" ] && exit 1\n'
+ "done\n"
+ 'exec /bin/mv "$@"\n',
+ encoding = "utf-8",
+ )
+ stub.chmod(0o755)
+ return bindir
+
+
+@behavioural
+def test_a_state_that_cannot_be_published_holds_the_sync_marker(tmp_path: Path):
+ """Stamping the commit over a failed state publish wedges the tree permanently.
+ The next boot exits on remote == last, and once upstream moves again the stale
+ hashes no longer match the notebooks this run wrote, so all of them read as
+ user-edited and are never updated again. `failed` already holds the marker back
+ for a notebook that could not be written; the state file has to count too."""
+ remote, template, dest = _setup(tmp_path)
+ _advance(remote)
+ before = _state(dest)
+ bindir = _refuse_mv_to(tmp_path, dest / ".unsloth_sync_state")
+
+ run = _refresh(
+ tmp_path, remote, template, dest, PATH = f"{bindir}{os.pathsep}{os.environ['PATH']}"
+ )
+ assert run.returncode == 0, run.stdout + run.stderr
+
+ assert _state(dest) == before, "precondition: the stub refused the state publish"
+ assert not (
+ dest / ".unsloth_sync_commit"
+ ).is_file(), "the commit was stamped over an unpublished state, so the tree is wedged"
+
+
+@behavioural
+def test_the_state_temp_file_is_published_by_a_same_directory_rename(tmp_path: Path):
+ """Holding the marker is not on its own enough, which is why the temp file sits
+ beside the state file rather than in /tmp. The notebooks are published BEFORE the
+ state is, so a publish that fails on its own leaves disk ahead of state, and no
+ marker check undoes that: the next run reads every notebook it just wrote as
+ user-edited, because they no longer hash to the stale record. A sibling makes the
+ publish an atomic rename and makes it fail WITH the notebook writes, which already
+ hold the marker. Asserted on the script text because the failure it removes cannot
+ be provoked once the rename is atomic."""
+ source = SYNC.read_text(encoding = "utf-8")
+ assert 'TMPSTATE="$STATE.tmp"' in source, (
+ "the refresh state temp file left $DEST, so publishing it is a cross-device "
+ "copy that can fail after the notebooks have already landed"
+ )
+ stray = [
+ line.strip()
+ for line in source.splitlines()
+ if "mktemp" in line and "TMPSTATE=" in line and "||" not in line
+ ]
+ assert not stray, f"the refresh state must not be staged outside $DEST: {stray}"
+
+
+@behavioural
+def test_a_published_state_still_stamps_the_commit(tmp_path: Path):
+ """Non-vacuity for the assertion above: the identical run without the stub records
+ the marker, so that check is testing the failure and not the environment."""
+ remote, template, dest = _setup(tmp_path)
+ _advance(remote)
+
+ run = _refresh(tmp_path, remote, template, dest)
+ assert run.returncode == 0, run.stdout + run.stderr
+ assert (dest / ".unsloth_sync_commit").is_file()
+
+
+@behavioural
+def test_an_unwritable_dest_publishes_nothing_and_recovers(tmp_path: Path):
+ """$DEST unwritable while a notebook subdir still is, which is the container shape:
+ the image bakes the root and only the subdirs get chowned to the host user.
+
+ Staging the state in /tmp here would publish the new notebook bytes and then be
+ unable to record them. Run two reads every one of them as a user edit, and a user
+ edit counts as `kept`, not `failed`, so the marker IS stamped and the whole managed
+ set is stranded permanently. Nothing is published yet at that point, so the refresh
+ must bail and leave the tree exactly as it was."""
+ remote, template, dest = _setup(tmp_path)
+ _advance(remote)
+ before_state = _state(dest)
+ before_bytes = (dest / "nb" / "keep.ipynb").read_text(encoding = "utf-8")
+
+ (dest / "nb").chmod(0o755)
+ dest.chmod(0o555) # root writable by nobody; the subdir still is
+ try:
+ run = _refresh(tmp_path, remote, template, dest)
+ assert run.returncode == 0, run.stdout + run.stderr
+
+ assert (dest / "nb" / "keep.ipynb").read_text(
+ encoding = "utf-8"
+ ) == before_bytes, "notebooks were published with no way to record them"
+ assert _state(dest) == before_state
+ assert not (
+ dest / ".unsloth_sync_commit"
+ ).is_file(), "the marker was stamped over a refresh that could not record itself"
+ finally:
+ dest.chmod(0o755)
+
+ # the whole point of bailing: the next start recovers instead of being stranded
+ run2 = _refresh(tmp_path, remote, template, dest)
+ assert run2.returncode == 0, run2.stdout + run2.stderr
+ assert (dest / "nb" / "keep.ipynb").read_text(encoding = "utf-8") == "keep-v2"
+ assert _state(dest).get("nb/keep.ipynb") == _sha256(dest / "nb" / "keep.ipynb")
+ assert (dest / ".unsloth_sync_commit").is_file()
+
+
+@behavioural
+def test_a_stale_state_temp_file_does_not_block_the_refresh_forever(tmp_path: Path):
+ """The bail above must not become permanent. A run killed between the truncate and
+ the mv leaves $STATE.tmp behind, and if that run was a different uid (root once,
+ then --user) the file cannot be truncated even though $DEST is writable. Bailing
+ then would strand the tree on every future start, which is the failure the bail
+ exists to prevent. Unlinking needs write on $DEST, which the real bail case does
+ not have, so clearing it first cannot weaken the guard."""
+ remote, template, dest = _setup(tmp_path)
+ _advance(remote)
+
+ stale = dest / ".unsloth_sync_state.tmp"
+ stale.write_text("LEFTOVER FROM A KILLED RUN\n", encoding = "utf-8")
+ stale.chmod(0o444) # cannot be truncated by this uid; can still be unlinked
+ assert not os.access(stale, os.W_OK), "precondition: the leftover is not truncatable"
+
+ run = _refresh(tmp_path, remote, template, dest)
+ assert run.returncode == 0, run.stdout + run.stderr
+
+ assert (dest / "nb" / "keep.ipynb").read_text(
+ encoding = "utf-8"
+ ) == "keep-v2", "a stale temp file the uid cannot truncate blocked the refresh"
+ assert _state(dest).get("nb/keep.ipynb") == _sha256(dest / "nb" / "keep.ipynb")
+ assert (dest / ".unsloth_sync_commit").is_file()
diff --git a/tests/python/test_docker_nb_view_ownership.py b/tests/python/test_docker_nb_view_ownership.py
new file mode 100644
index 00000000000..57bb6fcd5e2
--- /dev/null
+++ b/tests/python/test_docker_nb_view_ownership.py
@@ -0,0 +1,160 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-Present the Unsloth team. See /studio/LICENSE.AGPL-3.0
+
+"""The categorized notebook VIEW may only delete the links it created.
+
+The VIEW is also JupyterLab's landing dir. Every link the tool creates points at
+DEST/nb/<file>, but the ownership predicate accepted ANY target under DEST, so a
+user's own shortcut to a notebook beside the checkout was deleted on the next boot.
+"""
+
+from __future__ import annotations
+
+import importlib.util
+import os
+from pathlib import Path
+
+import pytest
+
+REPO_ROOT = Path(__file__).resolve().parents[2]
+VIEW_PATH = REPO_ROOT / "docker" / "unsloth_nb_view.py"
+
+README = (
+ "### Main Notebooks\n"
+ "[Llama](nb/Llama3_2_%281B_and_3B%29_Conversational.ipynb)\n"
+ "### Gemma\n"
+ "[Gemma](nb/Gemma3_%284B%29.ipynb)\n"
+)
+
+
[email protected](scope = "module")
+def view_mod():
+ assert VIEW_PATH.is_file(), f"missing {VIEW_PATH}"
+ spec = importlib.util.spec_from_file_location("unsloth_nb_view_under_test", VIEW_PATH)
+ mod = importlib.util.module_from_spec(spec)
+ spec.loader.exec_module(mod)
+ return mod
+
+
+def tree(tmp_path: Path):
+ dest = tmp_path / "unsloth-notebooks"
+ view = tmp_path / "Unsloth Notebooks"
+ (dest / "nb").mkdir(parents = True)
+ view.mkdir()
+ for name in ("Llama3_2_(1B_and_3B)_Conversational.ipynb", "Gemma3_(4B).ipynb"):
+ (dest / "nb" / name).write_text("{}", encoding = "utf-8")
+ (dest / "README.md").write_text(README, encoding = "utf-8")
+ # the user's own notebook inside the checkout, plus their own shortcut folder
+ (dest / "my_work").mkdir()
+ (dest / "my_work" / "experiment.ipynb").write_text("{}", encoding = "utf-8")
+ return dest, view
+
+
+def link(target: Path, at: Path) -> None:
+ at.parent.mkdir(parents = True, exist_ok = True)
+ os.symlink(os.path.relpath(target, at.parent), at)
+
+
+def test_a_user_link_to_their_own_file_in_the_checkout_survives(view_mod, tree):
+ dest, view = tree
+ own = view / "00 My favourites" / "experiment.ipynb"
+ link(dest / "my_work" / "experiment.ipynb", own)
+
+ view_mod.build_view(str(dest), str(view))
+
+ assert os.path.islink(own), (
+ "a symlink the user created in the landing dir, pointing at their own "
+ "file inside the notebooks checkout, was deleted by _clear_view"
+ )
+ assert os.path.realpath(own) == os.path.realpath(dest / "my_work" / "experiment.ipynb")
+
+
+def test_a_user_link_outside_the_checkout_survives(view_mod, tree, tmp_path: Path):
+ dest, view = tree
+ outside = tmp_path / "datasets"
+ outside.mkdir()
+ own = view / "datasets"
+ link(outside, own)
+
+ view_mod.build_view(str(dest), str(view))
+
+ assert os.path.islink(own)
+
+
+def test_the_tools_own_stale_links_are_still_cleaned_up(view_mod, tree):
+ dest, view = tree
+ view_mod.build_view(str(dest), str(view))
+ generated = view / "02 Gemma" / "Gemma3_(4B).ipynb"
+ assert os.path.islink(generated)
+
+ # upstream drops the notebook: the stale link and its emptied folder must go
+ (dest / "nb" / "Gemma3_(4B).ipynb").unlink()
+ (dest / "README.md").write_text(
+ "### Main Notebooks\n[Llama](nb/Llama3_2_%281B_and_3B%29_Conversational.ipynb)\n",
+ encoding = "utf-8",
+ )
+ view_mod.build_view(str(dest), str(view))
+
+ assert not os.path.islink(generated) and not os.path.exists(generated)
+ assert not (view / "02 Gemma").exists()
+
+
+def test_a_rebuild_is_stable_for_the_links_it_owns(view_mod, tree):
+ dest, view = tree
+ view_mod.build_view(str(dest), str(view))
+ first = sorted(str(p.relative_to(view)) for p in view.rglob("*"))
+ view_mod.build_view(str(dest), str(view))
+ assert sorted(str(p.relative_to(view)) for p in view.rglob("*")) == first
+
+
+# The view is built as root while /workspace is a host bind mount, so every directory
+# the tool creates has to be handed back to whoever owns the mount. The tests run
+# unprivileged, where a chown to the anchor's own uid is a no-op and therefore
+# invisible in the result, so record the calls instead of inspecting st_uid.
+
+
+def chowns(monkeypatch):
+ calls = []
+ real = os.chown
+
+ def _record(path, uid, gid, *a, **kw):
+ calls.append((str(path), uid, gid))
+ return real(path, uid, gid, *a, **kw)
+
+ monkeypatch.setattr(os, "chown", _record)
+ return calls
+
+
+def test_the_view_root_and_every_category_folder_are_handed_to_the_host_user(
+ view_mod, tree, chowns
+):
+ dest, view = tree
+ view.rmdir() # first boot: the tool creates the view root itself
+ anchor = os.stat(view.parent)
+
+ view_mod.build_view(str(dest), str(view))
+
+ created = [str(view)] + [str(p) for p in sorted(view.iterdir()) if p.is_dir()]
+ assert len(created) >= 3, created
+ for path in created:
+ assert (path, anchor.st_uid, anchor.st_gid) in chowns, (path, chowns)
+
+
+def test_an_existing_directory_is_left_alone(view_mod, tree, chowns):
+ """Only directories this run created are re-owned. Chowning one the user already
+ had would take their view away rather than give it to them."""
+ dest, view = tree # the fixture already created the view root
+ view_mod.build_view(str(dest), str(view))
+ assert str(view) not in [c[0] for c in chowns], chowns
+
+
+def test_the_view_uses_the_same_directory_maker_as_unsloth_run(view_mod):
+ """A third copy of the walk would drift, and a silent import failure would put the
+ view straight back to creating root-owned folders."""
+ helper = view_mod._MAKEDIRS_AS_HOST
+ assert helper is not None, "the shared helper stopped resolving"
+ assert helper.__name__ == "_makedirs_as_host"
+ source = Path(helper.__code__.co_filename).resolve()
+ assert source == (REPO_ROOT / "docker" / "unsloth_run.py").resolve(), source
diff --git a/tests/python/test_docker_pip_shim_training_stack.py b/tests/python/test_docker_pip_shim_training_stack.py
new file mode 100644
index 00000000000..2838849813e
--- /dev/null
+++ b/tests/python/test_docker_pip_shim_training_stack.py
@@ -0,0 +1,315 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-Present the Unsloth team. See /studio/LICENSE.AGPL-3.0
+
+"""Regression guard for what the Docker pip shim protects.
+
+The shim protected torch/vLLM/unsloth and stopped there, so every notebook run
+silently mutated the training stack the image was validated with -- while printing
+that it was keeping the baked versions.
+
+The criterion for _KEEP is "replacing this invalidates the tested stack or breaks
+unsloth", not "any package a notebook mentions".
+"""
+
+from __future__ import annotations
+
+import importlib.util
+import os
+from pathlib import Path
+
+import pytest
+
+REPO_ROOT = Path(__file__).resolve().parents[2]
+SHIM_PATH = REPO_ROOT / "docker" / "unsloth_pip_shim.py"
+
+SHIPPED_TRL_CELL = ["--no-deps", "trl==0.22.2"]
+UNBAKED = "snac"
+
+
+class _Exec(Exception):
+ def __init__(self, path, argv):
+ self.path = path
+ self.argv = list(argv)
+
+
+class _BakedImage:
+ """Stands in for _installed_names() on an image where every bake succeeded.
+
+ Only `in` is asked of the return value, so answering the prefix rule here keeps
+ nvidia-* wheels present too, which a plain set of _KEEP cannot express.
+ """
+
+ def __init__(self, mod):
+ self._mod = mod
+
+ def __contains__(self, name):
+ # transformers is baked too; it is out of _KEEP only because the sidecar
+ # replaces its VERSION rather than the distribution
+ if name == "transformers":
+ return True
+ return name in self._mod._KEEP or name.startswith(self._mod._KEEP_PREFIX)
+
+
+def shim(tmp_path, monkeypatch):
+ monkeypatch.setenv("UNSLOTH_NB_TF_MARKER", str(tmp_path / "requested_transformers"))
+ monkeypatch.setenv("UNSLOTH_NB_SHIM", "1")
+ assert SHIM_PATH.is_file(), f"missing shim: {SHIM_PATH}"
+ spec = importlib.util.spec_from_file_location("unsloth_pip_shim_stack_test", SHIM_PATH)
+ mod = importlib.util.module_from_spec(spec)
+ spec.loader.exec_module(mod)
+
+ def _fake_execv(path, argv):
+ raise _Exec(path, argv)
+
+ monkeypatch.setattr(mod.os, "execv", _fake_execv)
+ # the shim now skips a protected package only when it is really installed, so pin
+ # the fully baked image here: otherwise these assertions read the CI venv, which
+ # has no torchcodec, and pass or fail on the runner rather than on the shim
+ monkeypatch.setattr(mod, "_installed_names", lambda: _BakedImage(mod))
+ return mod
+
+
+def _run(
+ shim,
+ args,
+ tool = "pip",
+):
+ """Args after `install`, or None when the shim no-op'd; constraints pair dropped."""
+ argv = ["uv", "pip", "install", *args] if tool == "uv" else ["pip", "install", *args]
+ with pytest.MonkeyPatch.context() as mp:
+ mp.setattr(shim.sys, "argv", argv)
+ try:
+ shim.main()
+ return None
+ except _Exec as exc:
+ i = exc.argv.index("install")
+ execd = exc.argv[i + 1 :]
+ if (
+ len(execd) >= 2
+ and execd[-2] == "--constraint"
+ and os.path.basename(execd[-1]).startswith("unsloth-nb-protected-")
+ ):
+ execd = execd[:-2]
+ return execd
+
+
+ "pkg",
+ [
+ "trl",
+ "peft",
+ "datasets",
+ "accelerate",
+ "torchao",
+ "torchcodec",
+ "huggingface-hub",
+ "tokenizers",
+ "safetensors",
+ ],
+)
+def test_training_stack_is_protected(shim, pkg):
+ assert (
+ pkg in shim._KEEP
+ ), f"{pkg} is baked and tested; a notebook pin replacing it invalidates the image"
+
+
+def test_the_original_gpu_stack_is_still_protected(shim):
+ for pkg in [
+ "torch",
+ "torchvision",
+ "torchaudio",
+ "triton",
+ "xformers",
+ "vllm",
+ "bitsandbytes",
+ "unsloth",
+ "unsloth-zoo",
+ ]:
+ assert pkg in shim._KEEP
+
+
+def test_unrelated_packages_are_not_swept_in(shim):
+ for pkg in [
+ "snac",
+ "causal-conv1d",
+ "mamba-ssm",
+ "omegaconf",
+ "timm",
+ "librosa",
+ "trackio",
+ "open-spiel",
+ "protobuf",
+ "sentencepiece",
+ ]:
+ assert pkg not in shim._KEEP, f"{pkg} must still install for the notebooks that need it"
+
+
+def test_the_shipped_trl_cell_installs_nothing(shim):
+ assert _run(shim, SHIPPED_TRL_CELL) is None
+
+
+def test_a_mixed_cell_keeps_only_the_unbaked_package(shim):
+ execd = _run(
+ shim,
+ [
+ "--no-deps",
+ "trl==0.22.2",
+ "peft==0.14.0",
+ "datasets==3.0.0",
+ "accelerate==1.0.0",
+ UNBAKED,
+ ],
+ )
+ assert execd == ["--no-deps", UNBAKED], execd
+
+
+def test_cuda_matched_wheels_are_not_replaced_by_pypi_builds(shim):
+ # these come from the cu128 index; a PyPI pin swaps in a generic (or cu13) build
+ assert _run(shim, ["torchao==0.15.0", "torchcodec==0.5"]) is None
+
+
+def test_transformers_companions_cannot_desynchronise_the_sidecars(shim):
+ # each sidecar ships its own matched copies, so a base-venv swap breaks them all
+ assert (
+ _run(shim, ["huggingface_hub==0.30.0", "tokenizers==0.20.0", "safetensors==0.4.0"]) is None
+ )
+
+
+def test_an_unbaked_package_still_installs(shim):
+ assert _run(shim, [UNBAKED]) == [UNBAKED]
+ assert _run(shim, [UNBAKED], tool = "uv") == [UNBAKED]
+
+
+def test_protection_survives_a_requirements_file(shim, tmp_path):
+ req = tmp_path / "requirements.txt"
+ req.write_text(f"trl==0.22.2\npeft==0.14.0\ndatasets==3.0.0\n{UNBAKED}\n")
+ execd = _run(shim, ["-r", str(req)])
+ assert execd is not None and execd[0] == "-r"
+ filtered = Path(execd[1]).read_text()
+ assert UNBAKED in filtered
+ for dropped in ("trl", "peft", "datasets"):
+ assert dropped not in filtered, f"{dropped} slipped through the requirements file"
+
+
+def test_protection_survives_a_direct_wheel_url(shim):
+ url = "https://files.pythonhosted.org/x/trl-0.22.2-py3-none-any.whl"
+ assert _run(shim, [url, UNBAKED]) == [UNBAKED]
+
+
+def test_protection_survives_an_editable_vcs_install(shim):
+ assert _run(shim, ["-e", "git+https://github.com/huggingface/trl.git", UNBAKED]) == [UNBAKED]
+
+
+# A protected package that the image never managed to bake is nothing to protect, and
+# dropping it turned the recovery install into a silent success. MISSING is a _KEEP
+# member the Dockerfile is allowed to leave out (see the fail-soft premise test below).
+MISSING = "vllm"
+
+
+def _without(mod, missing):
+ """_installed_names() for an image whose `missing` bake was skipped."""
+ baked = _BakedImage(mod)
+
+ class _Partial:
+ def __contains__(self, name):
+ return name != missing and name in baked
+
+ return _Partial()
+
+
+def shim_without_vllm(shim, monkeypatch):
+ """The same shim over an image whose vLLM bake was skipped."""
+ monkeypatch.setattr(shim, "_installed_names", lambda: _without(shim, MISSING))
+ return shim
+
+
+def test_the_baked_premise_holds_before_the_absence_tests_mean_anything(shim):
+ """Non-vacuity: the two views must disagree, or every test below is trivial."""
+ assert _run(shim, [MISSING]) is None
+ with pytest.MonkeyPatch.context() as mp:
+ mp.setattr(shim, "_installed_names", lambda: _without(shim, MISSING))
+ assert _run(shim, [MISSING]) == [MISSING]
+
+
+def test_a_protected_package_the_image_never_baked_still_installs(shim_without_vllm):
+ # the arm64 vLLM bake is fail-soft, so `!pip install vllm` was the documented
+ # recovery; skipping it printed "kept baked versions" over an image with no vLLM
+ assert _run(shim_without_vllm, [MISSING]) == [MISSING]
+ assert _run(shim_without_vllm, [f"{MISSING}==0.20.0"]) == [f"{MISSING}==0.20.0"]
+ assert _run(shim_without_vllm, [MISSING], tool = "uv") == [MISSING]
+
+
+def test_the_absence_check_reaches_the_requirements_file_path(shim_without_vllm, tmp_path):
+ req = tmp_path / "requirements.txt"
+ req.write_text(f"trl==0.22.2\n{MISSING}==0.20.0\n")
+ execd = _run(shim_without_vllm, ["-r", str(req)])
+ assert execd is not None and execd[0] == "-r"
+ filtered = Path(execd[1]).read_text()
+ assert MISSING in filtered, filtered
+ assert "trl" not in filtered, filtered
+
+
+def test_the_absence_check_reaches_the_flag_target_path(shim_without_vllm):
+ # -e and -P classify their value through a separate helper; it drifted before
+ assert _run(shim_without_vllm, ["-P", MISSING, UNBAKED]) == ["-P", MISSING, UNBAKED]
+ assert _run(shim_without_vllm, ["-P", "trl", UNBAKED]) == [UNBAKED]
+
+
+def test_an_unreadable_metadata_scan_keeps_the_stricter_answer(shim, monkeypatch):
+ """Never open the stack up because the venv could not be read."""
+ monkeypatch.setattr(shim, "_installed_names", lambda: None)
+ assert _run(shim, [MISSING]) is None
+ assert _run(shim, ["torch"]) is None
+
+
+def test_installed_names_reads_a_real_venv(shim):
+ """The helper itself, unpatched: a stub returning an empty set would pass every
+ test above while forwarding the whole baked stack in the image."""
+ spec = importlib.util.spec_from_file_location("unsloth_pip_shim_unpatched", SHIM_PATH)
+ fresh = importlib.util.module_from_spec(spec)
+ spec.loader.exec_module(fresh)
+ names = fresh._installed_names()
+ assert names is not None
+ assert "pytest" in names, "the running interpreter must at least see pytest"
+ assert "definitely-not-a-real-distribution" not in names
+
+
+def test_every_drop_decision_goes_through_the_one_predicate(shim):
+ """The three call sites drifted apart before; keep them on _is_protected."""
+ source = SHIM_PATH.read_text(encoding = "utf-8")
+ raw = [
+ line
+ for line in source.splitlines()
+ if "_KEEP_PREFIX)" in line and "_KEEP_PREFIX = " not in line
+ ]
+ # only the predicate itself and the constraints builder may spell the rule out;
+ # the constraints builder is already scoped to installed distributions
+ assert len(raw) == 2, raw
+
+
+def test_the_dockerfile_still_lets_a_protected_bake_fail(shim):
+ """Premise pin: if every bake becomes mandatory, the absence path is dead code and
+ this file should be revisited rather than left asserting a case that cannot arise."""
+ dockerfile = (REPO_ROOT / "docker" / "Dockerfile").read_text(encoding = "utf-8")
+ assert "torchcodec bake skipped" in dockerfile
+ assert "fail-soft on non-amd64" in dockerfile
+ assert MISSING in shim._KEEP
+
+
+def test_forwarded_installs_pin_the_protected_set_for_the_resolver(shim):
+ # argument filtering does not stop a DEPENDENCY of the kept target from dragging
+ # peft/datasets down, which happened with no notebook ever naming peft
+ with pytest.MonkeyPatch.context() as mp:
+ mp.setattr(shim.sys, "argv", ["pip", "install", UNBAKED])
+ with pytest.raises(_Exec) as exc:
+ shim.main()
+ argv = exc.value.argv
+ assert "--constraint" in argv
+ pins = Path(argv[argv.index("--constraint") + 1]).read_text()
+ names = {line.split("==")[0].lower().replace("_", "-") for line in pins.splitlines() if line}
+ assert names, "the constraints file must not be empty"
+ assert all(
+ n in shim._KEEP or n == "transformers" or n.startswith("nvidia-") for n in names
+ ), sorted(names)
diff --git a/tests/python/test_docker_publish_ref_freeze.py b/tests/python/test_docker_publish_ref_freeze.py
new file mode 100644
index 00000000000..667821edc90
--- /dev/null
+++ b/tests/python/test_docker_publish_ref_freeze.py
@@ -0,0 +1,429 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-Present the Unsloth team. See /studio/LICENSE.AGPL-3.0
+
+"""The docker publish workflow must never forward an unfrozen ref.
+
+`git ls-remote` exits 0 whether or not a ref matched, so a non-zero exit means the
+remote was never reached -- and that exit is lost twice over: it heads a pipeline, and
+a `run:` step with no explicit `shell:` runs under `bash -e` WITHOUT pipefail. The
+step then publishes `ref=main`, each build resolves it independently, and the
+stable-tag gates still move `:latest` onto the result.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+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"
+
+RESOLVER_STEPS = ("unsloth_ref", "zoo_ref", "notebooks")
+
+pytestmark = pytest.mark.skipif(
+ shutil.which("bash") is None,
+ reason = "needs bash",
+)
+
+
[email protected](scope = "module")
+def steps() -> dict:
+ assert WORKFLOW.is_file(), f"missing {WORKFLOW}"
+ doc = yaml.safe_load(WORKFLOW.read_text(encoding = "utf-8"))
+ found = {}
+ for step in doc["jobs"]["prepare"]["steps"]:
+ if step.get("id") in RESOLVER_STEPS:
+ found[step["id"]] = step["run"]
+ missing = set(RESOLVER_STEPS) - set(found)
+ assert not missing, f"resolver steps missing from the prepare job: {missing}"
+ return found
+
+
+def test_the_workflow_never_pins_a_shell_so_bash_e_has_no_pipefail(steps: dict):
+ # `shell: bash` would switch the runner to `-eo pipefail`; until then the guards
+ # below are the only protection
+ doc = yaml.safe_load(WORKFLOW.read_text(encoding = "utf-8"))
+ assert "shell" not in doc.get("defaults", {}).get("run", {}), (
+ "this test models the default `bash -e` shell; update it if a default "
+ "shell with pipefail is introduced"
+ )
+
+
[email protected]("step_id", RESOLVER_STEPS)
+def test_an_unreachable_remote_fails_the_step(steps: dict, step_id: str, tmp_path: Path):
+ script = _expand(steps[step_id])
+ res = _run_with_failing_ls_remote(script, tmp_path)
+ assert res.returncode != 0, (
+ "a transport failure must fail the prepare job, not fall through to the "
+ f"mutable ref:\nstdout={res.stdout}\nstderr={res.stderr}"
+ )
+
+
[email protected]("step_id", RESOLVER_STEPS)
+def test_an_unreachable_remote_never_emits_a_mutable_ref(steps: dict, step_id: str, tmp_path: Path):
+ script = _expand(steps[step_id])
+ res = _run_with_failing_ls_remote(script, tmp_path)
+ emitted = (
+ (tmp_path / "github_output").read_text(encoding = "utf-8")
+ if (tmp_path / "github_output").exists()
+ else ""
+ )
+ for line in emitted.splitlines():
+ key, _, value = line.partition("=")
+ assert re.fullmatch(r"[0-9a-f]{40}", value), (
+ f"{step_id} published {key}={value!r}, which the three builds each "
+ "resolve again, so they can bake different revisions"
+ )
+ assert res.returncode != 0
+
+
+# Same hole in the llama tag step, where `bash -e` without pipefail takes the exit
+# status of the trailing `sed`. `tag=latest` is NOT a pin: every consumer re-resolves
+# it, so a release published mid-run puts two bundles under one manifest.
+
+
[email protected](scope = "module")
+def llama_step() -> str:
+ doc = yaml.safe_load(WORKFLOW.read_text(encoding = "utf-8"))
+ for step in doc["jobs"]["prepare"]["steps"]:
+ if step.get("id") == "llama":
+ return step["run"]
+ raise AssertionError("the llama tag resolver step is missing from the prepare job")
+
+
+def test_an_unresolvable_llama_release_fails_the_step(llama_step: str, tmp_path: Path):
+ res = _run_llama_step(llama_step, tmp_path, curl_exit = 6)
+ assert res.returncode != 0, (
+ "a failed /releases/latest lookup must fail the prepare job:\n"
+ f"stdout={res.stdout}\nstderr={res.stderr}"
+ )
+
+
+def test_an_unresolvable_llama_release_never_emits_a_mutable_tag(llama_step: str, tmp_path: Path):
+ res = _run_llama_step(llama_step, tmp_path, curl_exit = 6)
+ emitted = (tmp_path / "github_output").read_text(encoding = "utf-8")
+ assert "latest" not in emitted, (
+ f"the step published {emitted.strip()!r}; every consumer resolves that "
+ "mutable tag again, so the two arch legs and Studio can bake different "
+ "llama.cpp versions under one manifest"
+ )
+ assert res.returncode != 0
+
+
+def test_a_resolved_llama_release_is_forwarded_verbatim(llama_step: str, tmp_path: Path):
+ res = _run_llama_step(llama_step, tmp_path, curl_exit = 0)
+ assert res.returncode == 0, f"stdout={res.stdout}\nstderr={res.stderr}"
+ assert (tmp_path / "github_output").read_text(encoding = "utf-8").strip() == (
+ "tag=b10107-mix-1911198"
+ )
+
+
+def _run_llama_step(script: str, tmp_path: Path, *, curl_exit: int):
+ bin_dir = tmp_path / "bin"
+ bin_dir.mkdir(parents = True, exist_ok = True)
+ stub = bin_dir / "curl"
+ if curl_exit:
+ stub.write_text(
+ "#!/usr/bin/env bash\n"
+ 'echo "curl: (6) Could not resolve host: github.com" >&2\n'
+ f"exit {curl_exit}\n",
+ encoding = "utf-8",
+ )
+ else:
+ stub.write_text(
+ "#!/usr/bin/env bash\n"
+ "printf '%s' "
+ "'https://github.com/unslothai/llama.cpp/releases/tag/b10107-mix-1911198'\n",
+ encoding = "utf-8",
+ )
+ stub.chmod(0o755)
+ out = tmp_path / "github_output"
+ out.write_text("", encoding = "utf-8")
+ env = dict(os.environ)
+ env["PATH"] = f"{bin_dir}{os.pathsep}" + env["PATH"]
+ env["GITHUB_OUTPUT"] = str(out)
+ env["INPUT_TAG"] = "" # the default (push / schedule) trigger
+ path = tmp_path / "llama_step.sh"
+ path.write_text(_expand(script), encoding = "utf-8")
+ return subprocess.run(
+ ["bash", "-e", str(path)],
+ capture_output = True,
+ text = True,
+ env = env,
+ timeout = 60,
+ )
+
+
+def _expand(run: str) -> str:
+ return re.sub(r"\$\{\{[^}]*\}\}", "", run)
+
+
+def _run_with_failing_ls_remote(script: str, tmp_path: Path):
+ bin_dir = tmp_path / "bin"
+ bin_dir.mkdir(parents = True, exist_ok = True)
+ stub = bin_dir / "git"
+ stub.write_text(
+ "#!/usr/bin/env bash\n"
+ 'if [ "$1" = "ls-remote" ]; then\n'
+ ' echo "fatal: unable to access: Could not resolve host" >&2\n'
+ " exit 128\n"
+ "fi\n"
+ "exit 0\n",
+ encoding = "utf-8",
+ )
+ stub.chmod(0o755)
+ out = tmp_path / "github_output"
+ out.write_text("", encoding = "utf-8")
+ env = dict(os.environ)
+ env["PATH"] = f"{bin_dir}{os.pathsep}" + env["PATH"]
+ env["GITHUB_OUTPUT"] = str(out)
+ for name in ("INPUT_REF", "TAG_REF", "PUSH_SHA"):
+ env[name] = ""
+ path = tmp_path / "step.sh"
+ path.write_text(script, encoding = "utf-8")
+ return subprocess.run(
+ ["bash", "-e", str(path)],
+ capture_output = True,
+ text = True,
+ env = env,
+ timeout = 60,
+ )
+
+
+# git documents status 2 for "talked to the remote, no matching refs" and any other
+# non-zero for "never reached it", so treating every non-zero as "tag absent" lets a
+# transient DNS/TLS failure pair the unsloth tag with zoo `main`.
+
+ZOO_TAG = "v2026.9.1"
+ZOO_MAIN_SHA = "1" * 40
+ZOO_TAG_SHA = "2" * 40
+
+
+def _expand_tag_trigger(run: str) -> str:
+ run = run.replace("${{ github.event.inputs.unsloth_zoo_ref }}", "")
+ run = run.replace("${{ startsWith(github.ref, 'refs/tags/') }}", "true")
+ run = run.replace("${{ github.ref_name }}", ZOO_TAG)
+ return re.sub(r"\$\{\{[^}]*\}\}", "", run)
+
+
+def _run_zoo_step(script: str, tmp_path: Path, *, probe_exit: int):
+ bin_dir = tmp_path / "bin"
+ bin_dir.mkdir(parents = True, exist_ok = True)
+ stub = bin_dir / "git"
+ stub.write_text(
+ "#!/usr/bin/env bash\n"
+ 'for a in "$@"; do\n'
+ ' if [ "$a" = "--exit-code" ]; then\n'
+ + (
+ ' echo "fatal: unable to access: Could not resolve host" >&2\n'
+ if probe_exit not in (0, 2)
+ else ""
+ )
+ + f" exit {probe_exit}\n"
+ " fi\n"
+ "done\n"
+ 'if [ "${!#}" = "main" ]; then\n'
+ f' printf "%s\\trefs/heads/main\\n" "{ZOO_MAIN_SHA}"\n'
+ "else\n"
+ f' printf "%s\\trefs/tags/{ZOO_TAG}\\n" "{ZOO_TAG_SHA}"\n'
+ "fi\n"
+ "exit 0\n",
+ encoding = "utf-8",
+ )
+ stub.chmod(0o755)
+ out = tmp_path / "github_output"
+ out.write_text("", encoding = "utf-8")
+ env = dict(os.environ)
+ env["PATH"] = f"{bin_dir}{os.pathsep}" + env["PATH"]
+ env["GITHUB_OUTPUT"] = str(out)
+ path = tmp_path / "zoo_step.sh"
+ path.write_text(_expand_tag_trigger(script), encoding = "utf-8")
+ res = subprocess.run(
+ ["bash", "-e", str(path)],
+ capture_output = True,
+ text = True,
+ env = env,
+ timeout = 60,
+ )
+ return res, out.read_text(encoding = "utf-8")
+
+
+def test_an_unreachable_zoo_probe_fails_instead_of_taking_main(steps: dict, tmp_path: Path):
+ res, emitted = _run_zoo_step(steps["zoo_ref"], tmp_path, probe_exit = 128)
+ assert res.returncode != 0, (
+ "a transport failure in the tag probe must fail the prepare job; taking "
+ "'main' pairs the requested unsloth tag with an unrelated zoo revision:\n"
+ f"stdout={res.stdout}\nstderr={res.stderr}"
+ )
+ assert f"ref={ZOO_MAIN_SHA}" not in emitted, emitted
+
+
+def test_a_missing_zoo_tag_still_falls_back_to_main(steps: dict, tmp_path: Path):
+ # git's "reached the remote, no matching refs" status: the common case
+ res, emitted = _run_zoo_step(steps["zoo_ref"], tmp_path, probe_exit = 2)
+ assert res.returncode == 0, f"stdout={res.stdout}\nstderr={res.stderr}"
+ assert emitted.strip() == f"ref={ZOO_MAIN_SHA}", emitted
+
+
+def test_a_present_zoo_tag_is_mirrored(steps: dict, tmp_path: Path):
+ res, emitted = _run_zoo_step(steps["zoo_ref"], tmp_path, probe_exit = 0)
+ assert res.returncode == 0, f"stdout={res.stdout}\nstderr={res.stderr}"
+ assert emitted.strip() == f"ref={ZOO_TAG_SHA}", emitted
+
+
+# build-studio FROMs the digest this step exports. metadata-action sorts tags by
+# priority (raw=200 above sha=100), so `.tags[0]` on a main push is the MUTABLE
+# `:core`, which an unserialised second run can retag before this inspection.
+
+OTHER_RUN_DIGEST = "sha256:" + "a" * 64
+THIS_RUN_DIGEST = "sha256:" + "b" * 64
+IMAGE = "docker.io/unsloth/unsloth"
+
+# the per-arch digests this run pushed, one file per digest in /tmp/digests
+ARCH_DIGESTS = ("a" * 64, "c" * 64)
+
+
+def _digests_dir(tmp_path: Path, digests = ARCH_DIGESTS) -> Path:
+ d = tmp_path / "digests"
+ d.mkdir(parents = True, exist_ok = True)
+ for h in digests:
+ (d / h).write_text("", encoding = "utf-8")
+ return d
+
+
+def _docker_stub(bin_dir: Path, body: str) -> None:
+ bin_dir.mkdir(parents = True, exist_ok = True)
+ stub = bin_dir / "docker"
+ stub.write_text("#!/usr/bin/env bash\n" + body, encoding = "utf-8")
+ stub.chmod(0o755)
+
+
+def _raw_index(children = ARCH_DIGESTS) -> str:
+ inner = ",".join('{\\"digest\\":\\"sha256:%s\\"}' % h for h in children)
+ return '{\\"manifests\\":[' + inner + "]}"
+
+
[email protected](scope = "module")
+def manifest_digest_step() -> str:
+ doc = yaml.safe_load(WORKFLOW.read_text(encoding = "utf-8"))
+ for step in doc["jobs"]["merge"]["steps"]:
+ if step.get("id") == "manifest_digest":
+ return step["run"]
+ raise AssertionError("the manifest digest export step is missing from the merge job")
+
+
[email protected](shutil.which("jq") is None, reason = "needs jq")
+def test_the_exported_digest_comes_from_this_runs_tag(manifest_digest_step: str, tmp_path: Path):
+ bin_dir = tmp_path / "bin"
+ _docker_stub(
+ bin_dir,
+ 'case "$4" in\n'
+ f' --raw) printf "{_raw_index()}" ;;\n'
+ f" *core-sha-*) printf '\"{THIS_RUN_DIGEST}\"' ;;\n"
+ f" *) printf '\"{OTHER_RUN_DIGEST}\"' ;;\n"
+ "esac\n",
+ )
+ out = tmp_path / "github_output"
+ out.write_text("", encoding = "utf-8")
+ env = dict(os.environ)
+ env["PATH"] = f"{bin_dir}{os.pathsep}" + env["PATH"]
+ env["GITHUB_OUTPUT"] = str(out)
+ env["DOCKER_METADATA_OUTPUT_JSON"] = (
+ '{"tags":["' + IMAGE + ':core","' + IMAGE + ':core-sha-abc1234"]}'
+ )
+ path = tmp_path / "digest_step.sh"
+ path.write_text(_expand(manifest_digest_step), encoding = "utf-8")
+ res = subprocess.run(
+ ["bash", "-e", str(path)],
+ capture_output = True,
+ text = True,
+ env = env,
+ timeout = 60,
+ cwd = str(_digests_dir(tmp_path)),
+ )
+ assert res.returncode == 0, f"stdout={res.stdout}\nstderr={res.stderr}"
+ assert out.read_text(encoding = "utf-8").strip() == f"digest={THIS_RUN_DIGEST}", (
+ "the step read the digest through the mutable :core tag, so an overlapping "
+ "main run can hand build-studio another commit's base image"
+ )
+
+
[email protected](shutil.which("jq") is None, reason = "needs jq")
+def test_the_digest_export_still_works_without_a_sha_tag(manifest_digest_step: str, tmp_path: Path):
+ bin_dir = tmp_path / "bin"
+ _docker_stub(
+ bin_dir,
+ 'case "$4" in\n'
+ f' --raw) printf "{_raw_index()}" ;;\n'
+ f" *) printf '\"{THIS_RUN_DIGEST}\"' ;;\n"
+ "esac\n",
+ )
+ out = tmp_path / "github_output"
+ out.write_text("", encoding = "utf-8")
+ env = dict(os.environ)
+ env["PATH"] = f"{bin_dir}{os.pathsep}" + env["PATH"]
+ env["GITHUB_OUTPUT"] = str(out)
+ env["DOCKER_METADATA_OUTPUT_JSON"] = '{"tags":["' + IMAGE + ':core-v2026.9.1"]}'
+ path = tmp_path / "digest_step.sh"
+ path.write_text(_expand(manifest_digest_step), encoding = "utf-8")
+ res = subprocess.run(
+ ["bash", "-e", str(path)],
+ capture_output = True,
+ text = True,
+ env = env,
+ timeout = 60,
+ cwd = str(_digests_dir(tmp_path)),
+ )
+ assert res.returncode == 0, f"stdout={res.stdout}\nstderr={res.stderr}"
+ assert out.read_text(encoding = "utf-8").strip() == f"digest={THIS_RUN_DIGEST}"
+
+
[email protected](shutil.which("jq") is None, reason = "needs jq")
+def test_the_digest_export_refuses_another_runs_manifest(manifest_digest_step: str, tmp_path: Path):
+ """:core-sha- is immutable across COMMITS but not across REFS: a branch push and a
+ lightweight v* tag push at one commit produce the same short sha and land in
+ different concurrency groups, so both write this name and neither waits. If the
+ tag resolves to a manifest that does not contain the per-arch digests this run
+ pushed, the step has to fail rather than hand build-studio another run's base."""
+ bin_dir = tmp_path / "bin"
+ # the tag now resolves to a manifest built from somebody else's arches
+ _docker_stub(
+ bin_dir,
+ 'case "$4" in\n'
+ f' --raw) printf "{_raw_index(("d" * 64, "e" * 64))}" ;;\n'
+ f" *) printf '\"{THIS_RUN_DIGEST}\"' ;;\n"
+ "esac\n",
+ )
+ out = tmp_path / "github_output"
+ out.write_text("", encoding = "utf-8")
+ env = dict(os.environ)
+ env["PATH"] = f"{bin_dir}{os.pathsep}" + env["PATH"]
+ env["GITHUB_OUTPUT"] = str(out)
+ env["DOCKER_METADATA_OUTPUT_JSON"] = (
+ '{"tags":["' + IMAGE + ':core","' + IMAGE + ':core-sha-abc1234"]}'
+ )
+ path = tmp_path / "digest_step.sh"
+ path.write_text(_expand(manifest_digest_step), encoding = "utf-8")
+ res = subprocess.run(
+ ["bash", "-e", str(path)],
+ capture_output = True,
+ text = True,
+ env = env,
+ timeout = 60,
+ cwd = str(_digests_dir(tmp_path)),
+ )
+ assert res.returncode != 0, (
+ "the step accepted a manifest that does not contain this run's arches, so an "
+ "overlapping ref at the same commit silently becomes the published base:\n"
+ + res.stdout
+ + res.stderr
+ )
+ assert "digest=" not in out.read_text(
+ encoding = "utf-8"
+ ), "a digest was exported despite the mismatch"
diff --git a/tests/python/test_docker_run_kernel_cwd.py b/tests/python/test_docker_run_kernel_cwd.py
new file mode 100644
index 00000000000..4d3f17eaaf4
--- /dev/null
+++ b/tests/python/test_docker_run_kernel_cwd.py
@@ -0,0 +1,109 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved.
+
+"""`--out` must not move the notebook's execution directory.
+
+nbconvert derives the kernel's working directory from the INPUT notebook's path
+(``Exporter.from_filename`` sets ``resources["metadata"]["path"]`` to its dirname,
+which nbclient passes to the kernel as cwd), so staging the input beside ``--out``
+made every relative ``open()``, local import and save inside the notebook resolve
+against the OUTPUT tree instead of the tree the notebook lives in.
+"""
+
+from __future__ import annotations
+
+import importlib.util
+import json
+import os
+import sys
+from pathlib import Path
+
+import pytest
+
+REPO_ROOT = Path(__file__).resolve().parents[2]
+RUNNER_PATH = REPO_ROOT / "docker" / "unsloth_run.py"
+
+NOTEBOOK = {
+ "cells": [{"cell_type": "code", "source": ["print(1)\n"], "metadata": {}, "outputs": []}],
+ "metadata": {},
+ "nbformat": 4,
+ "nbformat_minor": 5,
+}
+
+
+def runner(tmp_path, monkeypatch):
+ monkeypatch.setenv("UNSLOTH_NB_TF_MARKER", str(tmp_path / "marker"))
+ spec = importlib.util.spec_from_file_location("unsloth_run_cwd_under_test", RUNNER_PATH)
+ mod = importlib.util.module_from_spec(spec)
+ spec.loader.exec_module(mod)
+ return mod
+
+
+def _run(runner, monkeypatch, argv):
+ seen = {}
+
+ def stub(cmd, env = None):
+ # the input notebook is the positional argument before --output
+ seen["input"] = cmd[cmd.index("--output") - 1]
+ out_dir = cmd[cmd.index("--output-dir") + 1]
+ name = cmd[cmd.index("--output") + 1]
+ with open(os.path.join(out_dir, name), "w", encoding = "utf-8") as f:
+ json.dump(NOTEBOOK, f)
+ return 0
+
+ monkeypatch.setattr(runner.subprocess, "call", stub)
+ monkeypatch.setattr(runner.sys, "argv", ["unsloth-run", *argv])
+ with pytest.raises(SystemExit) as exc:
+ runner.main()
+ assert exc.value.code == 0
+ return seen["input"]
+
+
+def test_a_local_notebook_executes_from_its_own_directory(runner, monkeypatch, tmp_path):
+ src_dir = tmp_path / "project"
+ src_dir.mkdir()
+ src = src_dir / "in.ipynb"
+ src.write_text(json.dumps(NOTEBOOK), encoding = "utf-8")
+ (src_dir / "data.json").write_text("{}", encoding = "utf-8")
+ out = tmp_path / "results" / "out.ipynb"
+
+ given = _run(runner, monkeypatch, [str(src), "--out", str(out)])
+
+ assert Path(os.path.dirname(os.path.abspath(given))) == src_dir, (
+ f"nbconvert was handed {given}; its dirname is the kernel cwd, so the "
+ "notebook's relative paths would resolve against the --out tree"
+ )
+ assert out.is_file(), "the result still has to be published at --out"
+ assert not list(out.parent.glob(".unsloth-run-in-*")), "no input staged beside --out"
+
+
+def test_the_source_directory_is_not_written_to(runner, monkeypatch, tmp_path):
+ src_dir = tmp_path / "project"
+ src_dir.mkdir()
+ src = src_dir / "in.ipynb"
+ src.write_text(json.dumps(NOTEBOOK), encoding = "utf-8")
+ out = tmp_path / "results" / "out.ipynb"
+
+ _run(runner, monkeypatch, [str(src), "--out", str(out)])
+
+ assert sorted(p.name for p in src_dir.iterdir()) == [
+ "in.ipynb"
+ ], "executing in place must not leave staging files in the user's tree"
+ assert json.loads(src.read_text(encoding = "utf-8")) == NOTEBOOK, "input left unmodified"
+
+
+def test_a_url_notebook_still_runs_beside_out(runner, monkeypatch, tmp_path):
+ """A URL has no source tree; --out stays the run's working directory."""
+ monkeypatch.setattr(runner, "_load", lambda *_args, **_kwargs: json.loads(json.dumps(NOTEBOOK)))
+ out = tmp_path / "results" / "out.ipynb"
+
+ given = _run(runner, monkeypatch, ["https://example.invalid/x.ipynb", "--out", str(out)])
+
+ assert Path(os.path.dirname(os.path.abspath(given))) == out.parent
+ assert out.is_file()
+ assert not list(out.parent.glob(".unsloth-run-in-*")), "the staged input is cleaned up"
+
+
+if __name__ == "__main__":
+ sys.exit(pytest.main([__file__, "-v"]))
diff --git a/tests/python/test_docker_run_output_publish.py b/tests/python/test_docker_run_output_publish.py
new file mode 100644
index 00000000000..b885251484b
--- /dev/null
+++ b/tests/python/test_docker_run_output_publish.py
@@ -0,0 +1,232 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-Present the Unsloth team. See /studio/LICENSE.AGPL-3.0
+
+"""`unsloth-run --out` must publish an output the host user can read.
+
+tempfile.mkstemp() creates the staging file 0600, nbconvert writes its result by
+TRUNCATING the same inode, and os.replace is a rename, so that root-owned 0600 is
+carried onto the destination -- and re-running over an existing output replaces that
+file's mode and owner too.
+"""
+
+from __future__ import annotations
+
+import errno
+import importlib.util
+import json
+import os
+import stat
+import sys
+from pathlib import Path
+
+import pytest
+
+REPO_ROOT = Path(__file__).resolve().parents[2]
+RUNNER_PATH = REPO_ROOT / "docker" / "unsloth_run.py"
+
+NOTEBOOK = {
+ "cells": [{"cell_type": "code", "source": ["print(1)\n"], "metadata": {}, "outputs": []}],
+ "metadata": {},
+ "nbformat": 4,
+ "nbformat_minor": 5,
+}
+
+
+def runner(tmp_path, monkeypatch):
+ monkeypatch.setenv("UNSLOTH_NB_TF_MARKER", str(tmp_path / "marker"))
+ assert RUNNER_PATH.is_file(), f"missing runner: {RUNNER_PATH}"
+ spec = importlib.util.spec_from_file_location("unsloth_run_under_test", RUNNER_PATH)
+ mod = importlib.util.module_from_spec(spec)
+ spec.loader.exec_module(mod)
+ return mod
+
+
+def _nbconvert_stub(cmd, env = None):
+ out_dir = cmd[cmd.index("--output-dir") + 1]
+ name = cmd[cmd.index("--output") + 1]
+ with open(os.path.join(out_dir, name), "w", encoding = "utf-8") as f:
+ json.dump(NOTEBOOK, f)
+ return 0
+
+
+def _run(runner, monkeypatch, src, out):
+ monkeypatch.setattr(runner.subprocess, "call", _nbconvert_stub)
+ monkeypatch.setattr(runner.sys, "argv", ["unsloth-run", str(src), "--out", str(out)])
+ with pytest.raises(SystemExit) as exc:
+ runner.main()
+ assert exc.value.code == 0
+
+
+def _mode(path):
+ return stat.S_IMODE(os.stat(path).st_mode)
+
+
+def notebook(tmp_path):
+ src = tmp_path / "in.ipynb"
+ src.write_text(json.dumps(NOTEBOOK), encoding = "utf-8")
+ return src
+
+
+def test_a_new_output_is_not_published_as_0600(runner, monkeypatch, tmp_path, notebook):
+ out = tmp_path / "out.ipynb"
+ _run(runner, monkeypatch, notebook, out)
+ assert out.is_file()
+ umask = os.umask(0)
+ os.umask(umask)
+ assert _mode(out) == 0o666 & ~umask, (
+ f"published mode {oct(_mode(out))}; the mkstemp 0600 survives os.replace, "
+ "so a root container publishes an output the host user cannot read"
+ )
+ assert json.loads(out.read_text(encoding = "utf-8"))["cells"], "the result must survive"
+
+
+def test_an_existing_outputs_mode_is_preserved(runner, monkeypatch, tmp_path, notebook):
+ out = tmp_path / "out.ipynb"
+ out.write_text("{}", encoding = "utf-8")
+ os.chmod(out, 0o664)
+ _run(runner, monkeypatch, notebook, out)
+ assert (
+ _mode(out) == 0o664
+ ), f"re-running replaced the existing output's mode with {oct(_mode(out))}"
+
+
[email protected](os.geteuid() != 0, reason = "chown to another uid needs root")
+def test_an_existing_outputs_ownership_is_preserved(runner, monkeypatch, tmp_path, notebook):
+ out = tmp_path / "out.ipynb"
+ out.write_text("{}", encoding = "utf-8")
+ os.chown(out, 1000, 1000)
+ _run(runner, monkeypatch, notebook, out)
+ st = os.stat(out)
+ assert (st.st_uid, st.st_gid) == (1000, 1000), "the host user lost their own output file"
+
+
+def test_no_staging_files_are_left_behind(runner, monkeypatch, tmp_path, notebook):
+ out = tmp_path / "out.ipynb"
+ _run(runner, monkeypatch, notebook, out)
+ leftovers = [p.name for p in tmp_path.iterdir() if p.name.startswith(".unsloth-run-")]
+ assert not leftovers, leftovers
+
+
+def test_every_created_level_is_chowned_to_the_nearest_existing_ancestor(
+ runner, monkeypatch, tmp_path
+):
+ # mkdir(2) uses the CALLER's uid, so a new `sub/dir` is root-owned and
+ # _stage_metadata then gives the OUTPUT that owner too. Recorded, not observed:
+ # chowning to another uid needs root.
+ anchor = os.stat(tmp_path)
+ chowned = []
+ monkeypatch.setattr(runner.os, "chown", lambda p, u, g: chowned.append((str(p), u, g)))
+
+ runner._makedirs_as_host(str(tmp_path / "sub" / "dir"))
+
+ assert [p for p, _, _ in chowned] == [
+ str(tmp_path / "sub"),
+ str(tmp_path / "sub" / "dir"),
+ ], "both created levels must be fixed, outermost first"
+ assert {(u, g) for _, u, g in chowned} == {(anchor.st_uid, anchor.st_gid)}
+
+
+def test_the_ancestor_is_the_nearest_one_that_exists(runner, monkeypatch, tmp_path):
+ # the deepest EXISTING directory, not the mount root: a user can own
+ # /workspace/host/projectA without owning everything above it
+ base = tmp_path / "exists"
+ base.mkdir()
+ chowned = []
+ monkeypatch.setattr(runner.os, "chown", lambda p, u, g: chowned.append(str(p)))
+
+ runner._makedirs_as_host(str(base / "a" / "b"))
+
+ assert chowned == [str(base / "a"), str(base / "a" / "b")]
+
+
[email protected](os.geteuid() != 0, reason = "chown to another uid needs root")
+def test_the_output_in_a_created_directory_is_not_root_owned(
+ runner, monkeypatch, tmp_path, notebook
+):
+ host = tmp_path / "host"
+ host.mkdir()
+ os.chown(host, 1000, 1000)
+ out = host / "results" / "run" / "out.ipynb"
+
+ _run(runner, monkeypatch, notebook, out)
+
+ for path in (host / "results", host / "results" / "run", out):
+ st = os.stat(path)
+ assert (st.st_uid, st.st_gid) == (1000, 1000), path
+
+
+def test_an_existing_output_directory_is_left_alone(runner, tmp_path):
+ existing = tmp_path / "already"
+ existing.mkdir()
+ before = os.stat(existing)
+ runner._makedirs_as_host(str(existing))
+ after = os.stat(existing)
+ assert (after.st_uid, after.st_gid, after.st_mode) == (
+ before.st_uid,
+ before.st_gid,
+ before.st_mode,
+ )
+
+
+# A bind-mounted OUTPUT FILE makes the destination a mount point, and rename(2) onto
+# one returns EBUSY even though the file is writable, so the cleanup then deleted a
+# finished run's result. Simulated by raising the kernel's errno.
+
+
+def _replace_raising(errno_value):
+ def _replace(src, dst):
+ raise OSError(errno_value, os.strerror(errno_value))
+
+ return _replace
+
+
+def test_a_busy_destination_still_gets_the_executed_notebook(
+ runner, monkeypatch, tmp_path, notebook
+):
+ out = tmp_path / "out.ipynb"
+ out.write_text("{}", encoding = "utf-8")
+ os.chmod(out, 0o664)
+ monkeypatch.setattr(runner.os, "replace", _replace_raising(errno.EBUSY))
+
+ _run(runner, monkeypatch, notebook, out)
+
+ assert json.loads(out.read_text(encoding = "utf-8"))["cells"], (
+ "the rename cannot work on a single-file bind mount, but the file itself "
+ "is writable, so the finished notebook must still reach the user"
+ )
+ # writing through the existing inode is what a bind mount needs
+ assert _mode(out) == 0o664
+ leftovers = [p.name for p in tmp_path.iterdir() if p.name.startswith(".unsloth-run-")]
+ assert not leftovers, leftovers
+
+
+def test_an_unpublishable_result_is_kept_and_its_location_printed(
+ runner, monkeypatch, tmp_path, notebook, capsys
+):
+ out = tmp_path / "out.ipynb"
+ monkeypatch.setattr(runner.os, "replace", _replace_raising(errno.EBUSY))
+
+ def _no_open(
+ path,
+ mode = "r",
+ *args,
+ **kwargs,
+ ):
+ if str(path) == str(out) and "w" in mode:
+ raise OSError(errno.EACCES, os.strerror(errno.EACCES))
+ return _real_open(path, mode, *args, **kwargs)
+
+ _real_open = open
+ monkeypatch.setattr(runner.subprocess, "call", _nbconvert_stub)
+ monkeypatch.setattr(runner.sys, "argv", ["unsloth-run", str(notebook), "--out", str(out)])
+ monkeypatch.setitem(runner.__dict__, "open", _no_open)
+
+ with pytest.raises(OSError):
+ runner.main()
+
+ staged = [p for p in tmp_path.iterdir() if p.name.startswith(".unsloth-run-out-")]
+ assert len(staged) == 1, "an executed notebook that cannot be published must be kept"
+ assert json.loads(staged[0].read_text(encoding = "utf-8"))["cells"]
+ assert str(staged[0]) in capsys.readouterr().err
diff --git a/tests/python/test_docker_run_pin_scan.py b/tests/python/test_docker_run_pin_scan.py
new file mode 100644
index 00000000000..0ca0070fc60
--- /dev/null
+++ b/tests/python/test_docker_run_pin_scan.py
@@ -0,0 +1,349 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-Present the Unsloth team. See /studio/LICENSE.AGPL-3.0
+
+"""`unsloth-run` must take its transformers pin from an install, not from prose.
+
+`_scan` used to regex the ENTIRE source of every code cell, so a commented-out install
+line outranked the model tier and launched the kernel a tier short of the model it was
+about to load -- and no install runs, so the pip shim never corrects it either.
+
+The fix must not narrow the scan too far: most shipped notebooks carry a pin, many on
+the CONTINUATION line of a multi-line `!uv pip install \\` or indented inside the
+`if "COLAB_" not in ...` guard. Those shapes are pinned below verbatim.
+"""
+
+from __future__ import annotations
+
+import importlib.util
+import json
+import os
+import sys
+from pathlib import Path
+from types import SimpleNamespace
+
+import pytest
+
+REPO_ROOT = Path(__file__).resolve().parents[2]
+RUN_PATH = REPO_ROOT / "docker" / "unsloth_run.py"
+
+
+def _load_run(sidecar_root):
+ prev = {k: os.environ.get(k) for k in ("UNSLOTH_TF_SIDECAR_ROOT", "UNSLOTH_TF_SIDECAR_MIN")}
+ os.environ["UNSLOTH_TF_SIDECAR_ROOT"] = str(sidecar_root)
+ os.environ.pop("UNSLOTH_TF_SIDECAR_MIN", None)
+ stale = sys.modules.pop("unsloth_nb_compat", None)
+ try:
+ spec = importlib.util.spec_from_file_location("unsloth_run_under_test", RUN_PATH)
+ mod = importlib.util.module_from_spec(spec)
+ spec.loader.exec_module(mod)
+ finally:
+ sys.modules.pop("unsloth_nb_compat", None)
+ if stale is not None:
+ sys.modules["unsloth_nb_compat"] = stale
+ for k, v in prev.items():
+ if v is None:
+ os.environ.pop(k, None)
+ else:
+ os.environ[k] = v
+ return mod
+
+
+def sidecar_root(tmp_path):
+ root = tmp_path / "tf-sidecars"
+ for name in ("t_5_5_0", "t_5_10_2"):
+ (root / name).mkdir(parents = True)
+ (root / ".vllm_min_transformers").write_text("5.5.0\n")
+ return root
+
+
+def run_mod(sidecar_root):
+ return _load_run(sidecar_root)
+
+
+def _nb(*sources):
+ return {
+ "cells": [
+ {
+ "cell_type": "code",
+ "source": s,
+ "metadata": {},
+ "outputs": [],
+ "execution_count": None,
+ }
+ for s in sources
+ ],
+ "metadata": {"kernelspec": {"name": "python3", "language": "python", "display_name": "Py"}},
+ "nbformat": 4,
+ "nbformat_minor": 5,
+ }
+
+
+GEMMA4_12B = 'model, tok = FastModel.from_pretrained("unsloth/gemma-4-12b-it")\n'
+
+
+ "cell",
+ [
+ pytest.param(
+ "# !pip install --no-deps transformers==4.57.6\n!pip install unsloth\n",
+ id = "commented-out-install",
+ ),
+ pytest.param(
+ "!pip install unsloth # was transformers==4.57.6 before the 5.x bump\n",
+ id = "trailing-comment",
+ ),
+ pytest.param(
+ '"""Colab used to need transformers==4.57.6 here."""\n!pip install unsloth\n',
+ id = "docstring",
+ ),
+ pytest.param(
+ 'print("upgrade from transformers==4.57.6 if you hit an import error")\n',
+ id = "string-literal",
+ ),
+ pytest.param(
+ "_legacy = 'transformers==4.57.6' # no longer applied\n!pip install unsloth\n",
+ id = "assigned-but-unused",
+ ),
+ pytest.param(
+ " # !uv pip install transformers==4.57.6\n!pip install unsloth\n",
+ id = "indented-comment",
+ ),
+ ],
+)
+def test_a_mention_that_installs_nothing_is_not_a_pin(run_mod, cell):
+ pin, model = run_mod._scan(_nb(cell, GEMMA4_12B))
+ assert pin is None, f"{pin!r} came from text that never runs an install"
+ assert model == "unsloth/gemma-4-12b-it"
+
+
+ "cell, expected",
+ [
+ pytest.param(
+ '!pip install --no-deps transformers==5.10.1 "tokenizers>=0.22.0"\n',
+ "5.10.1",
+ id = "bang-pip",
+ ),
+ pytest.param("%pip install transformers==5.5.0\n", "5.5.0", id = "percent-pip"),
+ pytest.param("!pip3 install transformers==5.5.0\n", "5.5.0", id = "pip3"),
+ pytest.param('!uv pip install --system -qqq "transformers==5.2.0"\n', "5.2.0", id = "uv-pip"),
+ pytest.param("!python -m pip install transformers==5.3.0\n", "5.3.0", id = "python-m-pip"),
+ pytest.param(
+ "!{sys.executable} -m pip install transformers==5.3.0\n", "5.3.0", id = "sys-executable"
+ ),
+ pytest.param("!pip -q install transformers==5.5.0\n", "5.5.0", id = "opt-before-install"),
+ pytest.param("pip install transformers==5.5.0\n", "5.5.0", id = "bare-shell-cell"),
+ pytest.param(
+ # the pin on a backslash continuation, several lines below the invocation
+ "!uv pip install -qqq \\\n"
+ ' {_torch} "triton>=3.3.0" {_numpy} torchvision bitsandbytes "transformers==4.56.2" \\\n'
+ ' "unsloth[base] @ git+https://github.com/unslothai/unsloth"\n',
+ "4.56.2",
+ id = "backslash-continuation",
+ ),
+ pytest.param(
+ # installs indented inside the Colab guard
+ "%%capture\n"
+ "import os\n"
+ 'if "COLAB_" not in "".join(os.environ.keys()):\n'
+ " !pip install unsloth\n"
+ "else:\n"
+ " !pip install --no-deps transformers==5.10.1\n",
+ "5.10.1",
+ id = "indented-inside-guard",
+ ),
+ ],
+)
+def test_real_install_shapes_still_yield_their_pin(run_mod, cell, expected):
+ assert run_mod._scan(_nb(cell))[0] == expected
+
+
+def test_an_install_still_outranks_the_model_tier(run_mod):
+ # a REAL install must keep outranking the tier; only prose stops counting
+ pin, model = run_mod._scan(_nb("!pip install transformers==5.5.0\n", GEMMA4_12B))
+ assert (pin, model) == ("5.5.0", "unsloth/gemma-4-12b-it")
+
+
+def _launch(run_mod, monkeypatch, tmp_path, nb, name):
+ """What the kernel would see at launch; the per-run marker is a temp file main()
+ deletes on the way out, so it has to be read there."""
+ src = tmp_path / f"{name}.ipynb"
+ src.write_text(json.dumps(nb))
+ seen = {}
+
+ def fake_call(
+ cmd,
+ env = None,
+ **kwargs,
+ ):
+ seen["cmd"] = cmd
+ seen["env"] = dict(env or {})
+ marker = seen["env"].get("UNSLOTH_NB_TF_MARKER")
+ seen["marker"] = Path(marker).read_text().strip() if marker else None
+ return 0
+
+ monkeypatch.setattr(run_mod, "subprocess", SimpleNamespace(call = fake_call))
+ monkeypatch.setattr(sys, "argv", ["unsloth-run", str(src)])
+ monkeypatch.delenv("UNSLOTH_NB_TF_MARKER", raising = False)
+ with pytest.raises(SystemExit) as exc:
+ run_mod.main()
+ assert exc.value.code == 0
+ return seen
+
+
+def _sidecars_on_path(env):
+ return [
+ Path(p).name
+ for p in env.get("PYTHONPATH", "").split(os.pathsep)
+ if Path(p).name.startswith("t_")
+ ]
+
+
+def test_a_stale_commented_pin_does_not_downgrade_the_kernel(run_mod, monkeypatch, tmp_path):
+ nb = _nb(
+ "# legacy Colab workaround, no longer needed:\n"
+ "# !pip install --no-deps transformers==4.57.6\n"
+ "!pip install unsloth\n",
+ GEMMA4_12B,
+ )
+ seen = _launch(run_mod, monkeypatch, tmp_path, nb, "stale")
+ assert _sidecars_on_path(seen["env"]) == ["t_5_10_2"], (
+ "the dead comment must not outrank the gemma-4-12b tier; 5.5.0 predates "
+ "gemma4-unified, which landed in transformers 5.10.1"
+ )
+ assert seen["marker"] == "5.10.2"
+
+
+def test_a_clean_notebook_is_unaffected(run_mod, monkeypatch, tmp_path):
+ seen = _launch(
+ run_mod, monkeypatch, tmp_path, _nb("!pip install unsloth\n", GEMMA4_12B), "clean"
+ )
+ assert _sidecars_on_path(seen["env"]) == ["t_5_10_2"]
+ assert seen["marker"] == "5.10.2"
+
+
+def test_a_real_pin_still_drives_the_kernel(run_mod, monkeypatch, tmp_path):
+ nb = _nb("!pip install --no-deps transformers==5.10.1\n", GEMMA4_12B)
+ seen = _launch(run_mod, monkeypatch, tmp_path, nb, "pinned")
+ assert _sidecars_on_path(seen["env"]) == ["t_5_10_2"]
+ assert seen["marker"] == "5.10.1"
+
+
+# `--timeout` only ever reached nbconvert, so a URL host that accepted the connection
+# and then went quiet hung unsloth-run before a single cell had executed.
+
+
+def test_a_url_fetch_is_bounded(run_mod, monkeypatch):
+ seen = {}
+
+ class _Response:
+ def __enter__(self):
+ return self
+
+ def __exit__(self, *a):
+ return False
+
+ def read(self):
+ return b'{"cells": [], "metadata": {}, "nbformat": 4, "nbformat_minor": 5}'
+
+ def _urlopen(url, *args, **kwargs):
+ seen["url"] = url
+ seen["timeout"] = kwargs.get("timeout", args[2] if len(args) > 2 else None)
+ return _Response()
+
+ monkeypatch.setattr(run_mod.urllib.request, "urlopen", _urlopen)
+
+ run_mod._load("https://example.invalid/x.ipynb")
+ assert seen["timeout"] == run_mod.DEFAULT_FETCH_TIMEOUT
+ assert seen["timeout"] is not None and seen["timeout"] > 0
+
+ run_mod._load("https://example.invalid/x.ipynb", fetch_timeout = 7)
+ assert seen["timeout"] == 7
+
+
+def test_the_stall_limit_is_separate_from_the_execution_budget(run_mod):
+ """--timeout is nbconvert's whole-notebook budget, an hour by default; reusing it
+ for the download would mean an hour of silence before the first cell."""
+ source = (REPO_ROOT / "docker" / "unsloth_run.py").read_text(encoding = "utf-8")
+ assert "--fetch-timeout" in source
+ assert run_mod.DEFAULT_FETCH_TIMEOUT < 3600
+
+
+def test_a_local_path_is_not_given_a_timeout(run_mod, tmp_path):
+ """Only the URL branch changed; a local file must still open normally."""
+ path = tmp_path / "x.ipynb"
+ path.write_text(
+ json.dumps({"cells": [], "metadata": {}, "nbformat": 4, "nbformat_minor": 5}),
+ encoding = "utf-8",
+ )
+ assert run_mod._load(str(path)) == {
+ "cells": [],
+ "metadata": {},
+ "nbformat": 4,
+ "nbformat_minor": 5,
+ }
+
+
+# The IPython startup hook gives every kernel its own UNSLOTH_NB_TF_MARKER, so
+# `!unsloth-run nb.ipynb` from a notebook cell inherits the CALLER's marker. Honouring
+# it corrupts both sides: the target's pin overwrites the caller kernel's, and a target
+# with no pin runs against the caller's stale pin. A kernel that has not imported
+# transformers yet then activates the wrong sidecar.
+def _launch_with_inherited_marker(run_mod, monkeypatch, tmp_path, nb, caller_pin):
+ src = tmp_path / "target.ipynb"
+ src.write_text(json.dumps(nb))
+ caller = tmp_path / "caller_kernel_marker"
+ caller.write_text(caller_pin)
+ seen = {}
+
+ def fake_call(
+ cmd,
+ env = None,
+ **kwargs,
+ ):
+ seen["env"] = dict(env or {})
+ m = seen["env"].get("UNSLOTH_NB_TF_MARKER")
+ seen["marker_path"] = m
+ seen["child_reads"] = Path(m).read_text().strip() if m and os.path.exists(m) else None
+ return 0
+
+ monkeypatch.setattr(run_mod, "subprocess", SimpleNamespace(call = fake_call))
+ monkeypatch.setattr(sys, "argv", ["unsloth-run", str(src)])
+ monkeypatch.setenv("UNSLOTH_NB_TF_MARKER", str(caller))
+ with pytest.raises(SystemExit) as exc:
+ run_mod.main()
+ assert exc.value.code == 0
+ seen["caller_after"] = caller.read_text().strip()
+ seen["caller_path"] = str(caller)
+ return seen
+
+
+def test_a_run_does_not_overwrite_the_calling_kernels_marker(run_mod, monkeypatch, tmp_path):
+ seen = _launch_with_inherited_marker(
+ run_mod,
+ monkeypatch,
+ tmp_path,
+ _nb("!pip install transformers==5.5.0\n"),
+ caller_pin = "5.10.2",
+ )
+ assert seen["marker_path"] != seen["caller_path"], "the run reused the caller's marker"
+ assert (
+ seen["caller_after"] == "5.10.2"
+ ), "the target's pin was written into the CALLER kernel's marker"
+ assert seen["child_reads"] == "5.5.0", seen
+
+
+def test_an_unpinned_target_does_not_inherit_the_callers_pin(run_mod, monkeypatch, tmp_path):
+ seen = _launch_with_inherited_marker(
+ run_mod,
+ monkeypatch,
+ tmp_path,
+ _nb("print('no install here')\n"),
+ caller_pin = "5.10.2",
+ )
+ assert seen["marker_path"] != seen["caller_path"]
+ assert not seen[
+ "child_reads"
+ ], f"the target has no pin, but the kernel was handed {seen['child_reads']!r}"
diff --git a/tests/python/test_docker_single_compile_worker_options.py b/tests/python/test_docker_single_compile_worker_options.py
new file mode 100644
index 00000000000..6d2f11be784
--- /dev/null
+++ b/tests/python/test_docker_single_compile_worker_options.py
@@ -0,0 +1,179 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-Present the Unsloth team. See /studio/LICENSE.AGPL-3.0
+
+"""Regression guard for the pinned-device single-compile-worker block.
+
+The trap: that block runs AFTER `import unsloth_zoo`, which has already built its
+module-level Inductor options dicts from the original thread count. Those snapshots go
+to torch.compile as `options`, which Inductor applies as a config patch outranking
+both TORCHINDUCTOR_COMPILE_THREADS and config.compile_threads, so replacing
+determine_compile_threads alone leaves every already-decorated compile site unguarded.
+
+The guard block is extracted from the shipped source and run against a synthetic
+unsloth_zoo module graph, so this exercises the real code rather than a copy.
+"""
+
+from __future__ import annotations
+
+import functools
+import importlib
+import os
+import re
+import sys
+import types
+from pathlib import Path
+
+import pytest
+
+REPO_ROOT = Path(__file__).resolve().parents[2]
+GPU_INIT = REPO_ROOT / "unsloth" / "_gpu_init.py"
+
+SENTINEL = "UNSLOTH_FORCE_SINGLE_COMPILE_WORKER"
+ORIGINAL_THREADS = 32 # what determine_compile_threads() returns on a 32+ core host
+
+
[email protected](scope = "module")
+def gpu_init_source() -> str:
+ assert GPU_INIT.is_file(), f"missing {GPU_INIT}"
+ return GPU_INIT.read_text(encoding = "utf-8")
+
+
[email protected](scope = "module")
+def guard_block(gpu_init_source: str) -> str:
+ start = re.search(
+ r'^if os\.environ\.get\("%s", "0"\) == "1":$' % SENTINEL,
+ gpu_init_source,
+ re.MULTILINE,
+ )
+ assert start, "the single-compile-worker guard block disappeared"
+ lines = gpu_init_source[start.start() :].splitlines()
+ block = [lines[0]]
+ for line in lines[1:]:
+ if line and not line.startswith((" ", "\t")):
+ break
+ block.append(line)
+ return "\n".join(block) + "\n"
+
+
+def test_guard_runs_after_unsloth_zoo_is_imported(gpu_init_source: str):
+ zoo_import = re.search(r"^ import unsloth_zoo$", gpu_init_source, re.MULTILINE)
+ guard = re.search(
+ r'^if os\.environ\.get\("%s", "0"\) == "1":$' % SENTINEL,
+ gpu_init_source,
+ re.MULTILINE,
+ )
+ assert zoo_import and guard
+ assert zoo_import.start() < guard.start()
+
+
+def _install_fake_zoo(monkeypatch) -> dict:
+ """The zoo's post-import state in its real shapes: one shared dict re-exported by
+ several modules, per-model dicts, and a partial closing over the shared one."""
+ shared = {"epilogue_fusion": True, "compile_threads": ORIGINAL_THREADS}
+ fused = {"triton.cudagraphs": True, "compile_threads": ORIGINAL_THREADS}
+ no_combo = {"combo_kernels": False, "compile_threads": ORIGINAL_THREADS}
+ unrelated = {"compile_threads": ORIGINAL_THREADS} # in a non-zoo module
+
+ def _fake_determine_compile_threads():
+ return ORIGINAL_THREADS
+
+ zoo = types.ModuleType("unsloth_zoo")
+ patches = types.ModuleType("unsloth_zoo.temporary_patches")
+ common = types.ModuleType("unsloth_zoo.temporary_patches.common")
+ gpt_oss = types.ModuleType("unsloth_zoo.temporary_patches.gpt_oss")
+ loss_utils = types.ModuleType("unsloth_zoo.loss_utils")
+ outsider = types.ModuleType("some_other_package")
+
+ common.determine_compile_threads = _fake_determine_compile_threads
+ common.torch_compile_options = shared
+ common.torch_compile = functools.partial(lambda *a, **k: None, options = shared)
+ gpt_oss.fused_torch_compile_options = fused
+ gpt_oss.no_combo_fused_torch_compile_options = no_combo
+ loss_utils.torch_compile_options = shared # same object, re-exported
+ patches.torch_compile_options = shared
+ outsider.torch_compile_options = unrelated
+
+ for module in (zoo, patches, common, gpt_oss, loss_utils, outsider):
+ monkeypatch.setitem(sys.modules, module.__name__, module)
+
+ return {
+ "shared": shared,
+ "fused": fused,
+ "no_combo": no_combo,
+ "unrelated": unrelated,
+ "common": common,
+ }
+
+
+def _run_guard(guard_block: str, monkeypatch) -> dict:
+ state = _install_fake_zoo(monkeypatch)
+ monkeypatch.setenv(SENTINEL, "1")
+ monkeypatch.delenv("TORCHINDUCTOR_COMPILE_THREADS", raising = False)
+
+ fake_torch = types.SimpleNamespace(
+ _inductor = types.SimpleNamespace(
+ config = types.SimpleNamespace(compile_threads = ORIGINAL_THREADS)
+ )
+ )
+ namespace = {
+ "os": os,
+ "sys": sys,
+ "importlib": importlib,
+ "torch": fake_torch,
+ "__builtins__": __builtins__,
+ }
+ exec(compile(guard_block, str(GPU_INIT), "exec"), namespace)
+ state["torch"] = fake_torch
+ return state
+
+
+def test_cached_options_dicts_are_rewritten(guard_block: str, monkeypatch):
+ state = _run_guard(guard_block, monkeypatch)
+
+ assert state["shared"]["compile_threads"] == 1, (
+ "common.torch_compile_options is a snapshot built during `import "
+ "unsloth_zoo`; left at %d it is passed to torch.compile as `options` and "
+ "spawns the compile workers the guard exists to prevent" % ORIGINAL_THREADS
+ )
+ assert state["fused"]["compile_threads"] == 1
+ assert state["no_combo"]["compile_threads"] == 1
+ assert state["common"].torch_compile.keywords["options"]["compile_threads"] == 1
+
+
+def test_guard_still_sets_env_config_and_function(guard_block: str, monkeypatch):
+ state = _run_guard(guard_block, monkeypatch)
+
+ assert os.environ["TORCHINDUCTOR_COMPILE_THREADS"] == "1"
+ assert state["torch"]._inductor.config.compile_threads == 1
+ assert state["common"].determine_compile_threads() == 1
+
+
+def test_guard_leaves_non_zoo_modules_alone(guard_block: str, monkeypatch):
+ state = _run_guard(guard_block, monkeypatch)
+ assert state["unrelated"]["compile_threads"] == ORIGINAL_THREADS
+
+
+def test_guard_is_a_no_op_when_the_user_opted_out(guard_block: str, monkeypatch):
+ state = _install_fake_zoo(monkeypatch)
+ monkeypatch.delenv(SENTINEL, raising = False)
+ monkeypatch.delenv("TORCHINDUCTOR_COMPILE_THREADS", raising = False)
+
+ fake_torch = types.SimpleNamespace(
+ _inductor = types.SimpleNamespace(
+ config = types.SimpleNamespace(compile_threads = ORIGINAL_THREADS)
+ )
+ )
+ exec(
+ compile(guard_block, str(GPU_INIT), "exec"),
+ {
+ "os": os,
+ "sys": sys,
+ "importlib": importlib,
+ "torch": fake_torch,
+ "__builtins__": __builtins__,
+ },
+ )
+
+ assert state["shared"]["compile_threads"] == ORIGINAL_THREADS
+ assert fake_torch._inductor.config.compile_threads == ORIGINAL_THREADS
+ assert "TORCHINDUCTOR_COMPILE_THREADS" not in os.environ
diff --git a/tests/python/test_docker_studio_launch_view_config.py b/tests/python/test_docker_studio_launch_view_config.py
new file mode 100644
index 00000000000..bf751d5c36a
--- /dev/null
+++ b/tests/python/test_docker_studio_launch_view_config.py
@@ -0,0 +1,151 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-Present the Unsloth team. See /studio/LICENSE.AGPL-3.0
+
+"""The notebook-view paths must survive being written into a Python config.
+
+`studio_launch.sh` appends three settings to `jupyter_lab_config.py` built from
+`UNSLOTH_NOTEBOOKS_VIEW_DIR`. Interpolated straight into a heredoc's string
+literals, a path containing a double quote closed the literal and made the
+config a SyntaxError, so the documented override stopped JupyterLab from
+starting at all; a backslash silently produced a different path, since Python
+reads `\\t` in a literal as a tab. Both characters are legal in a POSIX path.
+
+The generator block is extracted from the shipped script and run for real, then
+the result is compiled and executed the way Jupyter loads it, so the assertions
+are about what Jupyter would actually see rather than about the text.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+import shutil
+import subprocess
+import sys
+import types
+from pathlib import Path
+
+import pytest
+
+REPO_ROOT = Path(__file__).resolve().parents[2]
+LAUNCH = REPO_ROOT / "docker" / "studio_launch.sh"
+
+behavioural = pytest.mark.skipif(shutil.which("bash") is None, reason = "needs bash")
+
+
[email protected](scope = "module")
+def generator() -> str:
+ """The `python - >> ... <<'PY' ... PY` block, verbatim from the script."""
+ source = LAUNCH.read_text(encoding = "utf-8")
+ match = re.search(
+ r"^\s*UNSLOTH_VIEW_REL=.*?\n\s*python - >> .*?<<'PY'\n(.*?)\nPY$",
+ source,
+ re.S | re.M,
+ )
+ assert match, "the notebook-view config generator disappeared or changed shape"
+ return match.group(1)
+
+
+def _render(generator: str, rel: str, view: str) -> str:
+ result = subprocess.run(
+ [sys.executable, "-"],
+ input = generator,
+ capture_output = True,
+ text = True,
+ timeout = 120,
+ env = dict(os.environ, UNSLOTH_VIEW_REL = rel, UNSLOTH_VIEW_DIR = view),
+ )
+ assert result.returncode == 0, result.stdout + result.stderr
+ return result.stdout
+
+
+def _load(config_text: str):
+ """Execute the config the way Jupyter does, and hand back what it set."""
+
+ class _Node(types.SimpleNamespace):
+ pass
+
+ config = types.SimpleNamespace(
+ ServerApp = _Node(), LabApp = _Node(), PasswordIdentityProvider = _Node()
+ )
+ exec(compile(config_text, "jupyter_lab_config.py", "exec"), {"c": config})
+ return config
+
+
+NASTY = [
+ pytest.param('My "Special" Notebooks', id = "double-quote"),
+ pytest.param("Note\\tbooks", id = "backslash-t"),
+ pytest.param("Note'books", id = "single-quote"),
+ pytest.param("Note\\books", id = "trailing-backslash-segment"),
+ pytest.param("Unsloth Notebooks", id = "the-default"),
+]
+
+
[email protected]("name", NASTY)
+def test_the_config_stays_valid_python_and_keeps_the_path(generator: str, name: str):
+ view = f"/workspace/{name}"
+ rendered = _render(generator, name, view)
+
+ config = _load(rendered) # a SyntaxError here is the bug
+
+ assert (
+ config.ServerApp.preferred_dir == view
+ ), "the path Jupyter ends up with must be the one the user asked for"
+ assert config.ServerApp.default_url == f"/lab/tree/{name}"
+ assert (
+ config.LabApp.default_url == config.ServerApp.default_url
+ ), "LabApp otherwise overrides ServerApp back to /lab"
+
+
+def test_a_newline_in_the_path_cannot_inject_a_config_line(generator: str):
+ # A newline would end the statement outright and let the rest of the value
+ # be read as configuration.
+ name = 'x"\nc.ServerApp.token = "pwned'
+ config = _load(_render(generator, name, f"/workspace/{name}"))
+
+ assert config.ServerApp.preferred_dir == f"/workspace/{name}"
+ assert not hasattr(config.ServerApp, "token"), "the value was executed as config"
+
+
+def test_the_generator_does_not_interpolate_the_paths_in_the_shell(generator: str):
+ # The heredoc delimiter has to stay quoted and the values have to arrive
+ # through the environment; an unquoted heredoc puts the shell's expansion
+ # back in front of python's quoting and the fix is undone.
+ source = LAUNCH.read_text(encoding = "utf-8")
+ assert "python - >> \"${JUPYTER_CONFIG_DIR}/jupyter_lab_config.py\" <<'PY'" in source
+ assert "${_view_rel}" not in generator and "${_view_dir}" not in generator
+ assert 'os.environ["UNSLOTH_VIEW_REL"]' in generator
+ assert 'os.environ["UNSLOTH_VIEW_DIR"]' in generator
+
+
+@behavioural
+def test_the_heredoc_form_this_replaced_really_was_broken(tmp_path: Path):
+ """Pin the premise, so the test above is not guarding a hypothetical.
+
+ Reproduces the previous construct exactly: an unquoted heredoc interpolating
+ the value into a Python string literal. With a double quote in the path the
+ generated config does not parse, which is JupyterLab failing to start.
+ """
+ name = 'My "Special" Notebooks'
+ script = tmp_path / "old.sh"
+ script.write_text(
+ "#!/usr/bin/env bash\n"
+ '_view_rel="$1"\n'
+ '_view_dir="$2"\n'
+ "cat <<EOF\n"
+ 'c.ServerApp.default_url = "/lab/tree/${_view_rel}"\n'
+ 'c.LabApp.default_url = "/lab/tree/${_view_rel}"\n'
+ 'c.ServerApp.preferred_dir = "${_view_dir}"\n'
+ "EOF\n",
+ encoding = "utf-8",
+ )
+ result = subprocess.run(
+ ["bash", str(script), name, f"/workspace/{name}"],
+ capture_output = True,
+ text = True,
+ timeout = 120,
+ )
+ assert result.returncode == 0, result.stderr
+
+ with pytest.raises(SyntaxError):
+ compile(result.stdout, "jupyter_lab_config.py", "exec")
diff --git a/tests/python/test_docker_tf_sidecar_vllm_floor.py b/tests/python/test_docker_tf_sidecar_vllm_floor.py
new file mode 100644
index 00000000000..5f36fd9a4a0
--- /dev/null
+++ b/tests/python/test_docker_tf_sidecar_vllm_floor.py
@@ -0,0 +1,195 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-Present the Unsloth team. See /studio/LICENSE.AGPL-3.0
+
+"""Regression guard for transformers-sidecar selection in the Unsloth Docker image.
+
+Selection was a pure CEILING, ignoring that vLLM is version-locked to transformers, so
+the sidecars the common pins selected could not be imported by the baked vLLM at all.
+
+The FLOOR in front of it is measured, not hardcoded: the Dockerfile imports
+vllm.transformers_utils.config (the vLLM module that reads the transformers API, and
+it needs no GPU, which the build host lacks) under every candidate.
+"""
+
+from __future__ import annotations
+
+import importlib.util
+import re
+from pathlib import Path
+
+import pytest
+
+REPO_ROOT = Path(__file__).resolve().parents[2]
+DOCKERFILE = REPO_ROOT / "docker" / "Dockerfile"
+COMPAT_PATH = REPO_ROOT / "docker" / "unsloth_nb_compat.py"
+
+# every distinct pin across the shipped notebooks -> the sidecar it must resolve to
+SHIPPED_PINS = [
+ "4.48",
+ "4.52.3",
+ "4.55.4",
+ "4.56.1",
+ "4.56.2",
+ "4.57.0",
+ "4.57.1",
+ "4.57.3",
+ "5.2.0",
+ "5.3.0",
+ "5.5.0",
+ "5.10.1",
+ "5.11.0",
+]
+
+
[email protected](scope = "module")
+def dockerfile() -> str:
+ assert DOCKERFILE.is_file(), f"missing {DOCKERFILE}"
+ return DOCKERFILE.read_text(encoding = "utf-8")
+
+
[email protected](scope = "module")
+def sidecar_block(dockerfile: str) -> str:
+ start = dockerfile.index("tf-sidecars/t_$(echo")
+ block = dockerfile[dockerfile.rindex("RUN set -eux", 0, start) :]
+ return block[: block.index("\n\n")]
+
+
+def _load_compat(root, floor = None):
+ import os
+
+ prev_root = os.environ.get("UNSLOTH_TF_SIDECAR_ROOT")
+ prev_min = os.environ.get("UNSLOTH_TF_SIDECAR_MIN")
+ os.environ["UNSLOTH_TF_SIDECAR_ROOT"] = str(root)
+ os.environ.pop("UNSLOTH_TF_SIDECAR_MIN", None)
+ try:
+ spec = importlib.util.spec_from_file_location("unsloth_nb_compat_under_test", COMPAT_PATH)
+ mod = importlib.util.module_from_spec(spec)
+ spec.loader.exec_module(mod)
+ finally:
+ if prev_root is None:
+ os.environ.pop("UNSLOTH_TF_SIDECAR_ROOT", None)
+ else:
+ os.environ["UNSLOTH_TF_SIDECAR_ROOT"] = prev_root
+ if prev_min is not None:
+ os.environ["UNSLOTH_TF_SIDECAR_MIN"] = prev_min
+ return mod
+
+
+def fixed_root(tmp_path):
+ for name in ("t_5_5_0", "t_5_10_2"):
+ (tmp_path / name).mkdir()
+ (tmp_path / ".vllm_min_transformers").write_text("5.5.0\n")
+ return tmp_path
+
+
+def stale_root(tmp_path):
+ for name in ("t_4_57_6", "t_5_3_0", "t_5_5_0", "t_5_10_2"):
+ (tmp_path / name).mkdir()
+ (tmp_path / ".vllm_min_transformers").write_text("5.5.0\n")
+ return tmp_path
+
+
+def test_build_verifies_every_sidecar_against_the_baked_vllm(sidecar_block: str):
+ assert "import vllm.transformers_utils.config" in sidecar_block, (
+ "each baked sidecar must be proven importable by the baked vLLM; this is "
+ "the module that reads the transformers API and it reproduces both the "
+ "v4 refusal and the ALLOWED_LAYER_TYPES break"
+ )
+
+
+def test_build_verification_needs_no_gpu(sidecar_block: str):
+ # `import unsloth` raises on the GPU-less build host, so it cannot be the gate
+ assert (
+ "import unsloth" not in sidecar_block
+ ), "the sidecar gate must not import unsloth: the build host has no GPU"
+
+
+def test_an_unverifiable_sidecar_is_deleted_not_shipped(sidecar_block: str):
+ assert re.search(r"DROPPED", sidecar_block), "a failed candidate must be reported"
+ assert re.search(r'rm -rf "\$DEST"', sidecar_block), (
+ "a sidecar the baked vLLM cannot import must be removed, not shipped: it "
+ "can never be selected safely and it costs image size"
+ )
+
+
+def test_build_records_the_selection_floor(sidecar_block: str):
+ assert (
+ ".vllm_min_transformers" in sidecar_block
+ ), "the lowest verified version must be recorded for unsloth_nb_compat"
+ assert "sort -V | head -1" in sidecar_block, "the floor is the LOWEST survivor"
+
+
+def test_build_fails_when_no_sidecar_survives(sidecar_block: str):
+ assert "exit 1" in sidecar_block, (
+ "an empty sidecar set means the whole per-notebook mechanism is dead; "
+ "that must fail the build rather than ship silently"
+ )
+
+
+def test_build_skips_the_gate_when_vllm_is_absent(sidecar_block: str):
+ # the vLLM install is fail-soft per arch, and with no vLLM there is no constraint
+ assert "HAVE_VLLM" in sidecar_block
+
+
+def test_compat_reads_the_floor_the_build_writes():
+ assert ".vllm_min_transformers" in COMPAT_PATH.read_text(encoding = "utf-8"), (
+ "unsloth_nb_compat must read the floor the Dockerfile records, not a "
+ "literal that rots on the next vLLM bump"
+ )
+
+
+def test_floor_is_read_back(fixed_root):
+ assert _load_compat(fixed_root).min_version() == "5.5.0"
+
+
+ "pin, expected",
+ [
+ ("4.48", "t_5_5_0"),
+ ("4.52.3", "t_5_5_0"),
+ ("4.55.4", "t_5_5_0"),
+ ("4.56.1", "t_5_5_0"),
+ ("4.56.2", "t_5_5_0"),
+ ("4.57.0", "t_5_5_0"),
+ ("4.57.1", "t_5_5_0"),
+ ("4.57.3", "t_5_5_0"),
+ ("5.2.0", "t_5_5_0"),
+ ("5.3.0", "t_5_5_0"),
+ ("5.5.0", "t_5_5_0"),
+ ("5.10.1", "t_5_10_2"),
+ ("5.11.0", None),
+ ],
+)
+def test_every_shipped_pin_resolves_to_a_vllm_compatible_sidecar(fixed_root, pin, expected):
+ got = _load_compat(fixed_root).sidecar_for(pin)
+ assert (Path(got).name if got else None) == expected
+
+
+def test_no_shipped_pin_can_reach_an_incompatible_sidecar(stale_root):
+ compat = _load_compat(stale_root)
+ for pin in SHIPPED_PINS:
+ got = compat.sidecar_for(pin)
+ name = Path(got).name if got else None
+ assert name not in (
+ "t_4_57_6",
+ "t_5_3_0",
+ ), f"pin {pin} selected {name}, which the baked vLLM cannot import"
+
+
+def test_model_tier_fallback_is_clamped_too(stale_root):
+ # a model TIER must not reach an ineligible sidecar either
+ compat = _load_compat(stale_root)
+ tier = compat.tier_for_model("unsloth/Qwen3-Next-80B-A3B")
+ assert tier == "5.3.0"
+ assert Path(compat.sidecar_for(tier)).name == "t_5_5_0"
+
+
+def test_an_unrecorded_floor_keeps_the_old_ceiling_behaviour(tmp_path):
+ # with no recorded floor, selection must not silently start dropping sidecars
+ for name in ("t_4_57_6", "t_5_5_0"):
+ (tmp_path / name).mkdir()
+ compat = _load_compat(tmp_path)
+ assert compat.min_version() is None
+ assert Path(compat.sidecar_for("4.56.2")).name == "t_4_57_6"
diff --git a/tests/python/test_docker_update_helpers.py b/tests/python/test_docker_update_helpers.py
new file mode 100644
index 00000000000..5dcd665728b
--- /dev/null
+++ b/tests/python/test_docker_update_helpers.py
@@ -0,0 +1,376 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-Present the Unsloth team. See /studio/LICENSE.AGPL-3.0
+
+"""Behavioural guards for the two in-container update helpers of the Docker image.
+
+* `unsloth-studio-update` only WARNED when the new backend failed to import, so a
+ release missing a `--no-deps` dependency replaced the healthy process with one that
+ cannot start; supervisord then lands in FATAL and never leaves it.
+* `unsloth-llama-update --check` reported "up to date" when it could not reach the
+ release feed, and its in-place rollback left new-release-only shared objects beside
+ the restored files, which ggml dlopen()s.
+"""
+
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+from pathlib import Path
+
+import pytest
+
+REPO_ROOT = Path(__file__).resolve().parents[2]
+STUDIO_UPDATE = REPO_ROOT / "docker" / "unsloth_studio_update.sh"
+LLAMA_UPDATE = REPO_ROOT / "docker" / "unsloth_llama_update.sh"
+
+pytestmark = pytest.mark.skipif(
+ shutil.which("bash") is None,
+ reason = "needs bash",
+)
+
+
+def _stub(directory: Path, name: str, body: str) -> None:
+ directory.mkdir(parents = True, exist_ok = True)
+ path = directory / name
+ path.write_text("#!/usr/bin/env bash\n" + body, encoding = "utf-8")
+ path.chmod(0o755)
+
+
+def _run(
+ script: Path,
+ args,
+ env,
+ cwd = None,
+):
+ return subprocess.run(
+ ["bash", str(script), *args],
+ capture_output = True,
+ text = True,
+ env = env,
+ cwd = cwd,
+ timeout = 120,
+ )
+
+
+def _studio_env(tmp_path: Path, *, import_ok: bool) -> dict:
+ home = tmp_path / "studio"
+ venv_bin = home / "unsloth_studio" / "bin"
+ venv_bin.mkdir(parents = True)
+ _stub(
+ venv_bin,
+ "python",
+ 'if [ "$1" = "-c" ]; then\n'
+ + (
+ " exit 0\n"
+ if import_ok
+ else ' case "$2" in *studio.backend.main*) exit 1;; esac\n exit 0\n'
+ )
+ + "fi\n"
+ 'if [ "$1" = "-m" ] && [ "$2" = "pip" ]; then\n'
+ ' if [ "$3" = "show" ]; then echo "Version: 2026.7.5"; exit 0; fi\n'
+ ' echo "STUB-PIP $*" >> "$STUB_LOG"; exit 0\n'
+ "fi\n"
+ "exit 0\n",
+ )
+ bin_dir = tmp_path / "bin"
+ _stub(
+ bin_dir,
+ "supervisorctl",
+ 'echo "STUB-SUPERVISORCTL $*" >> "$STUB_LOG"\n'
+ 'if [ "$1" = "status" ]; then exit 0; fi\nexit 0\n',
+ )
+ env = dict(os.environ)
+ env["PATH"] = f"{bin_dir}{os.pathsep}" + env["PATH"]
+ env["UNSLOTH_STUDIO_HOME"] = str(home)
+ env["STUB_LOG"] = str(tmp_path / "calls.log")
+ return env
+
+
+def test_studio_update_restarts_when_the_backend_imports(tmp_path: Path):
+ env = _studio_env(tmp_path, import_ok = True)
+ res = _run(STUDIO_UPDATE, [], env)
+ calls = Path(env["STUB_LOG"]).read_text() if Path(env["STUB_LOG"]).exists() else ""
+ assert res.returncode == 0, res.stderr
+ assert "STUB-SUPERVISORCTL restart studio" in calls, calls
+
+
+def test_studio_update_does_not_restart_into_a_backend_that_cannot_import(tmp_path: Path):
+ env = _studio_env(tmp_path, import_ok = False)
+ res = _run(STUDIO_UPDATE, [], env)
+ calls = Path(env["STUB_LOG"]).read_text() if Path(env["STUB_LOG"]).exists() else ""
+ assert "STUB-SUPERVISORCTL restart studio" not in calls, (
+ "restarting into code that cannot import kills a process that is serving "
+ "fine and parks supervisord's studio program in FATAL:\n" + calls
+ )
+ assert res.returncode != 0, "a broken update must not report success"
+ assert "--with-deps" in res.stderr, "the remedy must still be printed"
+
+
+def _zoo_ref_env(tmp_path: Path, *, git_exit: int) -> dict:
+ """`--ref` env whose stub `git ls-remote` exits with `git_exit`. git's codes:
+ 0 = has the ref, 2 = reached the remote with no match, 128 = never reached it."""
+ env = _studio_env(tmp_path, import_ok = True)
+ _stub(tmp_path / "bin", "git", f"exit {git_exit}\n")
+ return env
+
+
+def _zoo_spec(calls: str) -> str:
+ for line in calls.splitlines():
+ for token in line.split():
+ if token.startswith("git+https://github.com/unslothai/unsloth-zoo.git@"):
+ return token
+ return ""
+
+
+def test_studio_update_mirrors_the_ref_when_the_zoo_has_it(tmp_path: Path):
+ env = _zoo_ref_env(tmp_path, git_exit = 0)
+ res = _run(STUDIO_UPDATE, ["--ref", "v2026.7.5", "--no-restart"], env)
+ calls = Path(env["STUB_LOG"]).read_text() if Path(env["STUB_LOG"]).exists() else ""
+ assert res.returncode == 0, res.stderr
+ assert _zoo_spec(calls).endswith("@v2026.7.5#egg=unsloth_zoo"), calls
+
+
+def test_studio_update_falls_back_to_zoo_main_when_the_ref_is_absent(tmp_path: Path):
+ env = _zoo_ref_env(tmp_path, git_exit = 2)
+ res = _run(STUDIO_UPDATE, ["--ref", "v2026.7.5", "--no-restart"], env)
+ calls = Path(env["STUB_LOG"]).read_text() if Path(env["STUB_LOG"]).exists() else ""
+ assert res.returncode == 0, res.stderr
+ assert _zoo_spec(calls).endswith("@main#egg=unsloth_zoo"), calls
+ assert "has no ref" in res.stdout, res.stdout
+
+
+def test_studio_update_aborts_when_the_zoo_lookup_never_reached_the_remote(tmp_path: Path):
+ # treating 2 and 128 alike pairs the requested unsloth revision with an unrelated
+ # zoo one once the network recovers, across a private API
+ env = _zoo_ref_env(tmp_path, git_exit = 128)
+ res = _run(STUDIO_UPDATE, ["--ref", "v2026.7.5", "--no-restart"], env)
+ calls = Path(env["STUB_LOG"]).read_text() if Path(env["STUB_LOG"]).exists() else ""
+ assert "STUB-PIP" not in calls, "a transport failure must not install anything:\n" + calls
+ assert res.returncode != 0, "an unresolvable zoo ref must not report success"
+ assert "has no ref" not in res.stdout, (
+ "an unreachable remote must not be reported as a missing ref:\n" + res.stdout
+ )
+ assert "--zoo-ref" in res.stderr, "the remedy must be printed"
+
+
+def _llama_env(
+ tmp_path: Path,
+ *,
+ latest: str | None,
+ marker: str = '{"tag": "b1111-old"}',
+) -> dict:
+ install = tmp_path / "llama.cpp"
+ install.mkdir(parents = True)
+ (install / "UNSLOTH_PREBUILT_INFO.json").write_text(
+ marker + "\n",
+ encoding = "utf-8",
+ )
+ fetcher = tmp_path / "fetch_llama_prebuilt.py"
+ resolve = (
+ " raise RuntimeError('unreachable')\n" if latest is None else f" return {latest!r}\n"
+ )
+ fetcher.write_text(
+ "def resolve_latest_tag(repo):\n" + resolve,
+ encoding = "utf-8",
+ )
+ env = dict(os.environ)
+ env["UNSLOTH_LLAMA_CPP_PATH"] = str(install)
+ env["UNSLOTH_LLAMA_FETCHER"] = str(fetcher)
+ return env
+
+
+def _llama_check(tmp_path: Path, latest, **kwargs):
+ env = _llama_env(tmp_path, latest = latest, **kwargs)
+ return _run(LLAMA_UPDATE, ["--check"], env)
+
+
+def test_llama_check_reports_an_available_update(tmp_path: Path):
+ res = _llama_check(tmp_path, "b2222-new")
+ assert res.returncode == 0, res.stderr
+ assert "an update is available" in res.stdout
+
+
+def test_llama_check_reports_up_to_date(tmp_path: Path):
+ res = _llama_check(tmp_path, "b1111-old")
+ assert res.returncode == 0, res.stderr
+ assert "up to date" in res.stdout
+
+
+def test_llama_check_reads_the_full_release_tag_not_the_base_build(tmp_path: Path):
+ # the latest pointer is always the full tag_name, so reading the normalized "tag"
+ # first offers an update forever on an install that is already current
+ res = _llama_check(
+ tmp_path,
+ "b10715-mix-86bd2d3",
+ marker = '{"tag": "b10715", "release_tag": "b10715-mix-86bd2d3"}',
+ )
+ assert res.returncode == 0, res.stderr
+ assert "up to date" in res.stdout, (
+ "the installed release IS the latest release; reporting an update here nags "
+ "forever because applying it cannot change the comparison:\n" + res.stdout
+ )
+ assert "installed: b10715-mix-86bd2d3" in res.stdout, (
+ "the reported installed version must be the full release identity it is "
+ "compared against:\n" + res.stdout
+ )
+
+
+def test_llama_check_still_offers_a_genuinely_newer_release(tmp_path: Path):
+ res = _llama_check(
+ tmp_path,
+ "b10800-mix-aaaaaaa",
+ marker = '{"tag": "b10715", "release_tag": "b10715-mix-86bd2d3"}',
+ )
+ assert res.returncode == 0, res.stderr
+ assert "an update is available" in res.stdout
+
+
+def test_llama_check_does_not_claim_up_to_date_when_it_could_not_look(tmp_path: Path):
+ res = _llama_check(tmp_path, None)
+ assert "up to date" not in res.stdout, (
+ "--check exists to report update status; saying 'up to date' for a lookup "
+ "that never happened is the one answer it must never give:\n" + res.stdout
+ )
+ assert res.returncode != 0, "an unperformed check must not exit 0"
+ assert "UNKNOWN" in res.stdout + res.stderr
+
+
+def _llama_inplace_env(tmp_path: Path, old: list[str], new: list[str]) -> dict:
+ """An in-place (volume-mounted) install whose activation fails part-way."""
+ install = tmp_path / "llama.cpp"
+ install.mkdir(parents = True)
+ for name in old:
+ (install / name).write_text("OLD\n", encoding = "utf-8")
+ (install / "UNSLOTH_PREBUILT_INFO.json").write_text(
+ '{"tag": "b1111-old"}\n',
+ encoding = "utf-8",
+ )
+ fetcher = tmp_path / "fetch_llama_prebuilt.py"
+ fetcher.write_text(
+ "import os, sys\n"
+ "def resolve_latest_tag(repo):\n"
+ " return 'b2222-new'\n"
+ "if __name__ == '__main__':\n"
+ " dest = sys.argv[3]\n"
+ " os.makedirs(dest, exist_ok = True)\n"
+ f" for name in {new!r}:\n"
+ " open(os.path.join(dest, name), 'w').write('NEW\\n')\n"
+ " open(os.path.join(dest, 'UNSLOTH_PREBUILT_INFO.json'), 'w')"
+ '.write(\'{"tag": "b2222-new"}\\n\')\n',
+ encoding = "utf-8",
+ )
+ # fail the ACTIVATION move AFTER it moved the files: the mid-swap abort the
+ # rollback exists for
+ bin_dir = tmp_path / "bin"
+ _stub(
+ bin_dir,
+ "mv",
+ 'if [ "$1" = "-t" ] && [ "$2" = "$FAIL_MV_TARGET" ]; then\n'
+ " shift 2\n"
+ ' for _s in "$@"; do /bin/mv "$_s" "$FAIL_MV_TARGET/"; done\n'
+ " exit 1\n"
+ "fi\n"
+ 'exec /bin/mv "$@"\n',
+ )
+ env = dict(os.environ)
+ env["PATH"] = f"{bin_dir}{os.pathsep}" + env["PATH"]
+ env["UNSLOTH_LLAMA_CPP_PATH"] = str(install)
+ env["UNSLOTH_LLAMA_FETCHER"] = str(fetcher)
+ env["UNSLOTH_LLAMA_UPDATE_IN_PLACE"] = "1"
+ env["FAIL_MV_TARGET"] = str(install)
+ return env
+
+
+def test_llama_rollback_leaves_no_new_release_files_behind(tmp_path: Path):
+ # only in the new release, so the rollback loop over the BACKUP's entries cannot
+ # see it, and ggml would dlopen it against the restored older libggml-base.so
+ old = ["libggml-base.so", "libggml-cpu-icelake.so", "llama-cli"]
+ new = [
+ "libggml-base.so",
+ "libggml-cpu-icelake.so",
+ "llama-cli",
+ "libggml-hexagon.so",
+ "llama-mtmd-cli",
+ ]
+ env = _llama_inplace_env(tmp_path, old, new)
+ res = _run(LLAMA_UPDATE, [], env)
+ assert res.returncode != 0, "a failed swap must not report success"
+ install = tmp_path / "llama.cpp"
+ present = sorted(p.name for p in install.iterdir())
+ leftovers = [n for n in ("libggml-hexagon.so", "llama-mtmd-cli") if n in present]
+ assert not leftovers, f"new-release-only files survived the rollback: {leftovers} in {present}"
+ for name in old:
+ assert (
+ install / name
+ ).read_text() == "OLD\n", f"{name} was not restored from the backup: {present}"
+
+
+def test_llama_rollback_keeps_every_old_file_when_the_drain_is_interrupted(tmp_path: Path):
+ # the mirror image: mid-drain, the entries left in the install dir are the only copy
+ old = ["libggml-base.so", "libggml-cpu-icelake.so", "llama-cli", "llama-quantize"]
+ env = _llama_inplace_env(tmp_path, old, old)
+ install = tmp_path / "llama.cpp"
+ # fail the DRAIN after one source, so half the old tree is still in the install dir
+ _stub(
+ tmp_path / "bin",
+ "mv",
+ 'case "${1:-}:${2:-}" in\n'
+ " -t:*/.old.*)\n"
+ ' _t="$2"; shift 2\n'
+ ' [ $# -gt 0 ] && /bin/mv "$1" "$_t/"\n'
+ " exit 1;;\n"
+ "esac\n"
+ 'exec /bin/mv "$@"\n',
+ )
+ res = _run(LLAMA_UPDATE, [], env)
+ assert res.returncode != 0
+ survivors = sorted(p.name for p in install.rglob("*") if p.is_file())
+ for name in old:
+ assert name in survivors, f"{name} was lost during an interrupted drain: {survivors}"
+
+
+def _fetcher_module():
+ """Import the build-time fetcher by path; stdlib-only, with a __main__ guard."""
+ import importlib.util
+
+ path = REPO_ROOT / "docker" / "fetch_llama_prebuilt.py"
+ spec = importlib.util.spec_from_file_location("_fetch_llama_prebuilt", path)
+ module = importlib.util.module_from_spec(spec)
+ spec.loader.exec_module(module)
+ return module
+
+
+ "release_tag, expected",
+ [
+ ("b10715-mix-86bd2d3", "b10715"),
+ ("b10715", "b10715"),
+ (" b9596-mix-e6f2453 ", "b9596"),
+ ("not-a-build-tag", "not-a-build-tag"),
+ ],
+)
+def test_fetcher_normalizes_the_base_build_for_the_marker_tag(release_tag, expected):
+ # the same split install_llama_prebuilt.py writes, or the two installers disagree
+ assert _fetcher_module().base_build_tag(release_tag) == expected
+
+
+def test_a_failed_studio_update_says_the_venv_on_disk_is_already_replaced(tmp_path: Path):
+ """Not restarting protects the running process, and only the code it has already
+ imported: the backend defers thousands of imports, so a lazy one fails the same
+ way. The venv itself is under $UNSLOTH_STUDIO_HOME, which the header recommends
+ putting on a named volume, so the replacement also survives docker rm + docker run.
+ The message used to stop at "the running process keeps serving", which reads as
+ though nothing is wrong until the operator chooses to restart."""
+ env = _studio_env(tmp_path, import_ok = False)
+ res = _run(STUDIO_UPDATE, [], env)
+ assert res.returncode != 0, "a broken update must not report success"
+ err = res.stderr.lower()
+ assert "already replaced" in err, (
+ "the failure never says the on-disk environment has been overwritten:\n" + res.stderr
+ )
+ assert "fatal" in err, "the failure never says a restart parks Studio in FATAL:\n" + res.stderr
+ assert "unsloth_studio_home" in err or "persisted home" in err, (
+ "the failure never says a persisted Studio home keeps it broken across a "
+ "container recreate:\n" + res.stderr
+ )
diff --git a/tests/python/test_unsloth_nb_pip_magic.py b/tests/python/test_unsloth_nb_pip_magic.py
new file mode 100644
index 00000000000..07642d803a8
--- /dev/null
+++ b/tests/python/test_unsloth_nb_pip_magic.py
@@ -0,0 +1,73 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-Present the Unsloth team. See /studio/LICENSE.AGPL-3.0
+
+"""Regression tests for docker/unsloth_nb_pip_magic.py.
+
+The input transformer rewrites `!<python> -m pip|uv ...` to `!pip|uv ...` so it
+resolves to the PATH shim. Transformers see the RAW cell text (brace expansion
+happens later, in the system() path), so the braced and absolute-interpreter forms
+notebooks use to target the running kernel must be rewritten too.
+"""
+
+import importlib.util
+import pathlib
+
+_MOD_PATH = pathlib.Path(__file__).resolve().parents[2] / "docker" / "unsloth_nb_pip_magic.py"
+_spec = importlib.util.spec_from_file_location("unsloth_nb_pip_magic", _MOD_PATH)
+magic = importlib.util.module_from_spec(_spec)
+_spec.loader.exec_module(magic)
+
+
+def _rewrite(line):
+ return magic._rewrite_python_dash_m([line])[0]
+
+
+def test_literal_python_rewritten():
+ assert _rewrite("!python -m pip install peft\n") == "!pip install peft\n"
+
+
+def test_literal_python_version_rewritten():
+ assert _rewrite("!python3.12 -m pip install peft") == "!pip install peft"
+
+
+def test_sys_executable_braces_rewritten():
+ assert _rewrite("!{sys.executable} -m pip install peft\n") == "!pip install peft\n"
+
+
+def test_sys_executable_braces_quoted_rewritten():
+ assert _rewrite('!"{sys.executable}" -m pip install peft') == "!pip install peft"
+
+
+def test_sys_executable_braces_spaced_rewritten():
+ assert _rewrite("!{ sys.executable } -m pip install peft") == "!pip install peft"
+
+
+def test_absolute_interpreter_path_rewritten():
+ assert _rewrite("!/opt/unsloth-venv/bin/python -m pip install peft\n") == "!pip install peft\n"
+
+
+def test_absolute_interpreter_versioned_path_rewritten():
+ assert _rewrite("!/usr/bin/python3.11 -m uv pip install peft") == "!uv pip install peft"
+
+
+def test_quoted_interpreter_path_rewritten():
+ assert _rewrite('!"/opt/unsloth venv/bin/python" -m pip install peft') == "!pip install peft"
+
+
+def test_indent_preserved():
+ assert _rewrite(" !{sys.executable} -m pip install peft") == " !pip install peft"
+
+
+def test_python_script_not_rewritten():
+ line = "!python train.py --epochs 3"
+ assert _rewrite(line) == line
+
+
+def test_module_other_than_pip_not_rewritten():
+ line = "!python -m venv .venv"
+ assert _rewrite(line) == line
+
+
+def test_non_shell_line_not_rewritten():
+ line = "x = '{sys.executable} -m pip install peft'"
+ assert _rewrite(line) == line
diff --git a/tests/python/test_unsloth_pip_shim.py b/tests/python/test_unsloth_pip_shim.py
new file mode 100644
index 00000000000..3f5a293538e
--- /dev/null
+++ b/tests/python/test_unsloth_pip_shim.py
@@ -0,0 +1,1947 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-Present the Unsloth team. See /studio/LICENSE.AGPL-3.0
+
+"""Regression tests for docker/unsloth_pip_shim.py.
+
+Drives main() with UNSLOTH_NB_SHIM=1 and captures the os.execv command, so the
+assertions are on what actually reaches the real pip/uv.
+"""
+
+from __future__ import annotations
+
+import importlib.util
+import os
+import sys
+from pathlib import Path
+
+import pytest
+
+REPO_ROOT = Path(__file__).resolve().parents[2]
+SHIM_PATH = REPO_ROOT / "docker" / "unsloth_pip_shim.py"
+
+TORCH_WHEEL_URL = (
+ "https://download.pytorch.org/whl/cu128/torch-2.11.0%2Bcu128-cp312-cp312-linux_x86_64.whl"
+)
+
+
+class _Exec(Exception):
+ """Raised by the patched os.execv so main() stops here."""
+
+ def __init__(self, path, argv):
+ self.path = path
+ self.argv = list(argv)
+
+
+class _BakedImage:
+ """Stands in for _installed_names() on an image where every bake succeeded.
+
+ Only `in` is asked of the return value, so answering the prefix rule here keeps
+ nvidia-* wheels present too, which a plain set of _KEEP cannot express.
+ """
+
+ def __init__(self, mod):
+ self._mod = mod
+
+ def __contains__(self, name):
+ # transformers is baked too; it is out of _KEEP only because the sidecar
+ # replaces its VERSION rather than the distribution
+ if name == "transformers":
+ return True
+ return name in self._mod._KEEP or name.startswith(self._mod._KEEP_PREFIX)
+
+
+def shim(tmp_path, monkeypatch):
+ """Fresh shim copy, marker in tmp_path, os.execv patched to capture the exec."""
+ marker = tmp_path / "requested_transformers"
+ monkeypatch.setenv("UNSLOTH_NB_TF_MARKER", str(marker))
+ monkeypatch.setenv("UNSLOTH_NB_SHIM", "1")
+
+ assert SHIM_PATH.is_file(), f"missing shim: {SHIM_PATH}"
+ spec = importlib.util.spec_from_file_location("unsloth_pip_shim_under_test", SHIM_PATH)
+ mod = importlib.util.module_from_spec(spec)
+ spec.loader.exec_module(mod)
+
+ def _fake_execv(path, argv):
+ raise _Exec(path, argv)
+
+ monkeypatch.setattr(mod.os, "execv", _fake_execv)
+ # the shim now skips a protected package only when it is really installed, so pin
+ # the fully baked image here: otherwise these assertions read the CI venv, which
+ # has no torchcodec, and pass or fail on the runner rather than on the shim
+ monkeypatch.setattr(mod, "_installed_names", lambda: _BakedImage(mod))
+ mod._marker_path = marker
+ return mod
+
+
+def _run(shim, tool, args):
+ """(args after `install` that reached the real tool or None, recorded transformers
+ version or None). The injected trailing `--constraint <file>` pair is stripped."""
+ if tool == "uv":
+ argv = ["uv", "pip", "install", *args]
+ else:
+ argv = ["pip", "install", *args]
+ with pytest.MonkeyPatch.context() as mp:
+ mp.setattr(shim.sys, "argv", argv)
+ try:
+ shim.main()
+ execd = None
+ except _Exec as exc:
+ i = exc.argv.index("install")
+ execd = exc.argv[i + 1 :]
+ if (
+ len(execd) >= 2
+ and execd[-2] == "--constraint"
+ and os.path.basename(execd[-1]).startswith("unsloth-nb-protected-")
+ ):
+ execd = execd[:-2]
+ marker = shim._marker_path.read_text() if shim._marker_path.exists() else None
+ return execd, marker
+
+
+UNSLOTH_VCS = "git+https://github.com/unslothai/unsloth.git#egg=unsloth"
+
+KEPT = object()
+
+
+ "args, expected",
+ [
+ pytest.param(["-e", UNSLOTH_VCS, "snac"], ["snac"], id = "sep-protected"),
+ # a protected editable drops the flag WITH its value: never a dangling `-e`
+ pytest.param(["-e", UNSLOTH_VCS], None, id = "sep-only-protected-noop"),
+ pytest.param(["-e", "./localpkg"], KEPT, id = "sep-unprotected-kept"),
+ pytest.param(["--editable=" + UNSLOTH_VCS, "snac"], ["snac"], id = "inline-protected"),
+ pytest.param(["--editable=./localpkg"], KEPT, id = "inline-unprotected-kept"),
+ pytest.param(["-e" + UNSLOTH_VCS, "snac"], ["snac"], id = "attached-protected"),
+ ],
+)
+def test_editable_forms(shim, args, expected):
+ execd, _ = _run(shim, "pip", args)
+ assert execd == (args if expected is KEPT else expected), execd
+
+
+ "args, expected, expected_marker",
+ [
+ pytest.param(["-P", "torch", "snac"], ["snac"], None, id = "protected-dropped"),
+ pytest.param(["--upgrade-package=transformers", "snac"], ["snac"], None, id = "inline"),
+ pytest.param(["-P", "transformers==4.55.0", "snac"], ["snac"], "4.55.0", id = "tf-pin"),
+ pytest.param(["-P", "requests", "requests"], KEPT, None, id = "unprotected-kept"),
+ pytest.param(["-P", "torch"], None, None, id = "only-protected-noop"),
+ ],
+)
+def test_upgrade_package_forms(shim, args, expected, expected_marker):
+ execd, marker = _run(shim, "uv", args)
+ assert execd == (args if expected is KEPT else expected), execd
+ assert marker == expected_marker, marker
+
+
+NUMPY_WHEEL_URL = "https://example.com/wheels/numpy-2.1.0-cp312-cp312-linux_x86_64.whl"
+
+
+ "args, expected",
+ [
+ pytest.param([TORCH_WHEEL_URL], None, id = "direct-url"),
+ pytest.param(
+ ["/tmp/torch-2.11.0+cu128-cp312-cp312-linux_x86_64.whl"], None, id = "local-path"
+ ),
+ pytest.param(
+ ["https://example.com/unsloth_zoo-1.0-py3-none-any.whl"], None, id = "normalised"
+ ),
+ pytest.param([NUMPY_WHEEL_URL], KEPT, id = "unprotected-kept"),
+ ],
+)
+def test_wheel_url_and_path_forms(shim, args, expected):
+ execd, _ = _run(shim, "pip", args)
+ assert execd == (args if expected is KEPT else expected), execd
+
+
+def test_protected_wheel_in_requirements_file_dropped(shim, tmp_path):
+ req = tmp_path / "reqs.txt"
+ req.write_text(
+ TORCH_WHEEL_URL + "\n" + "snac==1.2.0\n",
+ encoding = "utf-8",
+ )
+ execd, _ = _run(shim, "pip", ["-r", str(req)])
+ assert execd is not None and execd[0] == "-r"
+ filtered = Path(execd[1]).read_text(encoding = "utf-8")
+ assert "snac==1.2.0" in filtered
+ assert "torch" not in filtered
+
+
+def test_plain_package_passes_through(shim):
+ execd, _ = _run(shim, "pip", ["omegaconf==2.3.1"])
+ assert execd == ["omegaconf==2.3.1"], execd
+
+
+def test_bare_transformers_recorded_and_dropped(shim):
+ execd, marker = _run(shim, "pip", ["transformers==4.55.0"])
+ assert execd is None
+ assert marker == "4.55.0"
+
+
+def test_index_url_value_flag_kept_verbatim(shim):
+ execd, _ = _run(shim, "pip", ["--extra-index-url", "https://example.com/simple", "snac"])
+ assert execd == ["--extra-index-url", "https://example.com/simple", "snac"], execd
+
+
+def test_editable_protected_in_requirements_file_dropped(shim, tmp_path):
+ req = tmp_path / "reqs.txt"
+ req.write_text(
+ "-e git+https://github.com/unslothai/unsloth.git#egg=unsloth\nsnac==1.2.0\n",
+ encoding = "utf-8",
+ )
+ execd, _ = _run(shim, "pip", ["-r", str(req)])
+ assert execd is not None and execd[0] == "-r", execd
+ filtered = Path(execd[1]).read_text(encoding = "utf-8")
+ assert "snac==1.2.0" in filtered
+ assert "unsloth" not in filtered
+
+
+def test_editable_attached_protected_in_requirements_file_dropped(shim, tmp_path):
+ req = tmp_path / "reqs.txt"
+ req.write_text(
+ "-egit+https://github.com/unslothai/unsloth.git#egg=unsloth\nsnac==1.2.0\n",
+ encoding = "utf-8",
+ )
+ execd, _ = _run(shim, "pip", ["-r", str(req)])
+ assert execd is not None and execd[0] == "-r", execd
+ filtered = Path(execd[1]).read_text(encoding = "utf-8")
+ assert "snac==1.2.0" in filtered
+ assert "unsloth" not in filtered
+
+
+def test_editable_unprotected_in_requirements_file_kept(shim, tmp_path):
+ req = tmp_path / "reqs.txt"
+ req.write_text(
+ "-e ./localpkg\ntorch==2.11.0\nsnac==1.2.0\n",
+ encoding = "utf-8",
+ )
+ execd, _ = _run(shim, "pip", ["-r", str(req)])
+ assert execd is not None and execd[0] == "-r", execd
+ filtered = Path(execd[1]).read_text(encoding = "utf-8")
+ assert "./localpkg" in filtered
+ assert "snac==1.2.0" in filtered
+ assert "torch" not in filtered
+
+
+def test_nested_constraint_transformers_pin_not_recorded(shim, tmp_path):
+ constraints = tmp_path / "constraints.txt"
+ constraints.write_text("transformers==4.55.0\n", encoding = "utf-8")
+ req = tmp_path / "reqs.txt"
+ req.write_text("-c constraints.txt\nsnac==1.2.0\n", encoding = "utf-8")
+ execd, marker = _run(shim, "pip", ["-r", str(req)])
+ assert execd is not None and execd[0] == "-r", execd
+ assert marker is None, marker
+
+
+def test_nested_requirement_transformers_pin_recorded(shim, tmp_path):
+ nested = tmp_path / "nested.txt"
+ nested.write_text("transformers==4.55.0\n", encoding = "utf-8")
+ req = tmp_path / "reqs.txt"
+ req.write_text("-r nested.txt\nsnac==1.2.0\n", encoding = "utf-8")
+ execd, marker = _run(shim, "pip", ["-r", str(req)])
+ assert execd is not None and execd[0] == "-r", execd
+ assert marker == "4.55.0", marker
+
+
+def test_attached_short_requirement_file_filtered(shim, tmp_path):
+ # attached `-rreqs.txt` must filter the file AND count as a target, or the cell no-ops
+ req = tmp_path / "reqs.txt"
+ req.write_text("torch==2.11.0\nsnac==1.2.0\n", encoding = "utf-8")
+ execd, _ = _run(shim, "pip", ["-r" + str(req)])
+ assert execd is not None and execd[0] == "-r", execd
+ filtered = Path(execd[1]).read_text(encoding = "utf-8")
+ assert "snac==1.2.0" in filtered
+ assert "torch" not in filtered
+
+
+def test_attached_short_constraint_file_filtered(shim, tmp_path):
+ constraints = tmp_path / "constraints.txt"
+ constraints.write_text("torch==2.11.0\n", encoding = "utf-8")
+ execd, _ = _run(shim, "pip", ["-c" + str(constraints), "snac"])
+ assert execd is not None and execd[0] == "-c", execd
+ assert "snac" in execd
+ filtered = Path(execd[1]).read_text(encoding = "utf-8")
+ assert "torch" not in filtered
+
+
+def test_attached_short_upgrade_package_protected_dropped(shim):
+ execd, _ = _run(shim, "uv", ["-Ptorch", "snac"])
+ assert execd == ["snac"], execd
+ assert "torch" not in execd and "-P" not in execd
+
+
+ "args, expected",
+ [
+ pytest.param(["torch-2.11.0+cu128-cp312-cp312-linux_x86_64.whl"], None, id = "bare-torch"),
+ pytest.param(["dist/torch-2.11.0-cp312-cp312-linux_x86_64.whl"], None, id = "subdir-torch"),
+ pytest.param(["numpy-2.1.0-cp312-cp312-linux_x86_64.whl"], KEPT, id = "unprotected-kept"),
+ ],
+)
+def test_bare_wheel_filename_forms(shim, args, expected):
+ execd, _ = _run(shim, "pip", args)
+ assert execd == (args if expected is KEPT else expected), execd
+
+
+def test_vcs_url_without_egg_protected_dropped(shim):
+ execd, _ = _run(shim, "pip", ["git+https://github.com/huggingface/transformers.git", "snac"])
+ assert execd == ["snac"], execd
+
+
+def test_vcs_url_without_egg_with_ref_dropped(shim):
+ execd, _ = _run(shim, "pip", ["git+https://github.com/unslothai/unsloth-zoo.git@main", "snac"])
+ assert execd == ["snac"], execd
+
+
+def test_vcs_url_without_egg_unprotected_kept(shim):
+ url = "git+https://github.com/someone/coolpkg.git"
+ execd, _ = _run(shim, "pip", [url])
+ assert execd == [url], execd
+
+
+# remote requirement/constraint files are refused: their pins cannot be inspected first
+R_URL = "https://example.com/reqs.txt"
+
+
+ "args, expected",
+ [
+ pytest.param(["-r", R_URL], None, id = "sep-r-only-noop"),
+ pytest.param(["-r", R_URL, "snac"], ["snac"], id = "sep-r-target-kept"),
+ pytest.param(["--requirement=" + R_URL, "snac"], ["snac"], id = "inline-r"),
+ pytest.param(["-r" + R_URL, "snac"], ["snac"], id = "attached-r"),
+ pytest.param(["-c", "https://example.com/constraints.txt", "snac"], ["snac"], id = "sep-c"),
+ ],
+)
+def test_remote_requirement_and_constraint_urls_refused(shim, args, expected):
+ execd, _ = _run(shim, "pip", args)
+ assert execd == expected, execd
+
+
+def test_nested_remote_include_dropped(shim, tmp_path):
+ req = tmp_path / "reqs.txt"
+ req.write_text("-r https://example.com/evil.txt\nsnac==1.2.0\n", encoding = "utf-8")
+ execd, _ = _run(shim, "pip", ["-r", str(req)])
+ assert execd is not None and execd[0] == "-r", execd
+ filtered = Path(execd[1]).read_text(encoding = "utf-8")
+ assert "snac==1.2.0" in filtered
+ assert "example.com" not in filtered and "://" not in filtered
+
+
+# resolver-wide reinstall / ignore-installed flags cannot rebuild satisfied baked deps
+def test_force_reinstall_flag_stripped(shim):
+ execd, _ = _run(shim, "pip", ["--force-reinstall", "snac"])
+ assert execd == ["snac"], execd
+
+
+def test_ignore_installed_short_flag_stripped(shim):
+ execd, _ = _run(shim, "pip", ["-I", "snac"])
+ assert execd == ["snac"], execd
+
+
+def test_uv_reinstall_flag_stripped(shim):
+ execd, _ = _run(shim, "uv", ["--reinstall", "snac"])
+ assert execd == ["snac"], execd
+
+
+ "args, expected, expected_marker",
+ [
+ pytest.param(["--reinstall-package", "torch", "snac"], ["snac"], None, id = "sep-protected"),
+ pytest.param(["--reinstall-package=torch", "snac"], ["snac"], None, id = "inline-protected"),
+ pytest.param(["--reinstall-package", "requests", "requests"], KEPT, None, id = "unprotected"),
+ pytest.param(
+ ["--reinstall-package", "transformers==4.55.0", "snac"], ["snac"], "4.55.0", id = "tf-pin"
+ ),
+ ],
+)
+def test_reinstall_package_forms(shim, args, expected, expected_marker):
+ execd, marker = _run(shim, "uv", args)
+ assert execd == (args if expected is KEPT else expected), execd
+ assert marker == expected_marker, marker
+
+
+SDIST_URL = "https://files.pythonhosted.org/packages/aa/unsloth-2026.7.1.tar.gz"
+
+
+ "args, expected",
+ [
+ pytest.param([SDIST_URL, "snac"], ["snac"], id = "url-protected"),
+ pytest.param(["torch-2.11.0.tar.gz"], None, id = "bare-protected"),
+ pytest.param(["./transformers-4.55.0.zip", "snac"], ["snac"], id = "zip-protected"),
+ # a hyphenated protected name must survive the sdist hyphen split
+ pytest.param(["flashinfer-python-0.5.0.tar.gz"], None, id = "hyphenated-name"),
+ pytest.param(["numpy-2.1.0.tar.gz"], KEPT, id = "unprotected-kept"),
+ ],
+)
+def test_source_archive_forms(shim, args, expected):
+ execd, _ = _run(shim, "pip", args)
+ assert execd == (args if expected is KEPT else expected), execd
+
+
+def test_uv_plural_requirements_filtered(shim, tmp_path):
+ req = tmp_path / "reqs.txt"
+ req.write_text("torch==2.11.0\nsnac==1.2.0\n", encoding = "utf-8")
+ execd, _ = _run(shim, "uv", ["--requirements", str(req)])
+ assert execd is not None and execd[0] == "--requirements", execd
+ filtered = Path(execd[1]).read_text(encoding = "utf-8")
+ assert "snac==1.2.0" in filtered
+ assert "torch" not in filtered
+
+
+def test_uv_plural_constraints_filtered(shim, tmp_path):
+ constraints = tmp_path / "constraints.txt"
+ constraints.write_text("torch==2.11.0\n", encoding = "utf-8")
+ execd, _ = _run(shim, "uv", ["--constraints", str(constraints), "snac"])
+ assert execd is not None and execd[0] == "--constraints", execd
+ assert "snac" in execd
+ filtered = Path(execd[1]).read_text(encoding = "utf-8")
+ assert "torch" not in filtered
+
+
+# --upgrade-strategy eager would let a kept target rebuild satisfied baked deps
+ "args, expected",
+ [
+ pytest.param(["-U", "--upgrade-strategy", "eager", "snac"], ["-U", "snac"], id = "eager"),
+ pytest.param(["--upgrade-strategy=eager", "snac"], ["snac"], id = "inline-eager"),
+ pytest.param(
+ ["--upgrade-strategy", "only-if-needed", "snac"], ["snac"], id = "only-if-needed"
+ ),
+ ],
+)
+def test_upgrade_strategy_forms(shim, args, expected):
+ execd, _ = _run(shim, "pip", args)
+ assert execd == expected, execd
+
+
+# every forwarded install carries a constraints file, so an incompatible dependency
+# fails loudly instead of replacing the wheel
+def _raw_execd(shim, tool, args):
+ argv = ["uv", "pip", "install", *args] if tool == "uv" else ["pip", "install", *args]
+ with pytest.MonkeyPatch.context() as mp:
+ mp.setattr(shim.sys, "argv", argv)
+ try:
+ shim.main()
+ return None
+ except _Exec as exc:
+ return exc.argv[exc.argv.index("install") + 1 :]
+
+
+class _FakeDist:
+ def __init__(self, name, version):
+ self.metadata = {"Name": name}
+ self.version = version
+
+
+def _fake_distributions(monkeypatch, *pairs):
+ """Pin what _protected_constraints_file sees as INSTALLED, else the assertions
+ depend on the ambient venv. The shim imports it inside the function, so patch
+ it at its source."""
+ monkeypatch.setattr(
+ "importlib.metadata.distributions",
+ lambda **kw: [_FakeDist(n, v) for n, v in pairs],
+ )
+
+
+def test_forwarded_install_carries_protected_constraints(shim, monkeypatch):
+ _fake_distributions(monkeypatch, ("transformers", "5.14.1"), ("trl", "0.24.0"))
+ execd = _raw_execd(shim, "pip", ["snac"])
+ assert execd is not None, "an unprotected target must still be forwarded"
+ assert len(execd) >= 2 and execd[-2] == "--constraint", execd
+ pins = Path(execd[-1]).read_text(encoding = "utf-8").strip().splitlines()
+ assert pins, "constraints file must pin the installed protected packages"
+ assert all("==" in pin for pin in pins), pins
+ names = {pin.split("==", 1)[0].lower().replace("_", "-") for pin in pins}
+ protected = {"transformers"} | shim._KEEP | {"nvidia-"}
+ assert all(
+ n in shim._KEEP or n == "transformers" or n.startswith("nvidia-") for n in names
+ ), names
+
+
+def test_forwarded_install_without_protected_packages_has_no_constraints(shim, monkeypatch):
+ _fake_distributions(monkeypatch, ("snac", "1.2.1"))
+ execd = _raw_execd(shim, "pip", ["snac"])
+ assert execd is not None, "the install must still be forwarded"
+ assert "--constraint" not in execd, execd
+
+
+def test_noop_install_gets_no_constraints(shim):
+ execd = _raw_execd(shim, "pip", ["torch"])
+ assert execd is None
+
+
+# pip expands ${UPPERCASE} in requirements files after the shim classifies the literal
+# text, so classification must expand the same way or `${PKG}==` walks past _KEEP
+def test_env_expanded_protected_requirement_dropped(shim, tmp_path, monkeypatch):
+ monkeypatch.setenv("PKG", "torch")
+ req = tmp_path / "reqs.txt"
+ req.write_text("${PKG}==2.11.0\nsnac==1.2.0\n", encoding = "utf-8")
+ execd, _ = _run(shim, "pip", ["-r", str(req)])
+ assert execd is not None and execd[0] == "-r", execd
+ filtered = Path(execd[1]).read_text(encoding = "utf-8")
+ assert "snac==1.2.0" in filtered
+ assert "${PKG}" not in filtered and "torch" not in filtered
+
+
+def test_env_expanded_transformers_pin_recorded(shim, tmp_path, monkeypatch):
+ monkeypatch.setenv("TF_PKG", "transformers")
+ req = tmp_path / "reqs.txt"
+ req.write_text("${TF_PKG}==4.56.2\nsnac==1.2.0\n", encoding = "utf-8")
+ _, marker = _run(shim, "pip", ["-r", str(req)])
+ assert marker == "4.56.2"
+
+
+def test_unset_env_reference_left_verbatim(shim, tmp_path, monkeypatch):
+ monkeypatch.delenv("NOT_SET_ANYWHERE", raising = False)
+ req = tmp_path / "reqs.txt"
+ req.write_text("${NOT_SET_ANYWHERE}==1.0\nsnac==1.2.0\n", encoding = "utf-8")
+ execd, _ = _run(shim, "pip", ["-r", str(req)])
+ assert execd == ["-r", str(req)], execd
+
+
+# a filtered-copy write failure must fail CLOSED: forwarding the original hands pip
+# exactly what must be filtered
+def test_filter_write_failure_refuses_original_file(shim, tmp_path, monkeypatch):
+ req = tmp_path / "reqs.txt"
+ req.write_text("torch==2.11.0\nsnac==1.2.0\n", encoding = "utf-8")
+
+ def denied(*args, **kwargs):
+ raise OSError(30, "Read-only file system")
+
+ monkeypatch.setattr(shim.tempfile, "mkstemp", denied)
+ with pytest.raises(SystemExit, match = "refusing to forward"):
+ shim._filter_requirements_file(str(req))
+
+
+# transformers is already out of the real arguments by the time the marker is written,
+# so a swallowed failure reported a plain success while the model cells went on
+# importing the baked version. It must warn instead: aborting would turn an unwritable
+# path the user cannot act on into a hard notebook failure, but silence is worse.
+def test_marker_write_failure_warns_and_does_not_claim_success(shim, monkeypatch, capsys):
+ def denied(*args, **kwargs):
+ raise OSError(30, "Read-only file system")
+
+ monkeypatch.setattr(shim.os, "makedirs", denied)
+ monkeypatch.setattr(shim.sys, "argv", ["pip", "install", "transformers==4.99.0"])
+ shim.main()
+ err = capsys.readouterr()
+ assert "WARNING" in err.err and "will NOT" in err.err
+ assert "will activate its sidecar" not in err.out
+
+
+# dirname() is "" for a bare relative MARKER and makedirs("") raises FileNotFoundError,
+# an OSError: without the guard, failing closed would turn that config into a hard abort
+def test_bare_relative_marker_still_records(shim, tmp_path, monkeypatch):
+ monkeypatch.chdir(tmp_path)
+ monkeypatch.setattr(shim, "MARKER", "requested_transformers")
+ monkeypatch.setattr(shim.sys, "argv", ["pip", "install", "transformers==4.99.0"])
+ shim.main()
+ assert (tmp_path / "requested_transformers").read_text() == "4.99.0"
+
+
+def test_filter_write_failure_clean_file_passes_through(shim, tmp_path, monkeypatch):
+ req = tmp_path / "reqs.txt"
+ req.write_text("snac==1.2.0\n", encoding = "utf-8")
+
+ def denied(*args, **kwargs):
+ raise OSError(30, "Read-only file system")
+
+ monkeypatch.setattr(shim.tempfile, "mkstemp", denied)
+ path, recorded, dropped = shim._filter_requirements_file(str(req))
+ assert path == str(req) and recorded is None and dropped == []
+
+
+# the constraints file is the ONLY thing holding the baked stack when a forwarded
+# package pulls an incompatible transitive pin, and `_extras_only_target` forwards a
+# protected `name[extras]` because of it, so its write must fail CLOSED too instead of
+# reading like "nothing to protect"
+def test_protected_constraints_write_failure_refuses_install(shim, monkeypatch):
+ _fake_distributions(monkeypatch, ("torch", "2.11.0"))
+
+ def denied(*args, **kwargs):
+ raise OSError(28, "No space left on device")
+
+ monkeypatch.setattr(shim.tempfile, "mkstemp", denied)
+ with pytest.raises(SystemExit, match = "refusing to install"):
+ _raw_execd(shim, "pip", ["snac"])
+
+
+def test_protected_metadata_enumeration_failure_refuses_install(shim, monkeypatch):
+ def denied(**kw):
+ raise OSError(5, "Input/output error")
+
+ monkeypatch.setattr("importlib.metadata.distributions", denied)
+ with pytest.raises(SystemExit, match = "refusing to install"):
+ _raw_execd(shim, "pip", ["snac"])
+
+
+# an interrupted install leaves a `.dist-info` with no METADATA behind, and that one
+# unreadable dist must not take the pins for every other package down with it
+def test_one_unreadable_dist_does_not_drop_the_other_pins(shim, monkeypatch):
+ class _BrokenDist:
+ @property
+ def metadata(self):
+ raise KeyError("Name")
+
+ @property
+ def version(self):
+ raise KeyError("Version")
+
+ monkeypatch.setattr(
+ "importlib.metadata.distributions",
+ lambda **kw: [_BrokenDist(), _FakeDist("torch", "2.11.0"), _FakeDist("snac", "1.2.1")],
+ )
+ execd = _raw_execd(shim, "pip", ["snac"])
+ assert execd is not None and execd[-2] == "--constraint", execd
+ pins = Path(execd[-1]).read_text(encoding = "utf-8").split()
+ assert pins == ["torch==2.11.0"], pins
+
+
+# uv --exact is an exact SYNC: it removes packages outside the kept target's closure
+def test_uv_exact_flag_stripped(shim):
+ execd, _ = _run(shim, "uv", ["--exact", "snac"])
+ assert execd == ["snac"], execd
+
+
+# a local project dir naming a protected package needs its name from the project
+# metadata: a same-version dev build slips past the constraints file
+def _make_local_project(tmp_path, dirname, project_name):
+ proj = tmp_path / dirname
+ proj.mkdir()
+ (proj / "pyproject.toml").write_text(f'[project]\nname = "{project_name}"\nversion = "1.0"\n')
+ return str(proj)
+
+
+def test_local_dir_protected_by_metadata_dropped(shim, tmp_path):
+ path = _make_local_project(tmp_path, "my-checkout", "transformers")
+ execd, _ = _run(shim, "pip", [path, "snac"])
+ assert execd == ["snac"], execd
+
+
+def test_local_dir_protected_editable_dropped(shim, tmp_path):
+ path = _make_local_project(tmp_path, "unsloth", "unsloth")
+ execd, _ = _run(shim, "pip", ["-e", path, "snac"])
+ assert execd == ["snac"], execd
+ assert "-e" not in execd
+
+
+def test_local_dir_basename_fallback_setup_py(shim, tmp_path):
+ proj = tmp_path / "torch"
+ proj.mkdir()
+ (proj / "setup.py").write_text("from setuptools import setup\nsetup()\n")
+ execd, _ = _run(shim, "pip", [str(proj), "snac"])
+ assert execd == ["snac"], execd
+
+
+def test_local_dir_unprotected_kept(shim, tmp_path):
+ path = _make_local_project(tmp_path, "my-torch-utils", "my-torch-utils")
+ execd, _ = _run(shim, "pip", [path])
+ assert execd == [path], execd
+
+
+def test_local_dir_without_metadata_passes_through(shim, tmp_path):
+ plain = tmp_path / "datadir"
+ plain.mkdir()
+ execd, _ = _run(shim, "pip", [str(plain)])
+ assert execd == [str(plain)], execd
+
+
+# every uv/pip value-taking flag must be in _VALUE_FLAGS, or its VALUE is misread as
+# an install target (`--extra torch snac` swallowed snac behind a dangling --extra)
+ "tool, flag, value",
+ [
+ pytest.param("uv", "--torch-backend", "cu128", id = "uv-torch-backend"),
+ pytest.param("uv", "--resolution", "lowest", id = "uv-resolution"),
+ pytest.param("uv", "--default-index", "https://mirror/simple", id = "uv-default-index"),
+ pytest.param("uv", "--exclude-newer", "2026-01-01", id = "uv-exclude-newer"),
+ pytest.param("uv", "-b", "build-constraints.txt", id = "uv-build-constraints-short"),
+ pytest.param("uv", "--prerelease-package", "snac", id = "uv-prerelease-package"),
+ pytest.param("pip", "--proxy", "http://proxy:3128", id = "pip-proxy"),
+ pytest.param("pip", "--retries", "3", id = "pip-retries"),
+ pytest.param("pip", "--trusted-host", "mirror.internal", id = "pip-trusted-host"),
+ ],
+)
+def test_value_flag_protected_only_noops(shim, tool, flag, value):
+ execd, _ = _run(shim, tool, [flag, value, "torch"])
+ assert execd is None, execd
+
+
+ "tool, flag, value",
+ [
+ pytest.param("uv", "--torch-backend", "cu128", id = "uv-torch-backend"),
+ pytest.param("uv", "--resolution", "lowest", id = "uv-resolution"),
+ pytest.param("pip", "--proxy", "http://proxy:3128", id = "pip-proxy"),
+ ],
+)
+def test_value_flag_pair_forwarded_with_kept_target(shim, tool, flag, value):
+ execd, _ = _run(shim, tool, [flag, value, "torch", "snac"])
+ assert execd == [flag, value, "snac"], execd
+
+
+def test_extra_value_is_not_a_protected_target(shim):
+ execd, _ = _run(shim, "uv", ["--extra", "torch", "snac"])
+ assert execd == ["--extra", "torch", "snac"], execd
+
+
+def test_uv_per_package_value_flags_classified(shim):
+ # the whole family, so the next sibling uv adds fails here, not in the image build
+ known = shim._VALUE_FLAGS | shim._DROP_VALUE_FLAGS
+ family = {
+ "--config-settings-package",
+ "--exclude-newer-package",
+ "--no-build-isolation-package",
+ "--no-editable-package",
+ "--no-sources-package",
+ "--prerelease-package",
+ "--refresh-package",
+ "--reinstall-package",
+ "--upgrade-package",
+ }
+ assert family <= known, sorted(family - known)
+
+
+def _value_flags_from_help(cmd):
+ import re
+ import subprocess
+
+ out = subprocess.run(cmd, capture_output = True, text = True).stdout
+ flags = set()
+ for m in re.finditer(r"^\s+(-\w)?,?\s*(--[\w-]+)[= ]<", out, re.M):
+ if m.group(1):
+ flags.add(m.group(1))
+ flags.add(m.group(2))
+ for m in re.finditer(r"^\s+(-\w) <", out, re.M):
+ flags.add(m.group(1))
+ return flags
+
+
+# opt-in: repo CI runs whatever pip/uv are current, so a hard assert would redden every
+# upstream flag addition. The image build's --unsloth-selfcheck-value-flags is
+# authoritative, being run against the baked tools.
+_DRIFT_OPT_IN = os.environ.get("UNSLOTH_SHIM_FLAG_DRIFT_CHECK") == "1"
+
+
[email protected](not _DRIFT_OPT_IN, reason = "opt-in: UNSLOTH_SHIM_FLAG_DRIFT_CHECK=1")
+def test_pip_help_value_flags_all_classified(shim):
+ known = shim._VALUE_FLAGS | shim._DROP_VALUE_FLAGS
+ missing = _value_flags_from_help([sys.executable, "-m", "pip", "install", "--help"]) - known
+ assert not missing, f"value flags missing from _VALUE_FLAGS: {sorted(missing)}"
+
+
+ not _DRIFT_OPT_IN or not __import__("shutil").which("uv"),
+ reason = "opt-in: UNSLOTH_SHIM_FLAG_DRIFT_CHECK=1 (and uv installed)",
+)
+def test_uv_help_value_flags_all_classified(shim):
+ known = shim._VALUE_FLAGS | shim._DROP_VALUE_FLAGS
+ missing = _value_flags_from_help(["uv", "pip", "install", "--help"]) - known
+ assert not missing, f"value flags missing from _VALUE_FLAGS: {sorted(missing)}"
+
+
+# a VCS @ref may contain a slash (@feature/foo); strip it before the last-segment
+# split, else the ref's basename dodges _KEEP
+ "url",
+ [
+ pytest.param(
+ "git+https://github.com/unslothai/unsloth.git@feature/foo", id = "https-slash-ref"
+ ),
+ pytest.param(
+ "git+ssh://[email protected]/unslothai/unsloth.git@feature/foo",
+ id = "ssh-userinfo-and-slash-ref",
+ ),
+ pytest.param("git+https://github.com/unslothai/[email protected]", id = "plain-tag-ref"),
+ pytest.param("git+https://github.com/unslothai/unsloth.git", id = "no-ref"),
+ ],
+)
+def test_vcs_slash_ref_still_protected(shim, url):
+ execd, _ = _run(shim, "pip", [url, "snac"])
+ assert execd == ["snac"], execd
+
+
+def test_vcs_slash_ref_unprotected_kept(shim):
+ url = "git+https://github.com/someorg/sometool.git@feature/foo"
+ execd, _ = _run(shim, "pip", [url])
+ assert execd == [url], execd
+
+
+# the constraints pair must go BEFORE `--`: both pip and uv parse everything after
+# the terminator as a requirement and reject "Invalid requirement: '--constraint'"
+def _execd_full(shim, tool, args):
+ argv = ["uv", "pip", "install", *args] if tool == "uv" else ["pip", "install", *args]
+ with pytest.MonkeyPatch.context() as mp:
+ mp.setattr(shim.sys, "argv", argv)
+ with pytest.raises(_Exec) as exc:
+ shim.main()
+ tail = exc.value.argv[exc.value.argv.index("install") + 1 :]
+ return tail
+
+
[email protected]("tool", ["pip", "uv"])
+def test_constraints_precede_the_end_of_options_marker(shim, tool):
+ execd = _execd_full(shim, tool, ["--", "snac"])
+ assert "--constraint" in execd, execd
+ assert execd.index("--constraint") < execd.index("--"), (
+ f"the constraints pair lands after `--`, so the real tool parses "
+ f"--constraint as a requirement and the cell fails: {execd}"
+ )
+ assert execd[execd.index("--") :] == ["--", "snac"], execd
+
+
[email protected]("tool", ["pip", "uv"])
+def test_end_of_options_marker_still_protects_the_baked_stack(shim, tool):
+ execd = _execd_full(shim, tool, ["--", "torch", "snac"])
+ assert "torch" not in execd, execd
+ assert execd[execd.index("--") :] == ["--", "snac"], execd
+
+
[email protected]("tool", ["pip", "uv"])
+def test_without_a_terminator_the_pair_is_still_appended_last(shim, tool):
+ execd = _execd_full(shim, tool, ["snac"])
+ assert execd[0] == "snac", execd
+ assert execd[-2] == "--constraint", execd
+
+
+# PEP 503: a name compares equal under any run of `-`, `_` or `.`, so `unsloth.zoo`
+# IS `unsloth-zoo`. Every _canon early return must normalise, not just collapse "_".
+ "token",
+ [
+ "unsloth.zoo @ git+https://github.com/unslothai/unsloth_zoo",
+ "git+https://github.com/unslothai/unsloth_zoo#egg=unsloth.zoo",
+ "https://example.invalid/unsloth.zoo-1.0-py3-none-any.whl",
+ "unsloth.zoo-1.0.tar.gz",
+ "git+https://github.com/unslothai/unsloth.zoo",
+ "unsloth.zoo==2026.9.1",
+ "unsloth__zoo==2026.9.1",
+ "UNSLOTH.ZOO==2026.9.1",
+ ],
+)
+def test_dotted_spellings_of_a_protected_package_are_still_protected(shim, token):
+ assert shim._canon(token) == "unsloth-zoo", token
+ assert shim._canon(token) in shim._KEEP, token
+
+
+ "token, expected",
+ [
+ ("nvidia.cublas-cu12==1.0", "nvidia-cublas-cu12"),
+ ("huggingface.hub==1.0", "huggingface-hub"),
+ ],
+)
+def test_prefix_and_plain_matches_normalize_too(shim, token, expected):
+ name = shim._canon(token)
+ assert name == expected, token
+ assert name in shim._KEEP or name.startswith(shim._KEEP_PREFIX), token
+
+
+def test_normalization_does_not_merge_distinct_distributions(shim):
+ for token in ("torch-directml==0.2", "torch_tensorrt==2.0", "torchsde==0.2"):
+ assert shim._canon(token) not in shim._KEEP, token
+
+
+# --group and --requirements-from-script ARE the install target, with no package on
+# the command line; as ordinary option/value pairs the shim no-op'd while printing "ok"
+ "args",
+ [
+ ["--group", "test"],
+ ["--group=test"],
+ ["--group", "sub/pyproject.toml:dev"],
+ ["--requirements-from-script", "demo.py"],
+ ["--requirements-from-script=demo.py"],
+ ],
+)
+def test_dependency_group_flags_are_never_a_silent_no_op(shim, args):
+ """These flags ARE the install target, so treating them as ordinary option/value
+ pairs made the shim find nothing to install and print "ok" having done nothing.
+
+ They are now refused instead of forwarded, because their contents cannot be read
+ and a group holding a same-version local path over a baked package installs over
+ it. The property this test exists for is unchanged either way: never quietly
+ succeed while the requested packages go uninstalled."""
+ argv = ["pip", "install", *args]
+ with pytest.MonkeyPatch.context() as mp:
+ mp.setattr(shim.sys, "argv", argv)
+ with pytest.raises(SystemExit) as exc:
+ shim.main()
+ assert "refusing" in str(exc.value), (args, exc.value)
+
+
[email protected]("args", [["--no-deps"], ["--quiet"], ["torch"]])
+def test_flag_only_or_fully_protected_cells_still_no_op(shim, args):
+ """The guard must keep no-op'ing where there really is nothing to install."""
+ argv = ["pip", "install", *args]
+ with pytest.MonkeyPatch.context() as mp:
+ mp.setattr(shim.sys, "argv", argv)
+ shim.main()
+
+
+# --- hashed lock files: a requirement continues across physical lines --------------
+# `pip-compile --generate-hashes` / `uv pip compile --generate-hashes` emit
+# torch==2.11.0 \
+# --hash=sha256:... \
+# --hash=sha256:...
+# Filtering physical lines dropped only the first row and published the orphaned
+# `--hash` rows; uv then refuses the whole file with
+# "Unexpected '-', expected '-c', '-e', '-r' or the start of a requirement".
+HASHED_LOCK = (
+ "colorama==0.4.6 \\\n"
+ " --hash=sha256:08695f5cb7ed6e0531a20572697297273c47b8cae5a63ffc6d6ed5c201be6e44 \\\n"
+ " --hash=sha256:4f1d9991f5acc0ca119f9d443620b77f9d6b33703e51011c16baf57afb285fc6\n"
+ " # via -r in.txt\n"
+ "torch==2.11.0 \\\n"
+ " --hash=sha256:1111111111111111111111111111111111111111111111111111111111111111 \\\n"
+ " --hash=sha256:2222222222222222222222222222222222222222222222222222222222222222\n"
+ "idna==3.18 \\\n"
+ " --hash=sha256:7f952cbe720b688055e3f87de14f5c3e5fdaa8bc3928985c4077ca689de849a2\n"
+)
+
+
+def test_hashed_requirement_drops_its_continuation_lines(shim, tmp_path):
+ req = tmp_path / "locked.txt"
+ req.write_text(HASHED_LOCK, encoding = "utf-8")
+ execd, _ = _run(shim, "uv", ["-r", str(req)])
+ assert execd is not None and execd[0] == "-r", execd
+ filtered = Path(execd[1]).read_text(encoding = "utf-8")
+ # no ORPHANED option row: every `--hash` must continue the line above it
+ prev = ""
+ for line in filtered.splitlines():
+ if line.strip().startswith("--hash"):
+ assert prev.rstrip().endswith("\\"), filtered
+ prev = line
+ assert "torch" not in filtered, filtered
+ assert "1111111111111111" not in filtered and "2222222222222222" not in filtered, filtered
+ # the untouched requirements keep BOTH their pin and every hash row
+ assert "colorama==0.4.6 \\" in filtered, filtered
+ assert "08695f5cb7ed6e0531a20572697297273c47b8cae5a63ffc6d6ed5c201be6e44" in filtered
+ assert "4f1d9991f5acc0ca119f9d443620b77f9d6b33703e51011c16baf57afb285fc6" in filtered
+ assert "idna==3.18 \\" in filtered, filtered
+ assert "7f952cbe720b688055e3f87de14f5c3e5fdaa8bc3928985c4077ca689de849a2" in filtered
+
+
+def test_hashed_transformers_still_records_its_version(shim, tmp_path):
+ req = tmp_path / "locked.txt"
+ req.write_text(
+ "transformers==4.55.0 \\\n"
+ " --hash=sha256:3333333333333333333333333333333333333333333333333333333333333333\n"
+ "snac==1.2.0\n",
+ encoding = "utf-8",
+ )
+ execd, marker = _run(shim, "pip", ["-r", str(req)])
+ assert marker == "4.55.0", marker
+ filtered = Path(execd[1]).read_text(encoding = "utf-8")
+ assert "snac==1.2.0" in filtered
+ assert "transformers" not in filtered and "3333333333333333" not in filtered, filtered
+
+
+def test_continued_protected_requirement_leaves_no_orphan_specifier(shim, tmp_path):
+ req = tmp_path / "reqs.txt"
+ req.write_text("torch \\\n ==2.11.0\nsnac==1.2.0\n", encoding = "utf-8")
+ execd, _ = _run(shim, "pip", ["-r", str(req)])
+ filtered = Path(execd[1]).read_text(encoding = "utf-8")
+ assert "==2.11.0" not in filtered, filtered
+ assert "snac==1.2.0" in filtered, filtered
+
+
+# --- extras of a baked package ----------------------------------------------------
+# `pip install "datasets[audio]"` against an installed datasets ADDS the extra's
+# dependencies, it does not replace datasets, so dropping the token lost every one of
+# them and still printed "ok". The injected --constraint pins the baked version.
+ "arg, expected",
+ [
+ pytest.param("datasets[audio]", "datasets[audio]", id = "bare"),
+ pytest.param("unsloth[studio]", "unsloth[studio]", id = "unsloth-studio"),
+ # the pin is what would replace the bake, so only the pin is dropped
+ pytest.param("datasets[audio]==4.3.0", "datasets[audio]", id = "pinned"),
+ pytest.param("datasets[audio, vision]", "datasets[audio, vision]", id = "multi"),
+ pytest.param(
+ 'datasets[audio]; python_version >= "3.10"',
+ 'datasets[audio] ; python_version >= "3.10"',
+ id = "marker",
+ ),
+ ],
+)
+def test_extras_of_baked_package_are_forwarded(shim, arg, expected):
+ execd, _ = _run(shim, "pip", [arg])
+ assert execd == [expected], execd
+
+
+ "arg",
+ [
+ # a direct reference REPLACES the distribution, extras or not
+ "unsloth[colab-new] @ git+https://github.com/unslothai/unsloth.git",
+ "torch[opt] @ https://example.com/torch-2.11.0-py3-none-any.whl",
+ ],
+)
+def test_extras_with_direct_reference_still_dropped(shim, arg):
+ execd, _ = _run(shim, "pip", [arg])
+ assert execd is None, execd
+
+
+def test_extras_of_baked_package_in_requirements_file(shim, tmp_path):
+ req = tmp_path / "reqs.txt"
+ req.write_text("datasets[audio]==4.3.0\ntorch==2.11.0\nsnac==1.2.0\n", encoding = "utf-8")
+ execd, _ = _run(shim, "pip", ["-r", str(req)])
+ filtered = Path(execd[1]).read_text(encoding = "utf-8")
+ assert "datasets[audio]" in filtered, filtered
+ assert "datasets[audio]==4.3.0" not in filtered, filtered
+ assert "torch" not in filtered, filtered
+ assert "snac==1.2.0" in filtered, filtered
+
+
+# transformers is the one protected name outside _KEEP, because the sidecar replaces its
+# VERSION rather than the distribution. `pip install "transformers[deepspeed]"` is a
+# documented HF install line, so the extras must be forwarded here exactly as they are
+# for every _KEEP package; dropping the whole token recorded the pin and then printed
+# "nothing to install ... ok" while deepspeed never arrived.
+ "arg, expected, expected_marker",
+ [
+ pytest.param(
+ "transformers[deepspeed]==5.5.0", "transformers[deepspeed]", "5.5.0", id = "pinned"
+ ),
+ pytest.param("transformers[torch]", "transformers[torch]", None, id = "bare"),
+ pytest.param(
+ "transformers[torch, sentencepiece]",
+ "transformers[torch, sentencepiece]",
+ None,
+ id = "multi",
+ ),
+ ],
+)
+def test_transformers_extras_are_forwarded_and_the_pin_is_still_recorded(
+ shim, arg, expected, expected_marker
+):
+ execd, marker = _run(shim, "pip", [arg])
+ assert execd == [expected], execd
+ assert marker == expected_marker, marker
+
+
+def test_transformers_extras_direct_reference_still_dropped(shim):
+ # a direct reference REPLACES transformers, which is what the sidecar is for
+ execd, marker = _run(
+ shim, "pip", ["transformers[torch] @ git+https://github.com/huggingface/transformers"]
+ )
+ assert execd is None, execd
+ assert marker is None, marker
+
+
+def test_transformers_extras_in_requirements_file(shim, tmp_path):
+ req = tmp_path / "reqs.txt"
+ req.write_text("transformers[deepspeed]==5.5.0\nsnac==1.2.0\n", encoding = "utf-8")
+ execd, marker = _run(shim, "pip", ["-r", str(req)])
+ filtered = Path(execd[1]).read_text(encoding = "utf-8")
+ assert "transformers[deepspeed]\n" in filtered, filtered
+ assert "5.5.0" not in filtered, filtered
+ assert "snac==1.2.0" in filtered, filtered
+ assert marker == "5.5.0", marker
+
+
+def test_transformers_extras_are_dropped_when_transformers_is_not_installed(shim, monkeypatch):
+ """No baked transformers means no version to hold in place: forwarding the extras
+ would install whatever transformers pip resolves, so keep the sidecar route."""
+ monkeypatch.setattr(shim, "_installed_names", lambda: set())
+ execd, marker = _run(shim, "pip", ["transformers[deepspeed]==5.5.0"])
+ assert execd is None, execd
+ assert marker == "5.5.0", marker
+
+
+# unsloth_nb_compat and unsloth_run PREPEND an activated transformers sidecar to
+# PYTHONPATH, and each sidecar is built with `uv pip install --target`, so it carries
+# a real transformers-X.dist-info. A bare distributions() walks sys.path in order and
+# would report the sidecar's transformers first, pinning the SIDECAR version into the
+# protected constraints. The pin is what stops the resolver moving the shared base
+# install, so pinning the sidecar version defeats it for every later kernel.
+def _sidecar_dir(tmp_path, version):
+ d = tmp_path / f"t_{version.replace('.', '_')}"
+ info = d / f"transformers-{version}.dist-info"
+ info.mkdir(parents = True)
+ (info / "METADATA").write_text(
+ f"Metadata-Version: 2.1\nName: transformers\nVersion: {version}\n",
+ encoding = "utf-8",
+ )
+ (info / "RECORD").write_text("", encoding = "utf-8")
+ return d
+
+
+def test_protected_pins_ignore_a_sidecar_on_pythonpath(shim, tmp_path, monkeypatch):
+ """The pin must name the BAKED transformers, not the activated sidecar."""
+ baked = _sidecar_dir(tmp_path / "base", "4.57.6")
+ sidecar = _sidecar_dir(tmp_path / "sc", "5.5.0")
+ # the real thing: sidecar first on the search path, venv second
+ monkeypatch.setattr(shim, "_base_site_packages", lambda: [str(baked)])
+ monkeypatch.syspath_prepend(str(sidecar))
+
+ path = shim._protected_constraints_file()
+ assert path is not None
+ pins = Path(path).read_text(encoding = "utf-8").split()
+ tf = [p for p in pins if p.lower().startswith("transformers==")]
+ assert tf == ["transformers==4.57.6"], f"sidecar version leaked into the pins: {tf}"
+
+
+def test_base_site_packages_never_returns_a_pythonpath_entry(shim, tmp_path, monkeypatch):
+ """sys.prefix cannot be influenced by PYTHONPATH, which is the property the pin
+ scoping relies on. A sidecar on sys.path must not appear in the scope."""
+ sidecar = _sidecar_dir(tmp_path / "sc", "5.5.0")
+ monkeypatch.syspath_prepend(str(sidecar))
+ scope = shim._base_site_packages()
+ assert scope, "the base site-packages must be locatable"
+ assert str(sidecar) not in scope, scope
+
+
+# uv's command path is `uv [opts] pip [opts] install`, but it has other subcommands
+# ending in `install`. Selecting the first bare "install" claimed those too: `uv python
+# install 3.13` and `uv tool install ruff` got the protected --constraint appended,
+# which neither accepts, and `uv tool install transformers` was filtered to nothing and
+# reported ok, so NO tool was installed at all.
+def _full_argv(shim, argv):
+ """The whole command line the shim would run, or None when it ran nothing."""
+ with pytest.MonkeyPatch.context() as mp:
+ mp.setattr(shim.sys, "argv", argv)
+ try:
+ shim.main()
+ return None
+ except _Exec as exc:
+ return list(exc.argv)
+
+
+ "argv",
+ [
+ ["uv", "python", "install", "3.13"],
+ ["uv", "tool", "install", "ruff"],
+ ["uv", "tool", "install", "transformers"],
+ ],
+ ids = ["python-install", "tool-install", "tool-install-protected-name"],
+)
+def test_non_pip_uv_subcommands_pass_through_untouched(shim, monkeypatch, argv):
+ _fake_distributions(monkeypatch, ("transformers", "4.57.6"), ("torch", "2.11.0"))
+ ran = _full_argv(shim, argv)
+ assert ran is not None, f"{' '.join(argv)} installed NOTHING"
+ assert ran[1:] == argv[1:], ran
+ assert "--constraint" not in ran, "this uv subcommand takes no --constraint"
+
+
+ "argv",
+ [
+ ["uv", "pip", "install", "snac"],
+ ["uv", "pip", "--quiet", "install", "snac"],
+ ["uv", "--directory", "/x", "pip", "install", "snac"],
+ ],
+ ids = ["plain", "opt-before-install", "global-opt-before-pip"],
+)
+def test_real_uv_pip_installs_are_still_intercepted(shim, monkeypatch, argv):
+ """Narrowing the match must not stop protecting the command that matters."""
+ _fake_distributions(monkeypatch, ("transformers", "4.57.6"), ("torch", "2.11.0"))
+ ran = _full_argv(shim, argv)
+ assert ran is not None
+ assert "--constraint" in ran, ran
+
+
+def test_a_protected_target_under_uv_tool_install_is_not_swallowed(shim, monkeypatch):
+ """The silent shape: filtering left nothing to run and reported success."""
+ _fake_distributions(monkeypatch, ("transformers", "4.57.6"))
+ ran = _full_argv(shim, ["uv", "tool", "install", "transformers"])
+ assert ran is not None, "the tool install was swallowed and reported ok"
+ assert ran[-1] == "transformers", ran
+
+
+# uv accepts its global options between `pip` and `install`, e.g.
+# `uv pip --directory /tmp install torch==9.9`. Locating the subcommand by stepping
+# back over anything starting with "-" stopped at the VALUE (/tmp) and gave up, so the
+# install ran with no filtering and no protected constraints -- free to replace the
+# baked torch/CUDA stack. Missing the command is far worse than over-matching it.
+ "argv",
+ [
+ ["uv", "pip", "--directory", "/tmp", "install", "snac"],
+ # aimed AT the guarded venv on purpose: an interpreter elsewhere is a
+ # destination and is deliberately bypassed, which would not exercise the
+ # subcommand search this test is about
+ ["uv", "pip", "--python", "/opt/unsloth-venv/bin/python", "install", "snac"],
+ ["uv", "pip", "--cache-dir", "/c", "--color", "never", "install", "snac"],
+ ["uv", "pip", "--directory=/tmp", "install", "snac"],
+ ],
+ ids = ["directory", "python", "two-value-opts", "equals-form"],
+)
+def test_value_taking_options_before_install_do_not_lose_the_command(shim, monkeypatch, argv):
+ _fake_distributions(monkeypatch, ("transformers", "4.57.6"), ("torch", "2.11.0"))
+ ran = _full_argv(shim, argv)
+ assert ran is not None, f"{' '.join(argv)} was not recognised as an install"
+ assert "--constraint" in ran, "the baked stack was left unprotected for a real uv pip install"
+
+
+def test_a_protected_pin_behind_a_value_option_is_still_held(shim, monkeypatch):
+ """The consequence that matters: `torch==9.9` must never reach the real tool.
+
+ Losing the command let it through verbatim; recognising it means torch is a
+ protected target, so the run is filtered down to nothing instead.
+ """
+ _fake_distributions(monkeypatch, ("torch", "2.11.0"))
+ ran = _full_argv(shim, ["uv", "pip", "--directory", "/tmp", "install", "torch==9.9"])
+ assert ran is None or "torch==9.9" not in ran, f"the baked torch was replaceable: {ran}"
+
+
+# `!pip install -qr requirements.txt` is a standard notebook idiom, and a short-option
+# CLUSTER reached no handler: only tok[:2] is tested against the attached-value flags,
+# the exact-token comparisons never match, and the fallback keeps any unrecognised
+# `-...` verbatim. The ORIGINAL requirements file was forwarded, unfiltered and with
+# nothing recorded, so the sidecar was never activated for the pin it contained.
+ "cluster",
+ ["-qr", "-Ur", "-vr", "-nr", "-Ir", "-qqr"],
+)
+def test_short_option_clusters_still_filter_the_requirements_file(
+ shim, monkeypatch, tmp_path, cluster
+):
+ _fake_distributions(monkeypatch, ("transformers", "4.57.6"), ("torch", "2.11.0"))
+ reqs = tmp_path / "reqs.txt"
+ reqs.write_text("transformers==5.5.0\nsnac==1.2.1\n", encoding = "utf-8")
+ ran = _full_argv(shim, ["pip", "install", cluster, str(reqs)])
+ assert ran is not None
+ assert str(reqs) not in ran, (
+ f"{cluster} forwarded the ORIGINAL requirements file; the protected pin in it "
+ f"was never filtered and never recorded"
+ )
+
+
+def test_an_attached_short_value_is_left_alone(shim, monkeypatch, tmp_path):
+ """`-rfoo.txt` already worked; splitting clusters must not break it."""
+ _fake_distributions(monkeypatch, ("transformers", "4.57.6"))
+ reqs = tmp_path / "reqs.txt"
+ # it needs a protected pin, else nothing is rewritten and forwarding the ORIGINAL
+ # path is the correct answer, which makes the assertion below vacuous
+ reqs.write_text("transformers==5.5.0\nsnac==1.2.1\n", encoding = "utf-8")
+ ran = _full_argv(shim, ["pip", "install", f"-r{reqs}"])
+ assert ran is not None and str(reqs) not in ran, ran
+
+
+def test_reinstall_flags_inside_a_cluster_are_still_handled(shim, monkeypatch, tmp_path):
+ """-I hid inside a cluster and escaped _REINSTALL_FLAGS."""
+ _fake_distributions(monkeypatch, ("torch", "2.11.0"))
+ ran = _full_argv(shim, ["pip", "install", "-qI", "snac"])
+ assert ran is not None
+ assert "-I" not in ran and "-qI" not in ran, ran
+
+
+# `uv pip sync` UNINSTALLS everything absent from the file, so unlike install there is
+# nothing to strip: leaving a protected package out of the file is exactly what deletes
+# it, and --constraint bounds versions rather than preventing removals.
+ "argv",
+ [
+ ["uv", "pip", "sync", "reqs.txt"],
+ ["uv", "pip", "--directory", "/tmp", "sync", "reqs.txt"],
+ ],
+ ids = ["plain", "behind-a-value-option"],
+)
+def test_uv_pip_sync_is_refused_rather_than_forwarded(shim, monkeypatch, argv):
+ _fake_distributions(monkeypatch, ("torch", "2.11.0"))
+ with pytest.raises(SystemExit) as exc:
+ _full_argv(shim, argv)
+ assert "refusing" in str(exc.value), exc.value
+ assert "uv pip install" in str(exc.value), "say what to use instead"
+
+
+def test_uv_pip_install_is_not_caught_by_the_sync_refusal(shim, monkeypatch):
+ _fake_distributions(monkeypatch, ("torch", "2.11.0"))
+ ran = _full_argv(shim, ["uv", "pip", "install", "snac"])
+ assert ran is not None and "--constraint" in ran, ran
+
+
+def test_a_byte_order_mark_does_not_hide_the_first_pin(shim, monkeypatch, tmp_path):
+ """Both real tools strip a BOM and honour the line. Reading as utf-8 left
+ '\\ufefftransformers==X' matching nothing, so a file whose ONLY protected pin was
+ on line 1 was forwarded unchanged."""
+ _fake_distributions(monkeypatch, ("transformers", "4.57.6"))
+ reqs = tmp_path / "bom.txt"
+ reqs.write_bytes("transformers==5.5.0\n".encode("utf-8"))
+ ran = _full_argv(shim, ["pip", "install", "-r", str(reqs)])
+ assert ran is None or str(reqs) not in ran, (
+ "the BOM'd requirements file was forwarded verbatim, so its transformers pin "
+ "reached the resolver instead of being recorded for the sidecar"
+ )
+
+
+# _is_protected drops a package only when it is REALLY installed. The Dockerfile lets
+# the torchcodec bake and the non-amd64 vLLM bake fail on purpose, so without that
+# check a recovery `pip install vllm` prints "kept baked versions, skipped: vllm" over
+# an image that has no vLLM and the GRPO fast_inference path stays broken.
+#
+# Nothing exercised it, and not merely by omission: the shared `shim` fixture pins
+# _installed_names to _BakedImage, "an image where every bake succeeded", which is
+# exactly the case where the check cannot fire. These override it, because the whole
+# point of the check is the image where a bake DID fail.
+def test_a_baked_name_that_is_not_installed_is_still_forwarded(shim, monkeypatch):
+ assert "vllm" in shim._KEEP, "this test is meaningless if vllm is not protected"
+ _fake_distributions(monkeypatch, ("torch", "2.11.0"))
+ monkeypatch.setattr(shim, "_installed_names", lambda: {"torch"})
+ ran = _full_argv(shim, ["pip", "install", "vllm"])
+ assert ran is not None, "the install was swallowed as 'already baked' on an image with no vLLM"
+ assert "vllm" in ran, ran
+
+
+def test_a_baked_name_that_IS_installed_is_still_dropped(shim, monkeypatch):
+ """The other half, so the test above cannot be satisfied by never protecting."""
+ _fake_distributions(monkeypatch, ("torch", "2.11.0"), ("vllm", "0.11.0"))
+ monkeypatch.setattr(shim, "_installed_names", lambda: {"torch", "vllm"})
+ ran = _full_argv(shim, ["pip", "install", "vllm"])
+ assert ran is None or "vllm" not in ran, ran
+
+
+# A value-taking flag the scanner does not know is read as an install TARGET, so the
+# real target is never examined: the install forwards with the protected package kept
+# and no --constraint at all. The `=` form is unaffected, which is why this hides.
+# pip's --help prints one spelling per option, so seven hidden ALIASES were invisible
+# to a help scrape; --python-preference is a uv global documented in no help output.
+ "argv",
+ [
+ ["pip", "--default-timeout", "100", "install", "torch"],
+ ["pip", "--log-file", "/tmp/x.log", "install", "torch"],
+ ["pip", "--source-dir", "/tmp/s", "install", "torch"],
+ ["uv", "--python-preference", "system", "pip", "install", "torch"],
+ ],
+ ids = ["default-timeout", "log-file", "source-dir", "uv-python-preference"],
+)
+def test_a_separated_alias_value_is_not_read_as_a_target(shim, monkeypatch, argv):
+ _fake_distributions(monkeypatch, ("torch", "2.11.0"))
+ ran = _full_argv(shim, argv)
+ assert (
+ ran is None or "torch" not in ran
+ ), f"the baked torch was forwarded for replacement: {ran}"
+
+
+def test_an_alias_value_does_not_hide_uv_pip_sync(shim, monkeypatch):
+ """The sync refusal is found by the same positional walk, so a mis-parsed global
+ hid it too."""
+ _fake_distributions(monkeypatch, ("torch", "2.11.0"))
+ with pytest.raises(SystemExit) as exc:
+ _full_argv(shim, ["uv", "--python-preference", "system", "pip", "sync", "r.txt"])
+ assert "refusing" in str(exc.value), exc.value
+
+
+def test_the_value_flag_selfcheck_cannot_certify_what_it_cannot_inspect(shim):
+ """It used to scrape `--help` only, which structurally cannot see an alias, and
+ still printed OK. A selfcheck that can pass while blind is worse than none."""
+ src = SHIM_PATH.read_text(encoding = "utf-8")
+ body = src[src.index("def _selfcheck_value_flags():") :]
+ body = body[: body.index("\ndef ", 10)]
+ assert "option_list_all" in body, "pip must be introspected, not scraped"
+ assert (
+ "refusing to" in body and "sys.exit(1)" in body
+ ), "failing to introspect pip must be a FAILURE, never a silent pass"
+ assert '[REAL["uv"], "--help"]' in body, "uv globals must be checked too"
+
+
+# uv changes directory BEFORE it resolves a relative `-r`/`-c` path, so the shim has
+# to read the file from there too. Reading it from our own cwd misses, and the miss
+# is silent: _filter_requirements_file forwards the untouched relative path and uv,
+# now chdir'd, installs a file we never inspected and recorded no transformers pin
+# from. `--directory` is a uv GLOBAL, so every argv position below is valid.
+
+
+def _working_dir_case(tmp_path):
+ """A cwd with NO requirements.txt, beside a directory that has one."""
+ here = tmp_path / "here"
+ there = tmp_path / "there"
+ here.mkdir()
+ there.mkdir()
+ (there / "requirements.txt").write_text("transformers==4.55.0\nsnac\n", encoding = "utf-8")
+ return here, there
+
+
+ "build",
+ [
+ lambda d: ["uv", "pip", "--directory", d, "install", "-r", "requirements.txt"],
+ lambda d: ["uv", "--directory", d, "pip", "install", "-r", "requirements.txt"],
+ lambda d: ["uv", "pip", "install", "--directory", d, "-r", "requirements.txt"],
+ lambda d: ["uv", "pip", "--directory=" + d, "install", "-r", "requirements.txt"],
+ ],
+ ids = ["between-pip-and-install", "before-pip", "after-install", "equals-form"],
+)
+def test_a_relative_requirements_file_is_read_from_uvs_working_directory(
+ shim, monkeypatch, tmp_path, build
+):
+ _fake_distributions(monkeypatch, ("transformers", "4.57.6"))
+ here, there = _working_dir_case(tmp_path)
+ monkeypatch.chdir(here)
+ ran = _full_argv(shim, build(str(there)))
+ assert ran is not None, "the shim ran nothing"
+ assert "requirements.txt" not in ran, f"forwarded the file unfiltered: {ran}"
+ assert shim._marker_path.exists(), "no transformers pin was recorded"
+ assert shim._marker_path.read_text() == "4.55.0"
+
+
+def test_the_uv_working_dir_env_moves_the_file_too(shim, monkeypatch, tmp_path):
+ """uv documents --directory as `[env: UV_WORKING_DIR=]`, so the variable alone
+ relocates the file with no flag on the command line at all."""
+ _fake_distributions(monkeypatch, ("transformers", "4.57.6"))
+ here, there = _working_dir_case(tmp_path)
+ monkeypatch.chdir(here)
+ monkeypatch.setenv("UV_WORKING_DIR", str(there))
+ ran = _full_argv(shim, ["uv", "pip", "install", "-r", "requirements.txt"])
+ assert ran is not None, "the shim ran nothing"
+ assert "requirements.txt" not in ran, f"forwarded the file unfiltered: {ran}"
+ assert shim._marker_path.read_text() == "4.55.0"
+
+
+def test_the_directory_flag_wins_over_the_working_dir_env(shim, monkeypatch, tmp_path):
+ """uv gives the flag precedence, so honouring the variable instead would filter
+ and record the wrong file."""
+ _fake_distributions(monkeypatch, ("transformers", "4.57.6"))
+ here, there = _working_dir_case(tmp_path)
+ other = tmp_path / "other"
+ other.mkdir()
+ (other / "requirements.txt").write_text("transformers==1.0.0\n", encoding = "utf-8")
+ monkeypatch.chdir(here)
+ monkeypatch.setenv("UV_WORKING_DIR", str(other))
+ ran = _full_argv(
+ shim, ["uv", "pip", "--directory", str(there), "install", "-r", "requirements.txt"]
+ )
+ assert ran is not None, "the shim ran nothing"
+ assert shim._marker_path.read_text() == "4.55.0", "read the env's file, not the flag's"
+
+
+def test_a_nested_include_follows_uvs_working_directory(shim, monkeypatch, tmp_path):
+ """A nested `-r` is relative to the file that NAMES it, and that file now lives
+ in uv's directory rather than ours."""
+ _fake_distributions(monkeypatch, ("transformers", "4.57.6"))
+ here, there = _working_dir_case(tmp_path)
+ (there / "requirements.txt").write_text("-r nested.txt\nsnac\n", encoding = "utf-8")
+ (there / "nested.txt").write_text("transformers==4.55.0\n", encoding = "utf-8")
+ monkeypatch.chdir(here)
+ ran = _full_argv(
+ shim, ["uv", "pip", "--directory", str(there), "install", "-r", "requirements.txt"]
+ )
+ assert ran is not None, "the shim ran nothing"
+ assert shim._marker_path.read_text() == "4.55.0"
+
+
+def test_pip_keeps_resolving_a_relative_requirements_file_from_the_cwd(shim, monkeypatch, tmp_path):
+ """pip has no --directory and never chdirs, so none of this may change for it."""
+ _fake_distributions(monkeypatch, ("transformers", "4.57.6"))
+ here, _there = _working_dir_case(tmp_path)
+ (here / "requirements.txt").write_text("transformers==4.99.0\nsnac\n", encoding = "utf-8")
+ monkeypatch.chdir(here)
+ ran = _full_argv(shim, ["pip", "install", "-r", "requirements.txt"])
+ assert ran is not None, "the shim ran nothing"
+ assert shim._marker_path.read_text() == "4.99.0"
+
+
+# A local project target is a filesystem lookup too: _classify_flag_target -> _canon
+# -> _local_project_name stats the directory to learn the project's real name. uv
+# stats it from ITS working directory, so resolving it from ours reports a protected
+# project as unknown and forwards it. That one is silent where the requirements-file
+# case is loud, because the injected constraint only rejects a version MISMATCH: a
+# local checkout whose version equals the baked one resolves cleanly and installs.
+
+
+def _local_project(
+ root,
+ name,
+ version = "2026.6.9",
+):
+ proj = root / name
+ proj.mkdir(parents = True)
+ (proj / "pyproject.toml").write_text(
+ f'[project]\nname = "{name}"\nversion = "{version}"\n', encoding = "utf-8"
+ )
+ return proj
+
+
+ "build",
+ [
+ lambda d: ["uv", "pip", "--directory", d, "install", "-e", "./unsloth"],
+ lambda d: ["uv", "pip", "--directory", d, "install", "./unsloth"],
+ lambda d: ["uv", "--directory", d, "pip", "install", "-e", "./unsloth"],
+ lambda d: ["uv", "pip", "install", "--directory", d, "-e", "./unsloth"],
+ ],
+ ids = ["editable", "positional", "before-pip", "after-install"],
+)
+def test_a_local_protected_project_is_found_in_uvs_working_directory(
+ shim, monkeypatch, tmp_path, build
+):
+ _fake_distributions(monkeypatch, ("unsloth", "2026.6.9"))
+ here, there = tmp_path / "here", tmp_path / "there"
+ here.mkdir()
+ there.mkdir()
+ _local_project(there, "unsloth")
+ monkeypatch.chdir(here)
+
+ ran = _full_argv(shim, build(str(there)))
+ assert ran is None or not any(
+ "unsloth" in a for a in ran
+ ), f"the baked unsloth was forwarded for replacement: {ran}"
+
+
+def test_the_working_dir_env_also_finds_a_local_protected_project(shim, monkeypatch, tmp_path):
+ _fake_distributions(monkeypatch, ("unsloth", "2026.6.9"))
+ here, there = tmp_path / "here", tmp_path / "there"
+ here.mkdir()
+ there.mkdir()
+ _local_project(there, "unsloth")
+ monkeypatch.chdir(here)
+ monkeypatch.setenv("UV_WORKING_DIR", str(there))
+
+ ran = _full_argv(shim, ["uv", "pip", "install", "-e", "./unsloth"])
+ assert ran is None or not any(
+ "unsloth" in a for a in ran
+ ), f"the baked unsloth was forwarded for replacement: {ran}"
+
+
+def test_a_local_project_relative_to_the_cwd_is_still_classified(shim, monkeypatch, tmp_path):
+ """The ordinary no-directory case must keep working: pip never changes directory
+ and uv without --directory resolves from the cwd exactly as we do."""
+ _fake_distributions(monkeypatch, ("unsloth", "2026.6.9"))
+ here = tmp_path / "here"
+ here.mkdir()
+ _local_project(here, "unsloth")
+ monkeypatch.chdir(here)
+
+ ran = _full_argv(shim, ["pip", "install", "-e", "./unsloth"])
+ assert ran is None or not any(
+ "unsloth" in a for a in ran
+ ), f"the baked unsloth was forwarded for replacement: {ran}"
+
+
+def test_an_unrelated_local_project_still_reaches_the_real_tool(shim, monkeypatch, tmp_path):
+ """Resolving from uv's directory must not start dropping things: a local project
+ that is not protected still has to be installed."""
+ _fake_distributions(monkeypatch, ("unsloth", "2026.6.9"))
+ here, there = tmp_path / "here", tmp_path / "there"
+ here.mkdir()
+ there.mkdir()
+ _local_project(there, "mytool", version = "0.1.0")
+ monkeypatch.chdir(here)
+
+ ran = _full_argv(shim, ["uv", "pip", "--directory", str(there), "install", "-e", "./mytool"])
+ assert ran is not None and any(
+ "mytool" in a for a in ran
+ ), f"an unprotected local project was dropped: {ran}"
+
+
+ "spec",
+ ["./unsloth#subdirectory=sub", "./unsloth#foo=1"],
+ ids = ["subdirectory", "unknown-fragment"],
+)
+def test_a_fragment_does_not_hide_a_local_protected_project(shim, monkeypatch, tmp_path, spec):
+ """The stat has to happen on the path alone. `#egg=` is recognised earlier, but
+ any other fragment reaches the directory lookup still attached, and leaving it on
+ makes the stat miss and forwards the project for replacement."""
+ _fake_distributions(monkeypatch, ("unsloth", "2026.6.9"))
+ here, there = tmp_path / "here", tmp_path / "there"
+ here.mkdir()
+ there.mkdir()
+ _local_project(there, "unsloth")
+ monkeypatch.chdir(here)
+
+ ran = _full_argv(shim, ["uv", "pip", "--directory", str(there), "install", "-e", spec])
+ assert ran is None or not any(
+ "unsloth" in a for a in ran
+ ), f"the baked unsloth was forwarded for replacement: {ran}"
+
+
+# --target/--prefix/--root/--python send the install to an environment this shim does
+# not guard. Filtering the baked stack out of one of those drops the packages the
+# caller actually asked for, and the "nothing to install" path then prints ok and
+# installs nothing at all.
+
+BAKED_VENV = "/opt/unsloth-venv"
+
+
+ "argv",
+ [
+ ["pip", "--python", "/tmp/venv/bin/python", "install", "torch==2.5.0"],
+ ["pip", "install", "--target", "/tmp/lib", "torch==2.5.0"],
+ ["pip", "install", "--target=/tmp/lib", "torch==2.5.0"],
+ ["pip", "install", "-t", "/tmp/lib", "torch==2.5.0"],
+ ["pip", "install", "-t/tmp/lib", "torch==2.5.0"],
+ ["pip", "install", "--prefix", "/tmp/pfx", "torch==2.5.0"],
+ ["pip", "install", "--root", "/tmp/root", "torch==2.5.0"],
+ ["uv", "pip", "install", "--python", "/tmp/venv/bin/python", "torch==2.5.0"],
+ ["uv", "pip", "install", "-p", "/tmp/venv/bin/python", "torch==2.5.0"],
+ ["uv", "pip", "install", "--target", "/tmp/lib", "torch==2.5.0"],
+ ["uv", "pip", "install", "--prefix", "/tmp/pfx", "torch==2.5.0"],
+ ],
+ ids = [
+ "pip-python",
+ "pip-target",
+ "pip-target-eq",
+ "pip-t",
+ "pip-t-attached",
+ "pip-prefix",
+ "pip-root",
+ "uv-python",
+ "uv-p",
+ "uv-target",
+ "uv-prefix",
+ ],
+)
+def test_an_install_aimed_elsewhere_keeps_the_packages_it_asked_for(shim, monkeypatch, argv):
+ _fake_distributions(monkeypatch, ("torch", "2.9.1+cu128"))
+ ran = _full_argv(shim, argv)
+ assert ran is not None, "the shim installed nothing and reported success"
+ assert "torch==2.5.0" in ran, f"torch was dropped from another environment: {ran}"
+
+
+ "var, value",
+ [
+ ("PIP_TARGET", "/tmp/lib"),
+ ("PIP_PREFIX", "/tmp/pfx"),
+ ("PIP_ROOT", "/tmp/root"),
+ ("UV_PYTHON", "/tmp/venv/bin/python"),
+ ],
+)
+def test_a_destination_environment_variable_redirects_too(shim, monkeypatch, var, value):
+ """pip honours PIP_<OPTION> for every option and uv documents --python as
+ [env: UV_PYTHON=], so the destination moves with nothing on the command line."""
+ _fake_distributions(monkeypatch, ("torch", "2.9.1+cu128"))
+ monkeypatch.setenv(var, value)
+ tool = "uv" if var.startswith("UV_") else "pip"
+ argv = (
+ ["uv", "pip", "install", "torch==2.5.0"]
+ if tool == "uv"
+ else ["pip", "install", "torch==2.5.0"]
+ )
+ ran = _full_argv(shim, argv)
+ assert ran is not None, "the shim installed nothing and reported success"
+ assert "torch==2.5.0" in ran, f"torch was dropped from another environment: {ran}"
+
+
+def test_a_sync_aimed_elsewhere_is_not_refused(shim, monkeypatch):
+ """The sync refusal exists because sync UNINSTALLS everything missing from the
+ file, stripping the baked stack. Pointed at another environment there is no baked
+ stack for it to strip."""
+ _fake_distributions(monkeypatch, ("torch", "2.9.1+cu128"))
+ ran = _full_argv(shim, ["uv", "pip", "sync", "--python", "/tmp/venv/bin/python", "r.txt"])
+ assert ran is not None and "r.txt" in ran, f"a sync aimed elsewhere was refused: {ran}"
+
+
+ "argv",
+ [
+ ["pip", "install", "torch==2.5.0"],
+ ["uv", "pip", "install", "torch==2.5.0"],
+ # a bare name or version may well BE the baked interpreter, so it must not
+ # buy a bypass
+ ["uv", "pip", "install", "--python", "python3", "torch==2.5.0"],
+ ["uv", "pip", "install", "--python", "3.12", "torch==2.5.0"],
+ # and a destination INSIDE the guarded venv is still the guarded venv
+ [
+ "pip",
+ "install",
+ "--target",
+ BAKED_VENV + "/lib/python3.12/site-packages",
+ "torch==2.5.0",
+ ],
+ ["uv", "pip", "install", "--python", BAKED_VENV + "/bin/python", "torch==2.5.0"],
+ ],
+ ids = ["pip-plain", "uv-plain", "bare-name", "bare-version", "target-in-venv", "python-in-venv"],
+)
+def test_the_baked_venv_is_still_protected(shim, monkeypatch, argv):
+ """Guard on already-correct behaviour: the bypass must fire only for a destination
+ positively resolved OUTSIDE the venv."""
+ _fake_distributions(monkeypatch, ("torch", "2.9.1+cu128"))
+ ran = _full_argv(shim, argv)
+ assert (
+ ran is None or "torch==2.5.0" not in ran
+ ), f"the baked torch was forwarded for replacement: {ran}"
+
+
+# Each tool ignores the other's environment variables, and a bypass granted on a
+# variable the invoked tool never reads is the dangerous direction: the install lands
+# in the BAKED venv having skipped every filter. Measured against both CLIs: with
+# UV_PYTHON set, `pip install idna==3.18` reported "already satisfied" from the base
+# environment, and with PIP_PYTHON set, `uv pip install` reported "environment at:
+# <base>"; each honoured only its own.
+ "tool, var",
+ [
+ ("pip", "UV_PYTHON"),
+ ("uv", "PIP_PYTHON"),
+ ("uv", "PIP_TARGET"),
+ ("uv", "PIP_PREFIX"),
+ ("uv", "PIP_ROOT"),
+ ],
+ ids = [
+ "pip-ignores-uv-python",
+ "uv-ignores-pip-python",
+ "uv-ignores-pip-target",
+ "uv-ignores-pip-prefix",
+ "uv-ignores-pip-root",
+ ],
+)
+def test_the_other_tools_destination_variable_buys_no_bypass(shim, monkeypatch, tool, var):
+ _fake_distributions(monkeypatch, ("torch", "2.9.1+cu128"))
+ monkeypatch.setenv(var, "/tmp/elsewhere")
+ argv = (
+ ["uv", "pip", "install", "torch==2.5.0"]
+ if tool == "uv"
+ else ["pip", "install", "torch==2.5.0"]
+ )
+ ran = _full_argv(shim, argv)
+ assert ran is None or "torch==2.5.0" not in ran, (
+ f"{var} is ignored by {tool}, so the install went to the BAKED venv with no "
+ f"filtering: {ran}"
+ )
+
+
+# pip reads PIP_<OPTION> for EVERY option, so an install target can arrive with
+# nothing on the command line to show for it. Measured: `PIP_REQUIREMENT=r.txt pip
+# install --dry-run` reported "Would install idna-3.6" where the same command with no
+# variable reports "You must give at least one requirement to install", and
+# PIP_EDITABLE=<project> reported "Would install dummyproj26-1.2.3". Both are space
+# separated for multiple values. uv has no environment form for --requirements.
+
+
+def _full_argv_env(shim, monkeypatch, argv):
+ """(whole command line, child environment or None) for a run that execs."""
+ seen = {}
+
+ def _fake_execve(path, a, env):
+ seen["env"] = env
+ raise _Exec(path, a)
+
+ monkeypatch.setattr(shim.os, "execve", _fake_execve)
+ return _full_argv(shim, argv), seen.get("env")
+
+
+def test_a_requirements_file_hidden_in_the_environment_is_filtered(shim, monkeypatch, tmp_path):
+ _fake_distributions(monkeypatch, ("torch", "2.9.1+cu128"))
+ hidden = tmp_path / "hidden.txt"
+ hidden.write_text("torch==9.9.9\nidna==3.6\n", encoding = "utf-8")
+ monkeypatch.setenv("PIP_REQUIREMENT", str(hidden))
+
+ ran, env = _full_argv_env(shim, monkeypatch, ["pip", "install", "packaging"])
+ assert ran is not None, "the shim ran nothing"
+ assert "torch==9.9.9" not in ran, f"the baked torch was forwarded: {ran}"
+ assert str(hidden) not in ran, f"the uninspected file was forwarded verbatim: {ran}"
+ assert any(
+ os.path.basename(a).startswith("unsloth-nb-req-") for a in ran
+ ), f"no filtered requirements file reached the real tool: {ran}"
+ assert env is not None and "PIP_REQUIREMENT" not in env, (
+ "the variable survived into the child, so the real pip reads the file again "
+ "unfiltered alongside our filtered copy"
+ )
+
+
+def test_an_editable_hidden_in_the_environment_is_classified(shim, monkeypatch, tmp_path):
+ _fake_distributions(monkeypatch, ("unsloth", "2026.6.9"))
+ _local_project(tmp_path, "unsloth")
+ monkeypatch.setenv("PIP_EDITABLE", str(tmp_path / "unsloth"))
+
+ proj = str(tmp_path / "unsloth")
+ ran, env = _full_argv_env(shim, monkeypatch, ["pip", "install", "packaging"])
+ # NOT a substring test for "unsloth": the injected constraints file we add is
+ # itself named unsloth-nb-protected-*, so that would always match
+ assert ran is not None, "the shim ran nothing"
+ assert (
+ proj not in ran and "-e" not in ran
+ ), f"the baked unsloth was forwarded for replacement: {ran}"
+ assert env is not None and "PIP_EDITABLE" not in env
+
+
+def test_several_hidden_requirements_files_are_all_filtered(shim, monkeypatch, tmp_path):
+ """pip splits these on whitespace, so one variable can carry several files."""
+ _fake_distributions(monkeypatch, ("torch", "2.9.1+cu128"))
+ one, two = tmp_path / "one.txt", tmp_path / "two.txt"
+ one.write_text("torch==9.9.9\n", encoding = "utf-8")
+ two.write_text("torch==8.8.8\nidna==3.6\n", encoding = "utf-8")
+ monkeypatch.setenv("PIP_REQUIREMENT", f"{one} {two}")
+
+ ran, _env = _full_argv_env(shim, monkeypatch, ["pip", "install", "packaging"])
+ assert ran is not None, "the shim ran nothing"
+ assert not any("9.9.9" in a or "8.8.8" in a for a in ran), f"a baked torch survived: {ran}"
+ assert (
+ sum(1 for a in ran if os.path.basename(a).startswith("unsloth-nb-req-")) == 2
+ ), f"both files should have been filtered: {ran}"
+
+
+def test_uv_is_not_given_a_requirements_file_pip_alone_reads(shim, monkeypatch, tmp_path):
+ """Guard: uv has no environment form for --requirements, so folding PIP_REQUIREMENT
+ into a uv command would install a file uv was never asked for."""
+ _fake_distributions(monkeypatch, ("torch", "2.9.1+cu128"))
+ hidden = tmp_path / "hidden.txt"
+ hidden.write_text("idna==3.6\n", encoding = "utf-8")
+ monkeypatch.setenv("PIP_REQUIREMENT", str(hidden))
+
+ ran = _full_argv(shim, ["uv", "pip", "install", "snac"])
+ assert ran is not None, "the shim ran nothing"
+ assert (
+ "-r" not in ran and str(hidden) not in ran
+ ), f"a pip-only requirements file was handed to uv: {ran}"
+
+
+def test_nothing_is_added_when_no_hidden_target_is_set(shim, monkeypatch):
+ """Guard: the ordinary case must be byte-identical, and must not switch to execve."""
+ _fake_distributions(monkeypatch, ("torch", "2.9.1+cu128"))
+ monkeypatch.delenv("PIP_REQUIREMENT", raising = False)
+ monkeypatch.delenv("PIP_EDITABLE", raising = False)
+ ran, env = _full_argv_env(shim, monkeypatch, ["pip", "install", "snac"])
+ assert ran is not None and "snac" in ran, ran
+ assert "-r" not in ran and "-e" not in ran, f"a phantom target was added: {ran}"
+ assert env is None, "the environment was rebuilt when nothing needed clearing"
+
+
+# pip's --root is a relocation PREFIX, not a destination directory: it keeps the
+# computed scheme path and re-anchors it under the root, so `--root /` is the identity
+# and still writes the venv's own site-packages. Measured with the real pip: `pip
+# install --root / idna==3.6` landed in the venv purelib, while `--root <dir>` put it
+# under that directory and left the venv untouched.
+IDENTITY_ROOT = "/" + ""
+
+
+ "argv",
+ [
+ ["pip", "install", "--root", IDENTITY_ROOT, "torch==2.5.0"],
+ ["pip", "install", "--root=" + IDENTITY_ROOT, "torch==2.5.0"],
+ ["pip", "install", "--root", IDENTITY_ROOT + IDENTITY_ROOT, "torch==2.5.0"],
+ ],
+ ids = ["separated", "equals-form", "double-slash"],
+)
+def test_an_identity_root_still_protects_the_baked_venv(shim, monkeypatch, argv):
+ _fake_distributions(monkeypatch, ("torch", "2.9.1+cu128"))
+ ran = _full_argv(shim, argv)
+ assert ran is None or "torch==2.5.0" not in ran, (
+ f"--root {IDENTITY_ROOT!r} relocates nothing, so this still replaces the baked "
+ f"CUDA stack: {ran}"
+ )
+
+
+def test_an_identity_root_from_the_environment_still_protects(shim, monkeypatch):
+ _fake_distributions(monkeypatch, ("torch", "2.9.1+cu128"))
+ monkeypatch.setenv("PIP_ROOT", IDENTITY_ROOT)
+ ran = _full_argv(shim, ["pip", "install", "torch==2.5.0"])
+ assert (
+ ran is None or "torch==2.5.0" not in ran
+ ), f"PIP_ROOT={IDENTITY_ROOT!r} relocates nothing: {ran}"
+
+
+def test_a_real_root_relocation_is_still_a_bypass(shim, monkeypatch):
+ """Guard: a root that genuinely moves the install must keep bypassing, or we are
+ back to emptying the environment the caller actually named."""
+ _fake_distributions(monkeypatch, ("torch", "2.9.1+cu128"))
+ ran = _full_argv(shim, ["pip", "install", "--root", "/tmp/reloc", "torch==2.5.0"])
+ assert (
+ ran is not None and "torch==2.5.0" in ran
+ ), f"a genuine --root relocation was filtered: {ran}"
+
+
+# URL schemes are case insensitive and pip normalises them, so `name@GIT+HTTPS://...`
+# is the same direct reference as the lowercase spelling.
+ "spec",
+ [
+ "unsloth@GIT+HTTPS://github.com/unslothai/unsloth.git",
+ "unsloth@Git+Https://github.com/unslothai/unsloth.git",
+ "unsloth@HTTPS://example.com/unsloth-2026.6.9-py3-none-any.whl",
+ "unsloth[all]@GIT+HTTPS://github.com/unslothai/unsloth.git",
+ ],
+ ids = ["upper-vcs", "mixed-vcs", "upper-url-wheel", "extras"],
+)
+def test_an_uppercase_direct_reference_scheme_is_still_classified(shim, monkeypatch, spec):
+ _fake_distributions(monkeypatch, ("unsloth", "2026.6.9"))
+ ran = _full_argv(shim, ["pip", "install", spec, "snac"])
+ assert (
+ ran is None or spec not in ran
+ ), f"a protected direct reference was forwarded because of scheme casing: {ran}"
+
+
+def test_an_unprotected_direct_reference_still_reaches_the_real_tool(shim, monkeypatch):
+ """Guard: matching schemes case insensitively must not start dropping things that
+ were never protected."""
+ _fake_distributions(monkeypatch, ("unsloth", "2026.6.9"))
+ spec = "snac@GIT+HTTPS://github.com/example/snac.git"
+ ran = _full_argv(shim, ["pip", "install", spec])
+ assert ran is not None and spec in ran, f"an unprotected direct reference was dropped: {ran}"
+
+
+def test_an_uppercase_scheme_without_a_double_slash_is_still_classified(shim, monkeypatch):
+ """`GIT+FILE:/path#egg=unsloth` carries no `://`, so the scheme prefix match is the
+ only thing that recognises it as a direct reference at all. Matching that prefix
+ case sensitively let the uppercase spelling fall through to "unknown" and be
+ forwarded."""
+ _fake_distributions(monkeypatch, ("unsloth", "2026.6.9"))
+ spec = "GIT+FILE:/tmp/checkout#egg=unsloth"
+ ran = _full_argv(shim, ["pip", "install", spec, "snac"])
+ assert (
+ ran is None or spec not in ran
+ ), f"a protected direct reference was forwarded because of scheme casing: {ran}"
+
+
+# --group (PEP 735, pip 25.3+ and uv) and --requirements-from-script (PEP 723, pip 26+,
+# which an image built today bakes because docker/Dockerfile installs pip unpinned)
+# supply install targets from a pyproject table or a script header. Nothing in the scan
+# can read those, and the injected constraints do not cover them: pip reinstalls a
+# same-version LOCAL PATH or sdist, so `unsloth @ file:///checkout` at the baked
+# version installs over the baked code.
+ "argv",
+ [
+ ["pip", "install", "--group", "dev"],
+ ["pip", "install", "--group=dev"],
+ ["uv", "pip", "install", "--group", "dev"],
+ ["pip", "install", "--requirements-from-script", "demo.py"],
+ ["pip", "install", "--group", "dev", "snac"],
+ ],
+ ids = ["pip-group", "pip-group-eq", "uv-group", "pip-script", "group-with-target"],
+)
+def test_an_uninspectable_target_source_is_refused(shim, monkeypatch, argv):
+ _fake_distributions(monkeypatch, ("unsloth", "2026.6.9"))
+ with pytest.raises(SystemExit) as exc:
+ _full_argv(shim, argv)
+ assert "refusing" in str(exc.value), exc.value
+
+
+def test_a_group_install_aimed_elsewhere_is_not_refused(shim, monkeypatch):
+ """Guard: the destination bypass runs first on purpose. A group installed into
+ another environment cannot touch the baked stack, so refusing it would break a
+ command that was never a threat."""
+ _fake_distributions(monkeypatch, ("unsloth", "2026.6.9"))
+ ran = _full_argv(shim, ["pip", "install", "--target", "/tmp/lib", "--group", "dev"])
+ assert ran is not None and "--group" in ran, f"a harmless group install was refused: {ran}"
+
+
+def test_an_ordinary_install_is_not_refused(shim, monkeypatch):
+ """Guard: the refusal must key on those flags alone."""
+ _fake_distributions(monkeypatch, ("unsloth", "2026.6.9"))
+ ran = _full_argv(shim, ["pip", "install", "snac"])
+ assert ran is not None and "snac" in ran, ran
+
+
+ "spec, expected",
+ [
+ ("transformers==4.57.6", "4.57.6"),
+ ("transformers==4.57.6; python_version < '3.0'", None),
+ ("transformers==4.57.6; sys_platform == 'win32'", None),
+ ("transformers==5.5.0; python_version >= '3.0'", "5.5.0"),
+ ],
+ ids = ["no-marker", "false-marker", "false-marker-platform", "true-marker"],
+)
+def test_a_false_marker_does_not_record_a_transformers_pin(shim, monkeypatch, spec, expected):
+ """Both real tools skip a requirement whose marker is false ("Ignoring
+ transformers: markers ... don't match your environment"), so it installs nothing
+ and must not write the sidecar marker file that every later cell reads."""
+ _fake_distributions(monkeypatch, ("transformers", "4.57.6"))
+ _execd, marker = _run(shim, "pip", [spec])
+ assert marker == expected, f"recorded {marker!r} for {spec!r}"
diff --git a/tests/sh/test_select_cuda_jit_tools.sh b/tests/sh/test_select_cuda_jit_tools.sh
new file mode 100755
index 00000000000..ebc7ea8af45
--- /dev/null
+++ b/tests/sh/test_select_cuda_jit_tools.sh
@@ -0,0 +1,104 @@
+#!/bin/bash
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+# Unit tests for select_cuda_jit_tools() from docker/entrypoint.sh.
+#
+# cu12.8 is the immutable baked default and the cu13 tools switch on ONLY for sm_103
+# and sm_121 (>= 580 drivers), picked per device via nvidia-smi compute_cap.
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+ENTRYPOINT_SH="$SCRIPT_DIR/../../docker/entrypoint.sh"
+PASS=0
+FAIL=0
+
+# The fixtures assert through readlink, because retargeting that symlink is what the
+# function does -- and git-bash copies instead of symlinking unless
+# MSYS=winsymlinks:nativestrict and the user is elevated.
+_probe=$(mktemp -d)
+: > "$_probe/target"
+if ! ln -s target "$_probe/link" 2>/dev/null || [ "$(readlink "$_probe/link")" != "target" ]; then
+ rm -rf "$_probe"
+ echo "=== test_select_cuda_jit_tools ==="
+ echo " SKIP: this filesystem does not honour symlinks (readlink cannot observe them)"
+ echo "PASS=0 FAIL=0 SKIPPED"
+ exit 0
+fi
+rm -rf "$_probe"
+
+_FUNC_FILE=$(mktemp)
+sed -n '/^select_cuda_jit_tools()/,/^}/p' "$ENTRYPOINT_SH" > "$_FUNC_FILE"
+
+assert_eq() {
+ _label="$1"; _expected="$2"; _actual="$3"
+ if [ "$_actual" = "$_expected" ]; then
+ echo " PASS: $_label"
+ PASS=$((PASS + 1))
+ else
+ echo " FAIL: $_label (expected '$_expected', got '$_actual')"
+ FAIL=$((FAIL + 1))
+ fi
+}
+
+# $1 = compute_cap(s) the mock nvidia-smi reports, ONE PER LINE ("none" = no
+# nvidia-smi, multi-line = a mixed-GPU host). $2 = the initial libnvrtc.so.12 target
+# (default cu12.8). Prints "<PTXAS_STATE> <NVRTC_TARGET>".
+run_select() {
+ _cap="$1"
+ _init="${2:-libnvrtc.so.12.cu128.orig}"
+ _tmp=$(mktemp -d)
+ mkdir -p "$_tmp/bin"
+ if [ "$_cap" != "none" ]; then
+ # cat a file so an embedded newline in $_cap survives into the mock's output
+ printf '%s\n' "$_cap" > "$_tmp/caps.txt"
+ printf '#!/bin/sh\ncat "%s"\n' "$_tmp/caps.txt" > "$_tmp/bin/nvidia-smi"
+ chmod +x "$_tmp/bin/nvidia-smi"
+ fi
+ _nvrtc="$_tmp/studio/unsloth_studio/lib/python3.12/site-packages/nvidia/cuda_nvrtc/lib"
+ mkdir -p "$_nvrtc"
+ : > "$_nvrtc/libnvrtc.so.12.cu128.orig" # real cu12.8 lib
+ : > "$_nvrtc/libnvrtc.so.13.stub" # stand-in cu13 lib
+ ln -sf libnvrtc.so.13.stub "$_nvrtc/libnvrtc.so.12.cu13" # staged cu13 alias
+ ln -sf "$_init" "$_nvrtc/libnvrtc.so.12" # cu12.8 default (or stale cu13)
+ bash -c '
+ set -euo pipefail
+ export PATH="'"$_tmp"'/bin:/usr/bin:/bin"
+ export UNSLOTH_STUDIO_HOME="'"$_tmp"'/studio"
+ unset TRITON_PTXAS_PATH || true
+ . "'"$_FUNC_FILE"'"
+ select_cuda_jit_tools || true
+ printf "%s %s\n" "${TRITON_PTXAS_PATH:-UNSET}" "$(readlink "'"$_nvrtc"'/libnvrtc.so.12")"
+ '
+ rm -rf "$_tmp"
+}
+
+echo "=== test_select_cuda_jit_tools ==="
+
+# non-datacenter arches: the cu12.8 default needs no write, and ptxas stays unset so
+# Triton keeps its bundled cu12.8 one
+assert_eq "sm_80 Ampere -> cu128 default kept" "UNSET libnvrtc.so.12.cu128.orig" "$(run_select 8.0)"
+assert_eq "sm_90 Hopper -> cu128 default kept" "UNSET libnvrtc.so.12.cu128.orig" "$(run_select 9.0)"
+assert_eq "sm_100 B200 -> cu128 default kept" "UNSET libnvrtc.so.12.cu128.orig" "$(run_select 10.0)"
+assert_eq "sm_120 RTX50 -> cu128 default kept" "UNSET libnvrtc.so.12.cu128.orig" "$(run_select 12.0)"
+assert_eq "no nvidia-smi -> cu128 default kept" "UNSET libnvrtc.so.12.cu128.orig" "$(run_select none)"
+
+# ptxas stays UNSET only because the test host has no cuda-13.0/bin/ptxas
+assert_eq "sm_103 B300 -> cu13 NVRTC selected" "UNSET libnvrtc.so.12.cu13" "$(run_select 10.3)"
+assert_eq "sm_121 DGX Spark -> cu13 NVRTC selected" "UNSET libnvrtc.so.12.cu13" "$(run_select 12.1)"
+
+# a datacenter Blackwell BEHIND an H100 must still switch: every cap is scanned
+assert_eq "H100 then B300 -> cu13 NVRTC selected" "UNSET libnvrtc.so.12.cu13" "$(run_select "$(printf '9.0\n10.3')")"
+assert_eq "B200 then GB10 -> cu13 NVRTC selected" "UNSET libnvrtc.so.12.cu13" "$(run_select "$(printf '10.0\n12.1')")"
+assert_eq "B300 then H100 -> cu13 NVRTC selected" "UNSET libnvrtc.so.12.cu13" "$(run_select "$(printf '10.3\n9.0')")"
+assert_eq "H100 then A100 -> cu128 default kept" "UNSET libnvrtc.so.12.cu128.orig" "$(run_select "$(printf '9.0\n8.0')")"
+
+# a cu13 selection left in the writable layer by an earlier boot must be reversed
+assert_eq "A100 after B300 -> cu128 restored" "UNSET libnvrtc.so.12.cu128.orig" "$(run_select 8.0 libnvrtc.so.12.cu13)"
+assert_eq "no GPU after B300 -> cu128 restored" "UNSET libnvrtc.so.12.cu128.orig" "$(run_select none libnvrtc.so.12.cu13)"
+assert_eq "B300 after B300 -> cu13 kept" "UNSET libnvrtc.so.12.cu13" "$(run_select 10.3 libnvrtc.so.12.cu13)"
+
+rm -f "$_FUNC_FILE"
+
+echo ""
+echo "Results: $PASS passed, $FAIL failed"
+[ "$FAIL" -eq 0 ] || exit 1
diff --git a/tests/studio/install/test_install_llama_prebuilt_logic.py b/tests/studio/install/test_install_llama_prebuilt_logic.py
index 968ecb302a4..52ae197ee51 100644
--- a/tests/studio/install/test_install_llama_prebuilt_logic.py
+++ b/tests/studio/install/test_install_llama_prebuilt_logic.py
@@ -1537,12 +1537,14 @@ def test_activate_install_tree_keeps_existing_install_when_aside_move_fails(
original_replace = INSTALL_LLAMA_PREBUILT.os.replace
- def cross_device_replace(src, dst):
+ # EIO, not EXDEV: a cross-device link is the one rename failure the aside-move
+ # now completes by copy, so it is no longer an example of a move that fails
+ def failing_replace(src, dst):
if Path(src) == install_dir:
- raise OSError(errno.EXDEV, "Invalid cross-device link")
+ raise OSError(errno.EIO, "Input/output error")
return original_replace(src, dst)
- monkeypatch.setattr(INSTALL_LLAMA_PREBUILT.os, "replace", cross_device_replace)
+ monkeypatch.setattr(INSTALL_LLAMA_PREBUILT.os, "replace", failing_replace)
with pytest.raises(
PrebuiltFallback,
@@ -1559,6 +1561,93 @@ def test_activate_install_tree_keeps_existing_install_when_aside_move_fails(
assert "existing install could not be moved aside; leaving it in place" in output
+def test_activate_install_tree_copies_the_existing_install_aside_across_devices(
+ tmp_path: Path, monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+):
+ install_dir = tmp_path / "llama.cpp"
+ install_dir.mkdir()
+ (install_dir / "old.txt").write_text("old install\n")
+
+ staging_dir = create_install_staging_dir(install_dir)
+ (staging_dir / "new.txt").write_text("new install\n")
+ monkeypatch.setattr(INSTALL_LLAMA_PREBUILT, "confirm_install_tree", lambda *_args: None)
+
+ original_replace = INSTALL_LLAMA_PREBUILT.os.replace
+
+ def cross_device_replace(src, dst):
+ if Path(src) == install_dir:
+ raise OSError(errno.EXDEV, "Invalid cross-device link")
+ return original_replace(src, dst)
+
+ monkeypatch.setattr(INSTALL_LLAMA_PREBUILT.os, "replace", cross_device_replace)
+
+ # a Docker studio build moves the base image's llama.cpp onto a different overlay
+ # layer, where rename cannot reach and the copy fallback has to carry it
+ activate_install_tree(staging_dir, install_dir, linux_host())
+
+ assert (install_dir / "new.txt").read_text() == "new install\n"
+ assert not staging_dir.exists()
+
+ captured = capsys.readouterr()
+ output = captured.out + captured.err
+ assert "copy+publish" in output
+
+
+def test_move_install_dir_aside_leaves_no_partial_tree_when_the_copy_fails(
+ tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+):
+ src = tmp_path / "llama.cpp"
+ src.mkdir()
+ (src / "old.txt").write_text("old install\n")
+ dst = tmp_path / "llama.cpp.rollback-20250101000000-1"
+
+ def cross_device_replace(from_path, to_path):
+ raise OSError(errno.EXDEV, "Invalid cross-device link")
+
+ def failing_copytree(*_args, **_kwargs):
+ raise OSError(errno.ENOSPC, "No space left on device")
+
+ monkeypatch.setattr(INSTALL_LLAMA_PREBUILT.os, "replace", cross_device_replace)
+ monkeypatch.setattr(INSTALL_LLAMA_PREBUILT.shutil, "copytree", failing_copytree)
+
+ with pytest.raises(OSError, match = "No space left on device"):
+ INSTALL_LLAMA_PREBUILT.move_install_dir_aside(src, dst)
+
+ # callers read dst.exists() as proof of a COMPLETE tree
+ assert not dst.exists()
+ assert not dst.with_name(dst.name + ".copying").exists()
+ assert (src / "old.txt").read_text() == "old install\n"
+
+
+def test_move_install_dir_aside_refuses_to_copy_a_linked_install(
+ tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+):
+ target = tmp_path / "real-install-elsewhere"
+ target.mkdir()
+ (target / "old.txt").write_text("old install\n")
+
+ src = tmp_path / "llama.cpp"
+ try:
+ src.symlink_to(target, target_is_directory = True)
+ except OSError as exc:
+ pytest.skip(f"directory symlinks unavailable: {exc}")
+ dst = tmp_path / "llama.cpp.rollback-20250101000000-1"
+
+ def cross_device_replace(from_path, to_path):
+ raise OSError(errno.EXDEV, "Invalid cross-device link")
+
+ monkeypatch.setattr(INSTALL_LLAMA_PREBUILT.os, "replace", cross_device_replace)
+
+ # copytree always follows the root, so this would duplicate a checkout the
+ # installer does not own
+ with pytest.raises(OSError, match = "cross-device"):
+ INSTALL_LLAMA_PREBUILT.move_install_dir_aside(src, dst)
+
+ assert not dst.exists()
+ assert src.is_symlink()
+ assert (target / "old.txt").read_text() == "old install\n"
+
+
def test_activate_install_tree_keeps_existing_install_when_aside_move_hits_busy_lock(
tmp_path: Path, monkeypatch: pytest.MonkeyPatch
):
@@ -1733,6 +1822,49 @@ def test_activate_staged_dir_copies_when_replace_hits_busy_lock(
assert "falling back to file-by-file copy" in captured.out + captured.err
[email protected](os.name == "nt", reason = "soname links are a Unix bundle layout")
[email protected]("dst_exists", [False, True])
+def test_activate_staged_dir_copy_keeps_soname_links(
+ tmp_path: Path, monkeypatch: pytest.MonkeyPatch, dst_exists: bool
+):
+ """The EXDEV copy must not turn a bundle's soname chain into duplicate libraries.
+
+ A Linux llama.cpp release ships libllama.so -> libllama.so.0 -> libllama.so.0.3.0
+ (10 such links in b10715), and copytree's default symlinks = False dereferences
+ every one of them into a full copy of the shared library.
+ """
+ staging_dir = tmp_path / "llama.cpp.staging-test"
+ staging_dir.mkdir()
+ real = staging_dir / "libllama.so.0.3.0"
+ real.write_bytes(b"\0" * 4096)
+ (staging_dir / "libllama.so.0").symlink_to("libllama.so.0.3.0")
+ (staging_dir / "libllama.so").symlink_to("libllama.so.0")
+ dst = tmp_path / "llama.cpp"
+ if dst_exists:
+ # os.replace also refuses an EMPTY existing dst cross-device, and the copy
+ # still has to complete there
+ dst.mkdir()
+
+ def cross_device_replace(src, dst_arg):
+ raise OSError(errno.EXDEV, "Invalid cross-device link", str(src))
+
+ monkeypatch.setattr(INSTALL_LLAMA_PREBUILT.os, "replace", cross_device_replace)
+
+ activate_staged_dir(staging_dir, dst)
+
+ assert (dst / "libllama.so.0.3.0").read_bytes() == b"\0" * 4096
+ for link, target in (("libllama.so.0", "libllama.so.0.3.0"), ("libllama.so", "libllama.so.0")):
+ assert (
+ dst / link
+ ).is_symlink(), f"{link} was dereferenced into a copy of the library it aliases"
+ assert os.readlink(dst / link) == target
+ on_disk = sum(p.lstat().st_size for p in dst.iterdir())
+ assert on_disk < 2 * len(
+ b"\0" * 4096
+ ), f"the activated tree duplicated libraries ({on_disk} bytes)"
+ assert not staging_dir.exists()
+
+
def test_activate_staged_dir_reraises_non_busy_errors(
tmp_path: Path, monkeypatch: pytest.MonkeyPatch
):
diff --git a/tests/studio/test_branding_guard.py b/tests/studio/test_branding_guard.py
new file mode 100644
index 00000000000..01ee54cdb6e
--- /dev/null
+++ b/tests/studio/test_branding_guard.py
@@ -0,0 +1,240 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-Present the Unsloth team. See /studio/LICENSE.AGPL-3.0
+"""Tests for the Unsloth Docker Studio branding / AGPLv3 integrity guard.
+
+verify_branding() runs against a staged temp tree mirroring the installed image
+layout, so no container or built labextension is required.
+"""
+
+import json
+import os
+import sys
+
+import pytest
+
+HERE = os.path.dirname(os.path.abspath(__file__))
+REPO = os.path.abspath(os.path.join(HERE, "..", ".."))
+sys.path.insert(0, os.path.join(REPO, "docker", "jupyter"))
+
+import unsloth_branding as ub # noqa: E402
+
+
+def _stage(tmp_path):
+ venv_share = tmp_path / "venv-share"
+ js_dir = tmp_path / "jupyter_server"
+
+ (venv_share).mkdir(parents = True)
+ (venv_share / "UNSLOTH_LICENSE.AGPL-3.0").write_text(
+ " GNU AFFERO GENERAL PUBLIC LICENSE\n"
+ " Version 3, 19 November 2007\n"
+ " Copyright (C) 2007 Free Software Foundation, Inc.\n",
+ encoding = "utf-8",
+ )
+
+ (venv_share / "lab" / "settings").mkdir(parents = True)
+ (venv_share / "lab" / "settings" / "overrides.json").write_text(
+ json.dumps({"@jupyterlab/apputils-extension:themes": {"theme": ub.THEME_NAME}}),
+ encoding = "utf-8",
+ )
+
+ labext = venv_share / "labextensions" / ub.LABEXT_NAME
+ (labext / "static").mkdir(parents = True)
+ (labext / "package.json").write_text(json.dumps({"name": ub.LABEXT_NAME}), encoding = "utf-8")
+ bundle = " ".join(
+ [
+ ub.PHRASE,
+ ub.SHORT_LABEL,
+ ub.COPYRIGHT,
+ ub.AGPL_URL,
+ ub.ABOUT_PLUGIN_ID,
+ ub.SPLASH_PLUGIN_ID,
+ ub.LOGO_DATA_URI_PREFIX + "AAAAdummyimagebytes",
+ ]
+ )
+ (labext / "static" / "remoteEntry.abc123.js").write_text(bundle, encoding = "utf-8")
+
+ (js_dir / "templates").mkdir(parents = True)
+ (js_dir / "templates" / "login.html").write_text(
+ "Built by the Unsloth team. Apache 2.0, AGPLv3 License Link\n"
+ "Copyright 2026-Present the Unsloth team.\n"
+ "https://github.com/unslothai/unsloth#license\n"
+ "https://github.com/unslothai/unsloth\n",
+ encoding = "utf-8",
+ )
+
+ (js_dir / "static" / "favicons").mkdir(parents = True)
+ (js_dir / "static" / "favicons" / "favicon.ico").write_bytes(b"\x00\x00\x01\x00icon")
+ (js_dir / "static" / "logo").mkdir(parents = True)
+ (js_dir / "static" / "logo" / "logo.png").write_bytes(b"\x89PNG\r\n\x1a\nlogo")
+
+ # config_dirs = [] keeps the tree hermetic: no host jupyter config is scanned
+ return ub.resolve_paths(
+ venv_share = str(venv_share),
+ jupyter_server_dir = str(js_dir),
+ config_dirs = [],
+ )
+
+
+def test_positive_clean_tree_passes(tmp_path):
+ paths = _stage(tmp_path)
+ assert ub.verify_branding(paths) == []
+
+
+def _remove_license(paths):
+ os.remove(paths["license"])
+
+
+def _blank_license(paths):
+ with open(paths["license"], "w", encoding = "utf-8") as f:
+ f.write("All rights reserved. Proprietary. Resold by someone else.\n")
+
+
+def _remove_login(paths):
+ os.remove(paths["login"])
+
+
+def _strip_login_source(paths):
+ with open(paths["login"], encoding = "utf-8") as f:
+ text = f.read()
+ with open(paths["login"], "w", encoding = "utf-8") as f:
+ f.write(text.replace(ub.SOURCE_URL, "https://example.com/forks"))
+
+
+def _strip_login_copyright(paths):
+ with open(paths["login"], encoding = "utf-8") as f:
+ text = f.read()
+ with open(paths["login"], "w", encoding = "utf-8") as f:
+ f.write(text.replace(ub.COPYRIGHT, "Copyright someone else"))
+
+
+def _drop_theme(paths):
+ with open(paths["overrides"], "w", encoding = "utf-8") as f:
+ f.write("{}")
+
+
+def _rebrand_labext(paths):
+ with open(paths["labext_pkg"], "w", encoding = "utf-8") as f:
+ f.write(json.dumps({"name": "totally-not-unsloth"}))
+
+
+def _strip_bundle_phrase(paths):
+ import glob
+ for path in glob.glob(os.path.join(paths["labext_static"], "*.js")):
+ with open(path, encoding = "utf-8") as f:
+ text = f.read()
+ with open(path, "w", encoding = "utf-8") as f:
+ f.write(text.replace(ub.PHRASE, "").replace(ub.SHORT_LABEL, ""))
+
+
+def _strip_bundle_logo(paths):
+ import glob
+ for path in glob.glob(os.path.join(paths["labext_static"], "*.js")):
+ with open(path, encoding = "utf-8") as f:
+ text = f.read()
+ with open(path, "w", encoding = "utf-8") as f:
+ f.write(text.replace(ub.LOGO_DATA_URI_PREFIX, "data:image/png;base64,XXXX"))
+
+
+def _remove_logo_png(paths):
+ os.remove(paths["logo"])
+
+
+def _empty_favicon(paths):
+ open(paths["favicon"], "w").close()
+
+
+def _disable_unsloth_ext(paths):
+ with open(paths["page_configs"][0], "w", encoding = "utf-8") as f:
+ json.dump({"disabledExtensions": {ub.LABEXT_NAME: True}}, f)
+
+
+def _disable_unsloth_plugin(paths):
+ with open(paths["page_configs"][0], "w", encoding = "utf-8") as f:
+ json.dump({"disabledExtensions": {ub.ABOUT_PLUGIN_ID: True}}, f)
+
+
+def _disable_unsloth_ext_list_form(paths):
+ with open(paths["page_configs"][0], "w", encoding = "utf-8") as f:
+ json.dump({"disabledExtensions": [ub.SPLASH_PLUGIN_ID]}, f)
+
+
+ "mutate",
+ [
+ _remove_license,
+ _blank_license,
+ _remove_login,
+ _strip_login_source,
+ _strip_login_copyright,
+ _drop_theme,
+ _rebrand_labext,
+ _strip_bundle_phrase,
+ _strip_bundle_logo,
+ _remove_logo_png,
+ _empty_favicon,
+ _disable_unsloth_ext,
+ _disable_unsloth_plugin,
+ _disable_unsloth_ext_list_form,
+ ],
+)
+def test_negative_each_marker_is_enforced(tmp_path, mutate):
+ paths = _stage(tmp_path)
+ assert ub.verify_branding(paths) == [], "baseline should be clean before mutation"
+ mutate(paths)
+ problems = ub.verify_branding(paths)
+ assert problems, "stripping " + mutate.__name__ + " must be detected"
+
+
+def test_disabling_stock_plugins_is_allowed(tmp_path):
+ """We disable the stock logo/splash ourselves; the guard must not flag those."""
+ paths = _stage(tmp_path)
+ with open(paths["page_configs"][0], "w", encoding = "utf-8") as f:
+ json.dump(
+ {
+ "disabledExtensions": {
+ "@jupyterlab/application-extension:logo": True,
+ "@jupyterlab/apputils-extension:splash": True,
+ }
+ },
+ f,
+ )
+ assert ub.verify_branding(paths) == []
+
+
+def test_attribution_sources_have_no_encoded_obfuscation():
+ """Plain readable strings only, so antivirus scanners have nothing to trip on."""
+ src_dir = os.path.join(REPO, "docker", "jupyter")
+ files = [
+ os.path.join(src_dir, "unsloth_branding.py"),
+ os.path.join(src_dir, "unsloth_labext", "src", "branding.ts"),
+ os.path.join(src_dir, "unsloth_labext", "src", "about.ts"),
+ os.path.join(src_dir, "unsloth_labext", "src", "splash.ts"),
+ ]
+ forbidden = [
+ "b64decode",
+ "b64encode",
+ "atob(",
+ "btoa(",
+ "fromCharCode",
+ "unescape(",
+ "rot13",
+ "codecs.decode",
+ ]
+ for path in files:
+ with open(path, encoding = "utf-8") as f:
+ text = f.read()
+ for token in forbidden:
+ assert token not in text, path + " uses obfuscation token: " + token
+
+
+def test_canonical_phrase_is_plain_text_in_definition_files():
+ """branding.ts holds the full PHRASE as ONE contiguous literal, so webpack keeps it
+ whole in the bundle for the guard to grep."""
+ src_dir = os.path.join(REPO, "docker", "jupyter")
+ ts = open(
+ os.path.join(src_dir, "unsloth_labext", "src", "branding.ts"), encoding = "utf-8"
+ ).read()
+ assert ub.PHRASE in ts, "branding.ts must hold the full PHRASE as one literal"
+ py = open(os.path.join(src_dir, "unsloth_branding.py"), encoding = "utf-8").read()
+ for marker in (ub.SHORT_LABEL, ub.COPYRIGHT, ub.SOURCE_URL, ub.AGPL_URL, ub.THEME_NAME):
+ assert marker in py, "unsloth_branding.py missing plain marker: " + marker
diff --git a/tests/test_fa2_fast_generate_bypass.py b/tests/test_fa2_fast_generate_bypass.py
index 5ca30a2642b..713c214c197 100644
--- a/tests/test_fa2_fast_generate_bypass.py
+++ b/tests/test_fa2_fast_generate_bypass.py
@@ -4,12 +4,22 @@ import ast
import inspect
import os
from contextlib import nullcontext
+from importlib.metadata import version as installed_version
from pathlib import Path
from types import SimpleNamespace
+from packaging.version import Version
+
VISION_PATH = Path(__file__).parents[1] / "unsloth" / "models" / "vision.py"
+# The exec'd copy below needs the same two module globals vision.py imports at its
+# top. packaging and importlib.metadata rather than unsloth_zoo.utils.Version and
+# transformers.__version__, because importing unsloth_zoo pulls in bitsandbytes and
+# CUDA -- the whole reason this file rebuilds the function from source. Only the names
+# have to resolve: NUM_LOGITS_TO_KEEP is seeded below, so neither branch touches kwargs.
+TRANSFORMERS_VERSION = installed_version("transformers")
+
def _load_function(name, namespace):
tree = ast.parse(VISION_PATH.read_text(encoding = "utf-8"))
@@ -204,6 +214,8 @@ def test_wrapper_dispatch_preserves_normalization_and_selects_expected_path():
"_unsloth_generate_accepts_kwarg": lambda model, name: False,
"NUM_LOGITS_TO_KEEP": {architecture: None},
"DEVICE_TYPE_TORCH": "cuda",
+ "Version": Version,
+ "transformers_version": TRANSFORMERS_VERSION,
"_uses_flash_attention_for_generation": uses_flash_attention,
"_clear_generation_caches": clear_generation_caches,
}
@@ -287,6 +299,8 @@ def test_flash_attention_fallback_pins_a_dynamic_cache():
"_unsloth_generate_accepts_kwarg": lambda model, name: False,
"NUM_LOGITS_TO_KEEP": {"Qwen3VLForConditionalGeneration": None},
"DEVICE_TYPE_TORCH": "cuda",
+ "Version": Version,
+ "transformers_version": TRANSFORMERS_VERSION,
"_uses_flash_attention_for_generation": uses_flash_attention,
"_clear_generation_caches": clear_generation_caches,
}
diff --git a/tests/test_generate_kwarg_gate.py b/tests/test_generate_kwarg_gate.py
index 00b3ddf6ee6..3f0f2fc9449 100644
--- a/tests/test_generate_kwarg_gate.py
+++ b/tests/test_generate_kwarg_gate.py
@@ -130,6 +130,59 @@ def test_generate_kwarg_gate():
assert got is expected, f"{name}: got {got}, expected {expected}"
+# transformers >= 5 injects logits_to_keep=1 in generate() itself, but the injection
+# is guarded by `"logits_to_keep" not in model_kwargs`, so it is a DEFAULT: popping
+# unconditionally turns an explicit logits_to_keep=0 into 1. Only the values the
+# strict validator would raise on may be stripped.
+
+
+def _filter_logits_kwargs(model, kwargs):
+ """The v5 branch of unsloth_base_fast_generate, as a testable function."""
+ for key in ("logits_to_keep", "num_logits_to_keep"):
+ if key in kwargs and not accepts(model, key):
+ kwargs.pop(key, None)
+ return kwargs
+
+
+def test_v5_preserves_a_supported_caller_value():
+ model = PrepHasKwargs_ForwardHasKey()
+ # 0 means "all logits": rewriting it to 1 changes the output shape
+ assert _filter_logits_kwargs(model, {"logits_to_keep": 0}) == {"logits_to_keep": 0}
+ assert _filter_logits_kwargs(model, {"logits_to_keep": 5}) == {"logits_to_keep": 5}
+
+
+def test_v5_strips_a_value_the_model_would_reject():
+ # renamed away in v5, so the validator raises on it
+ model = PrepHasKwargs_ForwardHasKey()
+ assert _filter_logits_kwargs(model, {"num_logits_to_keep": 1}) == {}
+ # a VLM whose top-level forward has no logits_to_keep at all
+ assert _filter_logits_kwargs(NoPrepare(), {"logits_to_keep": 1}) == {}
+
+
+def test_v5_leaves_other_kwargs_alone():
+ model = PrepHasKwargs_ForwardHasKey()
+ out = _filter_logits_kwargs(model, {"logits_to_keep": 2, "max_new_tokens": 8})
+ assert out == {"logits_to_keep": 2, "max_new_tokens": 8}
+
+
+def test_source_has_no_unconditional_pop():
+ src = open(VISION, encoding = "utf-8").read()
+ assert (
+ 'kwargs.pop("logits_to_keep", None)\n kwargs.pop("num_logits_to_keep", None)'
+ not in src
+ ), "the v5 branch must not drop caller-supplied logits_to_keep unconditionally"
+
+
+def test_the_v5_gate_uses_the_plain_release_sentinel():
+ # unsloth_zoo's Version() is not packaging's: it keeps the leading numeric run and
+ # appends ".1" for any suffix, so a "5.0.0.dev0" sentinel is 5.0.0.1 and 5.0.0 FINAL
+ # sorts below it, down the legacy 4.x branch. The plain sentinel still catches the
+ # prereleases, which normalize to 5.0.0.1 either way.
+ src = open(VISION, encoding = "utf-8").read()
+ assert 'Version(transformers_version) < Version("5.0.0")' in src
+ assert 'Version("5.0.0.dev0")' not in src
+
+
if __name__ == "__main__":
test_generate_kwarg_gate()
for name, _, _, _ in CASES:
diff --git a/tests/validate_studio_features.py b/tests/validate_studio_features.py
new file mode 100644
index 00000000000..fe2d180def8
--- /dev/null
+++ b/tests/validate_studio_features.py
@@ -0,0 +1,255 @@
+#!/usr/bin/env python3
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-Present the Unsloth team. See /studio/LICENSE.AGPL-3.0
+
+"""Cross-platform validation of the Unsloth Docker JupyterLab/notebook features.
+
+Runs WITHOUT Docker or a GPU, so it executes on every CI lane, and it exercises the
+real notebook-helper logic rather than py_compile.
+
+Usage: python tests/validate_studio_features.py
+Exit 0 = all checks pass; non-zero = at least one failed.
+"""
+
+from __future__ import annotations
+
+import importlib
+import json
+import os
+import sys
+
+ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+DOCKER = os.path.join(ROOT, "docker")
+JUPYTER = os.path.join(DOCKER, "jupyter")
+LABEXT = os.path.join(JUPYTER, "unsloth_labext")
+sys.path.insert(0, DOCKER)
+
+_failures: list[str] = []
+
+
+def check(
+ name: str,
+ cond: bool,
+ detail: str = "",
+) -> None:
+ status = "PASS" if cond else "FAIL"
+ print(f" [{status}] {name}" + (f" -- {detail}" if detail and not cond else ""))
+ if not cond:
+ _failures.append(name)
+
+
+def test_colab_compat() -> None:
+ print("colab cell-magic compat (unsloth_colab_compat):")
+ m = importlib.import_module("unsloth_colab_compat")
+ out = m.colab_cell_magic_fix(["#@title Setup\n", "%%capture\n", "!pip install x\n"])
+ check("magic hoisted above #@title", out[0] == "%%capture\n" and "#@title Setup\n" in out)
+ same = ["%%capture\n", "print(1)\n"]
+ check("no-op when magic already first", m.colab_cell_magic_fix(same) == same)
+ plain = ["x = 1\n", "y = 2\n"]
+ check("plain cell untouched", m.colab_cell_magic_fix(plain) == plain)
+ wf = ["#@title Config\n", "%%writefile config.json\n", "{}\n"]
+ check("content magic (%%writefile) left untouched", m.colab_cell_magic_fix(wf) == wf)
+ bash = ["#@title Run\n", "%%bash\n", "echo hi\n"]
+ check("safe magic (%%bash) hoisted", m.colab_cell_magic_fix(bash)[0] == "%%bash\n")
+
+
+def test_nb_view() -> None:
+ print("notebook view (unsloth_nb_view):")
+ v = importlib.import_module("unsloth_nb_view")
+ check(
+ "clean_section dash/slash -> space",
+ v.clean_section("### GRPO-Reinforcement/Learning Notebooks")
+ == "GRPO Reinforcement Learning Notebooks",
+ v.clean_section("### GRPO-Reinforcement/Learning Notebooks"),
+ )
+ check(
+ "clean_section strips hashes/space",
+ v.clean_section("## Main Notebooks ") == "Main Notebooks",
+ )
+
+
+def test_strip() -> None:
+ print("notebook strip (unsloth_nb_strip_colab):")
+ s = importlib.import_module("unsloth_nb_strip_colab")
+ nb = {
+ "metadata": {"widgets": {"application/vnd.jupyter.widget-state+json": {"x": 1}}},
+ "cells": [
+ {
+ "cell_type": "markdown",
+ "source": [
+ 'To run this, press "Runtime" ... Tesla T4 Google Colab instance!\n',
+ "\n",
+ "You will learn how to ...\n",
+ ],
+ },
+ {
+ "cell_type": "code",
+ "source": ["print(1)\n"],
+ "outputs": [
+ {"output_type": "stream", "name": "stdout", "text": "ok\n"},
+ {
+ "output_type": "display_data",
+ "data": {
+ "application/vnd.jupyter.widget-view+json": {"model_id": "abc"},
+ "text/plain": "0%| | 0/10",
+ },
+ },
+ ],
+ },
+ ],
+ }
+ changed1 = s._strip_intro(nb)
+ changed2 = s._clean_widgets(nb)
+ check(
+ "intro line stripped",
+ changed1 and not any("to run this, press" in (l.lower()) for l in nb["cells"][0]["source"]),
+ )
+ check("intro body kept", any("You will learn" in l for l in nb["cells"][0]["source"]))
+ wv = sum(
+ 1
+ for c in nb["cells"]
+ for o in (c.get("outputs", []) or [])
+ if "application/vnd.jupyter.widget-view+json" in (o.get("data", {}) or {})
+ )
+ check("widget-view outputs removed", changed2 and wv == 0)
+ check(
+ "non-widget outputs kept",
+ any(
+ o.get("output_type") == "stream"
+ for c in nb["cells"]
+ for o in (c.get("outputs", []) or [])
+ ),
+ )
+ check("metadata.widgets removed", "widgets" not in nb["metadata"])
+ check("strip idempotent", not s._strip_intro(nb) and not s._clean_widgets(nb))
+
+
+def test_sidecar_log_gate() -> None:
+ print("sidecar log gate (unsloth_nb_compat):")
+ c = importlib.import_module("unsloth_nb_compat")
+ old = os.environ.pop("UNSLOTH_ENABLE_LOGGING", None)
+ try:
+ check("logging off by default", c._logging_enabled() is False)
+ os.environ["UNSLOTH_ENABLE_LOGGING"] = "1"
+ check("logging on with env=1", c._logging_enabled() is True)
+ os.environ["UNSLOTH_ENABLE_LOGGING"] = "0"
+ check("logging off with env=0", c._logging_enabled() is False)
+ finally:
+ os.environ.pop("UNSLOTH_ENABLE_LOGGING", None)
+ if old is not None:
+ os.environ["UNSLOTH_ENABLE_LOGGING"] = old
+
+
+def test_overrides() -> None:
+ print("jupyterlab defaults (jupyter/overrides.json):")
+ path = os.path.join(JUPYTER, "overrides.json")
+ check("overrides.json exists", os.path.isfile(path))
+ if not os.path.isfile(path):
+ return
+ with open(path, encoding = "utf-8") as f:
+ d = json.load(f) # raises, so invalid JSON fails CI
+ themes = d.get("@jupyterlab/apputils-extension:themes", {})
+ check(
+ "default theme = Unsloth Dark",
+ themes.get("theme") == "Unsloth Dark",
+ str(themes.get("theme")),
+ )
+ check("adaptive theme on", themes.get("adaptive-theme") is True)
+ check("preferred dark = Unsloth Dark", themes.get("preferred-dark-theme") == "Unsloth Dark")
+ tracker = d.get("@jupyterlab/notebook-extension:tracker", {})
+ check(
+ "windowingMode none",
+ tracker.get("windowingMode") == "none",
+ str(tracker.get("windowingMode")),
+ )
+ notif = d.get("@jupyterlab/apputils-extension:notification", {})
+ check(
+ "news prompt off",
+ str(notif.get("fetchNews")) == "false" and notif.get("checkForUpdates") is False,
+ )
+ panel = d.get("@jupyterlab/notebook-extension:panel", {})
+ labels = [t.get("label", "") for t in panel.get("toolbar", [])]
+ check(
+ "Restart & Run All label (single >>)",
+ any(l == "Restart & Run All" for l in labels) and not any(">>" in l for l in labels),
+ str(labels),
+ )
+
+
+def test_labext_and_branding() -> None:
+ print("labextension + branding assets:")
+ pkg = os.path.join(LABEXT, "package.json")
+ check("labext package.json exists", os.path.isfile(pkg))
+ if os.path.isfile(pkg):
+ with open(pkg, encoding = "utf-8") as f:
+ p = json.load(f)
+ check("labext name unsloth-jupyterlab", p.get("name") == "unsloth-jupyterlab")
+ check("labext themePath set", bool(p.get("jupyterlab", {}).get("themePath")))
+ src_dir = os.path.join(LABEXT, "src")
+ all_src = ""
+ if os.path.isdir(src_dir):
+ for fn in sorted(os.listdir(src_dir)):
+ if fn.endswith(".ts"):
+ with open(os.path.join(src_dir, fn), encoding = "utf-8") as f:
+ all_src += f.read() + "\n"
+ for plug in [
+ "unsloth-jupyterlab:theme",
+ "unsloth-jupyterlab:cell-nav",
+ "unsloth-jupyterlab:logo",
+ "unsloth-jupyterlab:colab-title",
+ "unsloth-jupyterlab:output-select-all",
+ "unsloth-jupyterlab:ui-chrome",
+ ]:
+ check(f"plugin present: {plug}", plug in all_src)
+ index = os.path.join(src_dir, "index.ts")
+ index_src = open(index, encoding = "utf-8").read() if os.path.isfile(index) else ""
+ check("outputSelect wired in index.ts", "outputSelectPlugin" in index_src)
+ check("uiChrome wired in index.ts", "uiChromePlugin" in index_src)
+ check("right activity bar hidden", "jp-mod-right" in all_src and "display: none" in all_src)
+ check("ctrl+A output select", "selectNodeContents" in all_src)
+ # the remembered pointer-down must be revalidated against the ACTIVE cell, or
+ # Ctrl+A on a later cell selects the old output
+ check(
+ "ctrl+A fallback revalidated",
+ "isConnected" in all_src and "jp-mod-active" in all_src,
+ )
+ login = os.path.join(JUPYTER, "login.html")
+ login_src = open(login, encoding = "utf-8").read() if os.path.isfile(login) else ""
+ check("login.html branded", "unsloth-login-card" in login_src)
+ check(
+ "login.html uses sloth stickers",
+ 'static_url("sloth/' in login_src or "static_url('sloth/" in login_src,
+ )
+ check("favicon.ico present", os.path.isfile(os.path.join(JUPYTER, "favicon.ico")))
+ check("logo.png present", os.path.isfile(os.path.join(JUPYTER, "logo.png")))
+ check(
+ "sloth sticker installer present",
+ os.path.isfile(os.path.join(JUPYTER, "install_sloth_stickers.py")),
+ )
+
+
+def main() -> int:
+ print("=== Unsloth Studio/notebook feature validation ===")
+ for t in (
+ test_colab_compat,
+ test_nb_view,
+ test_strip,
+ test_sidecar_log_gate,
+ test_overrides,
+ test_labext_and_branding,
+ ):
+ try:
+ t()
+ except Exception as e: # a thrown exception is a failure, not a crash
+ _failures.append(f"{t.__name__}: {e!r}")
+ print(f" [FAIL] {t.__name__} raised {e!r}")
+ print()
+ if _failures:
+ print(f"FAILED ({len(_failures)}): " + ", ".join(_failures))
+ return 1
+ print("ALL CHECKS PASSED")
+ return 0
+
+
+if __name__ == "__main__":
+ sys.exit(main())
diff --git a/unsloth/_gpu_init.py b/unsloth/_gpu_init.py
index bf771f0c677..a8897a0cf16 100644
--- a/unsloth/_gpu_init.py
+++ b/unsloth/_gpu_init.py
@@ -125,6 +125,23 @@ del maybe_set_windows_rocm_bnb_version
# Fixes https://github.com/unslothai/unsloth/issues/1266
os.environ["PROTOCOL_BUFFERS_PYTHON_IMPLEMENTATION"] = "python"
+# `docker --gpus '"device=N"'` sets NVIDIA_VISIBLE_DEVICES but not
+# CUDA_VISIBLE_DEVICES, so Inductor's compile-worker pool cannot enumerate the
+# cgroup-pinned GPU ("Could not find an active GPU backend"). Pinned ids only, not
+# "all"/"none"/"void"/"". Opt out with UNSLOTH_FORCE_SINGLE_COMPILE_WORKER=0.
+_nvd = os.environ.get("NVIDIA_VISIBLE_DEVICES", "").strip().lower()
+_cgroup_pinned = _nvd not in ("", "all", "none", "void")
+if (
+ os.environ.get("UNSLOTH_FORCE_SINGLE_COMPILE_WORKER", "auto") != "0"
+ and _cgroup_pinned
+ and "CUDA_VISIBLE_DEVICES" not in os.environ
+):
+ # honour an existing thread count, but always plant the sentinel
+ if os.environ.get("TORCHINDUCTOR_COMPILE_THREADS") in (None, "", "1"):
+ os.environ["TORCHINDUCTOR_COMPILE_THREADS"] = "1"
+ os.environ["UNSLOTH_FORCE_SINGLE_COMPILE_WORKER"] = "1"
+del _nvd, _cgroup_pinned
+
from importlib.metadata import version as importlib_version
from importlib.metadata import PackageNotFoundError
@@ -156,6 +173,46 @@ except ModuleNotFoundError:
except:
raise
+# Re-assert after unsloth_zoo's patch_torch_compile, which historically popped
+# TORCHINDUCTOR_COMPILE_THREADS.
+if os.environ.get("UNSLOTH_FORCE_SINGLE_COMPILE_WORKER", "0") == "1":
+ try:
+ torch._inductor.config.compile_threads = 1
+ except Exception:
+ pass
+ os.environ["TORCHINDUCTOR_COMPILE_THREADS"] = "1"
+
+ def _force_single_compile_worker_in_zoo():
+ setattr(
+ importlib.import_module("unsloth_zoo.temporary_patches.common"),
+ "determine_compile_threads",
+ lambda: 1,
+ )
+ # `import unsloth_zoo` above already ran temporary_patches, so its
+ # module-level options dicts are snapshots of the original count and
+ # replacing the function only reaches dicts built from here on. Those
+ # snapshots go to torch.compile as `options`, which Inductor applies as a
+ # config patch outranking both the env var and the value set above. Rewrite
+ # them IN PLACE: each dict is shared by identity with every zoo module
+ # re-exporting it and with the functools.partial in `torch_compile`.
+ for module in list(sys.modules.values()):
+ name = getattr(module, "__name__", "")
+ if name != "unsloth_zoo" and not name.startswith("unsloth_zoo."):
+ continue
+ try:
+ values = list(vars(module).values())
+ except Exception:
+ continue
+ for value in values:
+ if isinstance(value, dict) and "compile_threads" in value:
+ value["compile_threads"] = 1
+
+ try:
+ _force_single_compile_worker_in_zoo()
+ except Exception:
+ pass
+ del _force_single_compile_worker_in_zoo
+
from unsloth_zoo.device_type import (
is_hip,
get_device_type,
diff --git a/unsloth/dataprep/synthetic.py b/unsloth/dataprep/synthetic.py
index 514953aa9b6..0cba47f401e 100644
--- a/unsloth/dataprep/synthetic.py
+++ b/unsloth/dataprep/synthetic.py
@@ -277,7 +277,9 @@ class SyntheticDataKit:
stderr = subprocess.PIPE,
start_new_session = True,
)
- ready_re = re.compile(r"Starting vLLM API server(?:\s+\d+)?\s+on\b")
+ # both "Starting vLLM API server on" (<= 0.18) and "Starting vLLM server on"
+ # (0.19), with the optional server index some versions insert
+ ready_re = re.compile(r"Starting vLLM(?:\s+API)?\s+server(?:\s+\d+)?\s+on\b")
self.vllm_process = vllm_process
self.stdout_capture = PipeCapture(
vllm_process.stdout,
@@ -292,7 +294,8 @@ class SyntheticDataKit:
keep_lines = 2000,
echo = False,
name = "vLLM STDERR",
- ready_regex = None,
+ # vLLM >= 0.19 logs startup lines to STDERR
+ ready_regex = ready_re,
text = False,
)
# stderr is not printed to console, but self.stderr_capture.tail(200) prints the last 200 lines.
@@ -345,6 +348,10 @@ class SyntheticDataKit:
wait = poll_interval if remaining is None else min(poll_interval, remaining)
if self.stdout_capture.wait_for_ready(timeout = wait):
return
+ # checked BEFORE the exit/closed arms, so a server that is ready on
+ # stderr is never reported as never having started
+ if self.stderr_capture.wait_for_ready(timeout = 0):
+ return
returncode = self.vllm_process.poll()
if returncode is not None:
self._fail_vllm_server(f"exited with code {returncode} before it was ready")
diff --git a/unsloth/models/_utils.py b/unsloth/models/_utils.py
index 6e10f24f27f..9b61396fbe6 100644
--- a/unsloth/models/_utils.py
+++ b/unsloth/models/_utils.py
@@ -2226,8 +2226,10 @@ try:
# Xformers <= 0.0.32.post2 dispatches FA3 wrongly on Blackwell/RTX 50x: `capability >= (9, 0)`
# matches SM 10.0/11.0/12.0 and runs sm_90a kernels on non-Hopper GPUs (CUDA error in
# flash_fwd_launch_template.h:188). Fixed in 0.0.33 with `<= (9, 0)`; see
- # facebookresearch/xformers#1329.
- if DEVICE_TYPE == "cuda":
+ # facebookresearch/xformers#1329. is_available() as well as DEVICE_TYPE: a CUDA-built torch
+ # on a driverless host keeps DEVICE_TYPE at "cuda" and get_device_capability() would raise
+ # out of _lazy_init().
+ if DEVICE_TYPE == "cuda" and torch.cuda.is_available():
major_version, minor_version = torch.cuda.get_device_capability()
if (f"{major_version}.{minor_version}" in ("10.0", "11.0", "12.0")) and (
Version(xformers_version) <= Version("0.0.32.post2")
diff --git a/unsloth/models/vision.py b/unsloth/models/vision.py
index bbfd6d8cfc5..32056863c45 100644
--- a/unsloth/models/vision.py
+++ b/unsloth/models/vision.py
@@ -762,26 +762,43 @@ def unsloth_base_fast_generate(self, *args, **kwargs):
):
kwargs.pop("mm_token_type_ids", None)
- # VLMs do not allow logits_to_keep.
- global NUM_LOGITS_TO_KEEP
- if arch not in NUM_LOGITS_TO_KEEP:
- m = self
- # Find which is used: num_logits_to_keep or logits_to_keep
- while hasattr(m, "model"):
- if hasattr(m, "forward"):
- keys = inspect.signature(m.forward).parameters.keys()
- if "num_logits_to_keep" in keys:
- NUM_LOGITS_TO_KEEP[arch] = "num_logits_to_keep"
- break
- elif "logits_to_keep" in keys:
- NUM_LOGITS_TO_KEEP[arch] = "logits_to_keep"
- break
- m = m.model
+ # VLMs do not allow logits_to_keep, and transformers >= 5.0 sets it itself in
+ # generate(), so pre-injecting there is redundant and the arch walk below can
+ # pick a key the top-level model rejects.
+ # The sentinel is the plain release: this Version() keeps only the leading
+ # numeric run and appends ".1" for a suffix, so a "5.0.0.dev0" sentinel would
+ # normalize to 5.0.0.1 and send 5.0.0 FINAL down the legacy branch. Prereleases
+ # still gate correctly, since they normalize to 5.0.0.1 either way.
+ if Version(transformers_version) < Version("5.0.0"):
+ global NUM_LOGITS_TO_KEEP
if arch not in NUM_LOGITS_TO_KEEP:
- NUM_LOGITS_TO_KEEP[arch] = None
- key = NUM_LOGITS_TO_KEEP[arch]
- if key is not None and key not in kwargs and _unsloth_generate_accepts_kwarg(self, key):
- kwargs[key] = 1
+ m = self
+ # find which is used: num_logits_to_keep or logits_to_keep
+ while hasattr(m, "model"):
+ if hasattr(m, "forward"):
+ keys = inspect.signature(m.forward).parameters.keys()
+ if "num_logits_to_keep" in keys:
+ NUM_LOGITS_TO_KEEP[arch] = "num_logits_to_keep"
+ break
+ elif "logits_to_keep" in keys:
+ NUM_LOGITS_TO_KEEP[arch] = "logits_to_keep"
+ break
+ m = m.model
+ if arch not in NUM_LOGITS_TO_KEEP:
+ NUM_LOGITS_TO_KEEP[arch] = None
+ key = NUM_LOGITS_TO_KEEP[arch]
+ if key is not None and key not in kwargs and _unsloth_generate_accepts_kwarg(self, key):
+ kwargs[key] = 1
+ else:
+ # v5's own injection is guarded by `"logits_to_keep" not in model_kwargs`,
+ # so it is a DEFAULT: an explicit caller value survives, and popping
+ # unconditionally would rewrite logits_to_keep=0 (full sequence) into 1.
+ # Strip only what the strict validator raises on: num_logits_to_keep
+ # everywhere (renamed away in v5), and logits_to_keep on the VLMs whose
+ # top-level forward does not take it.
+ for _logits_kwarg in ("logits_to_keep", "num_logits_to_keep"):
+ if _logits_kwarg in kwargs and not _unsloth_generate_accepts_kwarg(self, _logits_kwarg):
+ kwargs.pop(_logits_kwarg, None)
model_eos_token_id = getattr(self.config, "eos_token_id", None)
if model_eos_token_id is not None and hasattr(model_eos_token_id, "__iter__"):