Local UI to run and train LLMs and diffusion models. Supports GGUF, MLX, Qwen3.8, DeepSeek-V4.1, MiniMax-H3, Gemma 4, FLUX and more.
Python agentaichatgptdeepseekfine-tuninggemmaimage-generationllamallmllmsopenaipythonqwenreinforcement-learningself-hostedstable-diffusiontext-to-speechttsuiunsloth
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.ymlnew file mode 100644index 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.ymlindex 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 cacheif: always()uses: ./.github/actions/pip-cache-savediff --git a/.gitignore b/.gitignoreindex 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.jsonllama.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/.dockerignorenew file mode 100644index 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/Dockerfilenew file mode 100644index 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.studionew file mode 100644index 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/NOTICEnew file mode 100644index 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.shnew file mode 100755index 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.shnew file mode 100755index 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.pynew file mode 100644index 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.mdnew file mode 100644index 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.iconew file mode 100644index 00000000000..f922d8df9e3Binary files /dev/null and b/docker/jupyter/favicon.ico differdiff --git a/docker/jupyter/install_sloth_stickers.py b/docker/jupyter/install_sloth_stickers.pynew file mode 100644index 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.jsonnew file mode 100644index 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.htmlnew file mode 100644index 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>+ ·+ <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.pngnew file mode 100644index 00000000000..8fc411695d9Binary files /dev/null and b/docker/jupyter/logo.png differdiff --git a/docker/jupyter/overrides.json b/docker/jupyter/overrides.jsonnew file mode 100644index 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.pynew file mode 100644index 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/.gitignorenew file mode 100644index 00000000000..a51e4ca6ca1--- /dev/null+++ b/docker/jupyter/unsloth_labext/.gitignore@@ -0,0 +1,7 @@+node_modules/+lib/+*.tsbuildinfo+unsloth-jupyterlab/+.yarn/+.pnp.*+yarn.lockdiff --git a/docker/jupyter/unsloth_labext/.yarnrc.yml b/docker/jupyter/unsloth_labext/.yarnrc.ymlnew file mode 100644index 00000000000..3186f3f0795--- /dev/null+++ b/docker/jupyter/unsloth_labext/.yarnrc.yml@@ -0,0 +1 @@+nodeLinker: node-modulesdiff --git a/docker/jupyter/unsloth_labext/package.json b/docker/jupyter/unsloth_labext/package.jsonnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.cssnew file mode 100644index 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.cssnew file mode 100644index 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.jsonnew file mode 100644index 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.shnew file mode 100755index 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.pynew file mode 100644index 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.shnew file mode 100644index 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.confdiff --git a/docker/supervisord.conf b/docker/supervisord.confnew file mode 100644index 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=0diff --git a/docker/unsloth_colab_compat.py b/docker/unsloth_colab_compat.pynew file mode 100644index 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.pynew file mode 100644index 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.shnew file mode 100755index 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.shnew file mode 100755index 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.pynew file mode 100644index 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 = Truediff --git a/docker/unsloth_nb_content_sig.py b/docker/unsloth_nb_content_sig.pynew file mode 100644index 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.pynew file mode 100644index 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 = Truediff --git a/docker/unsloth_nb_strip_colab.py b/docker/unsloth_nb_strip_colab.pynew file mode 100644index 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.pynew file mode 100644index 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.pynew file mode 100644index 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.pynew file mode 100644index 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.shnew file mode 100755index 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.shnew file mode 100644index 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 0diff --git a/install.sh b/install.shindex 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 ]; thenif [ "$STUDIO_LOCAL_INSTALL" = true ]; thensubstep "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"fiif [ "$SKIP_TORCH" = false ] && [ "$_torch_index_is_rocm_family" = true ]; thenif _is_gfx906_bnb_skip; then@@ -5456,10 +5461,10 @@ elif [ -n "$TORCH_INDEX_URL" ]; thenif [ "$STUDIO_LOCAL_INSTALL" = true ]; thensubstep "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"fielif [ "$STUDIO_LOCAL_INSTALL" = true ]; thenrun_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 @@ elserun_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=autosubstep "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"elsecase "$PACKAGE_NAME" inunsloth)diff --git a/studio/install_llama_prebuilt.py b/studio/install_llama_prebuilt.pyindex 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_messagesis_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 asilent 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)):raiselog(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 = Nonefailed_dir: Path | None = None@@ -4491,7 +4573,7 @@ def activate_install_tree(staging_dir: Path, install_dir: Path, host: HostInfo)had_existing = Truerollback_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 = Truelog(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 = Nonelog(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.pyindex 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_repoif 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.pynew file mode 100644index 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.pynew file mode 100644index 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 branchdiff --git a/tests/python/test_docker_labext_cell_nav.py b/tests/python/test_docker_labext_cell_nav.pynew file mode 100644index 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.pynew file mode 100644index 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.pynew file mode 100644index 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_FAILUREdiff --git a/tests/python/test_docker_nb_compat_pre_run_cell.py b/tests/python/test_docker_nb_compat_pre_run_cell.pynew file mode 100644index 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.pynew file mode 100644index 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), linediff --git a/tests/python/test_docker_nb_ipython_profile_writable.py b/tests/python/test_docker_nb_ipython_profile_writable.pynew file mode 100644index 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.pynew file mode 100644index 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.pynew file mode 100644index 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.pynew file mode 100644index 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.pynew file mode 100644index 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.pynew file mode 100644index 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 Falsediff --git a/tests/python/test_docker_nb_sync_publish_ownership.py b/tests/python/test_docker_nb_sync_publish_ownership.pynew file mode 100644index 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.pynew file mode 100644index 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.pynew file mode 100644index 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.pynew file mode 100644index 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(), sourcediff --git a/tests/python/test_docker_pip_shim_training_stack.py b/tests/python/test_docker_pip_shim_training_stack.pynew file mode 100644index 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.pynew file mode 100644index 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.pynew file mode 100644index 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.pynew file mode 100644index 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().errdiff --git a/tests/python/test_docker_run_pin_scan.py b/tests/python/test_docker_run_pin_scan.pynew file mode 100644index 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.pynew file mode 100644index 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.environdiff --git a/tests/python/test_docker_studio_launch_view_config.py b/tests/python/test_docker_studio_launch_view_config.pynew file mode 100644index 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.pynew file mode 100644index 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.pynew file mode 100644index 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.pynew file mode 100644index 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) == linediff --git a/tests/python/test_unsloth_pip_shim.py b/tests/python/test_unsloth_pip_shim.pynew file mode 100644index 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.shnew file mode 100755index 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 1diff --git a/tests/studio/install/test_install_llama_prebuilt_logic.py b/tests/studio/install/test_install_llama_prebuilt_logic.pyindex 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.pynew file mode 100644index 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: " + markerdiff --git a/tests/test_fa2_fast_generate_bypass.py b/tests/test_fa2_fast_generate_bypass.pyindex 5ca30a2642b..713c214c197 100644--- a/tests/test_fa2_fast_generate_bypass.py+++ b/tests/test_fa2_fast_generate_bypass.py@@ -4,12 +4,22 @@ import astimport inspectimport osfrom contextlib import nullcontext+from importlib.metadata import version as installed_versionfrom pathlib import Pathfrom 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.pyindex 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.pynew file mode 100644index 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.pyindex 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/1266os.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_versionfrom 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.pyindex 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_processself.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):+ returnreturncode = 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.pyindex 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.pyindex 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_KEEPif 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__"):