Skip to content

Local UI to run and train LLMs and diffusion models. Supports GGUF, MLX, Qwen3.8, DeepSeek-V4.1, MiniMax-H3, Gemma 4, FLUX and more.

Keep the notebook and saved model when unsloth-run runs a URL (#12907)

Nilay37bee346bc5c
diff --git a/docker/Dockerfile b/docker/Dockerfile
index fd69f3c18d3..1ac70d44693 100644
--- a/docker/Dockerfile
+++ b/docker/Dockerfile
@@ -578,15 +578,16 @@ RUN mkdir -p ${HF_HOME} ${TRITON_CACHE_DIR} \
# 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/
+COPY unsloth_nb_compat.py unsloth_pip_shim.py unsloth_root_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 \
+ && chmod +x /opt/unsloth-nb/unsloth_pip_shim.py /opt/unsloth-nb/unsloth_root_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 \
+ && for t in apt apt-get dpkg sudo; do ln -sf /opt/unsloth-nb/unsloth_root_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 \
diff --git a/docker/Dockerfile.studio-rocm b/docker/Dockerfile.studio-rocm
index 841ed041d06..988807d8c02 100644
--- a/docker/Dockerfile.studio-rocm
+++ b/docker/Dockerfile.studio-rocm
@@ -241,15 +241,16 @@ RUN SP="$(/opt/unsloth-venv/bin/python -c 'import sysconfig; print(sysconfig.get
# No transformers sidecars are baked: the CUDA image derives its set from the vLLM
# it carries, and this image carries none, so a recorded transformers pin resolves
# to the base venv's transformers.
-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/
+COPY unsloth_nb_compat.py unsloth_pip_shim.py unsloth_root_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/bin/python -c 'import sysconfig; print(sysconfig.get_path("purelib"))')" \
&& 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 \
+ && chmod +x /opt/unsloth-nb/unsloth_pip_shim.py /opt/unsloth-nb/unsloth_root_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 \
+ && for t in apt apt-get dpkg sudo; do ln -sf /opt/unsloth-nb/unsloth_root_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 \
diff --git a/docker/run.sh b/docker/run.sh
index bb8c382d662..d999fd19f3e 100755
--- a/docker/run.sh
+++ b/docker/run.sh
@@ -13,6 +13,7 @@
# 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
+# bash docker/run.sh unsloth-run <notebook URL> # notebook and saves stay in $PWD
# UNSLOTH_PORTS="-p 8000:8000 -p 8888:8888" bash docker/run.sh # publish the ports
#
# JupyterLab on the lean core image (unsloth/unsloth:core):
@@ -397,8 +398,22 @@ 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).
+# URL runs use mounted $PWD so unsloth-run saves survive --rm; local paths still use /workspace
+WORKDIR_FLAG=()
+RUN_USER_ENV=()
+if [[ $# -gt 0 && "$1" == "unsloth-run" ]]; then
+ for _arg in "${@:2}"; do
+ case "$_arg" in
+ http://* | https://*)
+ WORKDIR_FLAG=(-w /workspace/host)
+ RUN_USER_ENV=(-e "UNSLOTH_RUN_UID=$(id -u)" -e "UNSLOTH_RUN_GID=$(id -g)")
+ break
+ ;;
+ esac
+ done
+fi
+
+# no set -x: it leaks HF_TOKEN/WANDB_API_KEY; this array form is nounset-safe on macOS Bash 3.2
exec docker run --rm ${TTY_FLAG[@]+"${TTY_FLAG[@]}"} \
${GPU_FLAG[@]+"${GPU_FLAG[@]}"} \
--ipc=host \
@@ -408,6 +423,8 @@ exec docker run --rm ${TTY_FLAG[@]+"${TTY_FLAG[@]}"} \
-v "$HF_CACHE":/workspace/.cache/huggingface \
-v "$TRITON_CACHE":/workspace/.cache/triton \
-v "$WORK_DIR":/workspace/host \
+ ${WORKDIR_FLAG[@]+"${WORKDIR_FLAG[@]}"} \
+ ${RUN_USER_ENV[@]+"${RUN_USER_ENV[@]}"} \
${STUDIO_MOUNT[@]+"${STUDIO_MOUNT[@]}"} \
${MODEL_MOUNTS[@]+"${MODEL_MOUNTS[@]}"} \
"${ENV_FORWARD[@]}" \
diff --git a/docker/unsloth_pip_shim.py b/docker/unsloth_pip_shim.py
index 8adcadaf0ba..a8f6b1067b6 100644
--- a/docker/unsloth_pip_shim.py
+++ b/docker/unsloth_pip_shim.py
@@ -168,6 +168,16 @@ _TARGET_VALUE_FLAGS = {"--group", "--upgrade-group", "--requirements-from-script
_ARCHIVE_EXTS = (".tar.gz", ".tgz", ".tar.bz2", ".tbz2", ".tar.xz", ".txz", ".tar", ".zip")
+def _restore_install_privileges():
+ if os.environ.get("UNSLOTH_NB_ROOT_INSTALL") != "1":
+ return
+ try:
+ os.setgid(0)
+ os.setuid(0)
+ except OSError as exc:
+ raise SystemExit(f"unsloth notebook install could not restore root: {exc}") from exc
+
+
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
@@ -1096,6 +1106,8 @@ def main():
if argv[:1] == ["--unsloth-selfcheck-value-flags"]:
_selfcheck_value_flags()
+ _restore_install_privileges()
+
if os.environ.get("UNSLOTH_NB_SHIM") != "1":
os.execv(REAL[tool], [REAL[tool]] + argv)
return
diff --git a/docker/unsloth_root_shim.py b/docker/unsloth_root_shim.py
new file mode 100644
index 00000000000..a897ff9a72c
--- /dev/null
+++ b/docker/unsloth_root_shim.py
@@ -0,0 +1,76 @@
+#!/opt/unsloth-venv/bin/python
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-Present the Unsloth team. See /studio/LICENSE.AGPL-3.0
+
+"""restore root only for system-install commands in host-owned notebook kernels."""
+
+import os, sys
+
+
+_TOOLS = {
+ "apt": "/usr/bin/apt",
+ "apt-get": "/usr/bin/apt-get",
+ "dpkg": "/usr/bin/dpkg",
+ "sudo": "/usr/bin/sudo",
+}
+_SUDO_FLAGS = {
+ "-b",
+ "--background",
+ "-E",
+ "--preserve-env",
+ "-H",
+ "--set-home",
+ "-K",
+ "--remove-timestamp",
+ "-k",
+ "--reset-timestamp",
+ "-n",
+ "--non-interactive",
+ "-S",
+ "--stdin",
+}
+
+
+def _become_root():
+ try:
+ os.setgid(0)
+ os.setuid(0)
+ except OSError as exc:
+ raise SystemExit(f"unsloth notebook install could not restore root: {exc}") from exc
+
+
+def _sudo_command(argv):
+ command = []
+ for arg in argv:
+ if command:
+ command.append(arg)
+ elif arg == "--":
+ continue
+ elif arg in _SUDO_FLAGS or arg.startswith("--preserve-env="):
+ continue
+ elif arg.startswith("-"):
+ raise SystemExit(f"unsloth notebook sudo does not support option: {arg}")
+ else:
+ command.append(arg)
+ if not command:
+ raise SystemExit("unsloth notebook sudo requires a command")
+ return command
+
+
+def main():
+ tool = os.path.basename(sys.argv[0])
+ privileged_run = os.geteuid() == 0 or os.environ.get("UNSLOTH_NB_ROOT_INSTALL") == "1"
+ if privileged_run:
+ _become_root()
+ if tool == "sudo" and privileged_run:
+ command = _sudo_command(sys.argv[1:])
+ os.execvpe(command[0], command, os.environ)
+ return
+ real = _TOOLS.get(tool)
+ if real is None:
+ raise SystemExit(f"unknown unsloth notebook root tool: {tool}")
+ os.execv(real, [real, *sys.argv[1:]])
+
+
+if __name__ == "__main__":
+ main()
diff --git a/docker/unsloth_run.py b/docker/unsloth_run.py
index d94d9d8a2dd..9c25c0be65d 100644
--- a/docker/unsloth_run.py
+++ b/docker/unsloth_run.py
@@ -2,19 +2,9 @@
# 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.
+"""execute notebooks headlessly with one transformers version active per kernel."""
-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
+import argparse, json, os, re, shutil, stat, subprocess, sys, tempfile, urllib.parse, urllib.request
sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
try:
@@ -25,10 +15,7 @@ except Exception:
_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.
+# share the site-packages scanner so this path and the IPython hook select the same sidecar.
if compat is not None:
_PIN_RE = compat._PIN_RE
_INSTALL_RE = compat._INSTALL_RE
@@ -87,7 +74,7 @@ def _scan(nb):
return pin, model
-def _makedirs_as_host(path):
+def _makedirs_as_host(path, owner_ids = None):
"""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."""
@@ -103,18 +90,24 @@ def _makedirs_as_host(path):
os.makedirs(path, exist_ok = True)
if not missing:
return
- try:
- anchor = os.stat(probe)
- except OSError:
- return
+ if owner_ids is None:
+ try:
+ anchor = os.stat(probe)
+ except OSError:
+ return
+ owner_ids = anchor.st_uid, anchor.st_gid
for created in reversed(missing):
try:
- os.chown(created, anchor.st_uid, anchor.st_gid)
+ os.chown(created, *owner_ids)
except (OSError, AttributeError):
pass
-def _stage_metadata(staged, dest):
+def _stage_metadata(
+ staged,
+ dest,
+ owner_ids = None,
+):
"""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."""
@@ -128,11 +121,17 @@ def _stage_metadata(staged, dest):
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
+ if owner_ids is None:
+ try:
+ _dir = os.stat(os.path.dirname(os.path.abspath(dest)) or ".")
+ owner_ids = _dir.st_uid, _dir.st_gid
+ except OSError:
+ pass
+ if owner_ids is not None:
+ try:
+ os.chown(staged, *owner_ids)
+ except (OSError, AttributeError):
+ pass
return
try:
os.chmod(staged, stat.S_IMODE(st.st_mode))
@@ -144,6 +143,81 @@ def _stage_metadata(staged, dest):
pass
+def _open_url_download(url, owner_ids = None):
+ name = os.path.basename(urllib.parse.unquote(urllib.parse.urlsplit(url).path)) or "notebook"
+ stem = name[: -len(".ipynb")] if name.endswith(".ipynb") else name
+ n = 0
+ while True:
+ path = os.path.abspath(f"{stem}-{n}.ipynb" if n else f"{stem}.ipynb")
+ try:
+ fd = os.open(path, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o666)
+ except FileExistsError:
+ n += 1
+ continue
+ if owner_ids is None:
+ try:
+ parent = os.stat(os.path.dirname(path))
+ owner_ids = parent.st_uid, parent.st_gid
+ except OSError:
+ pass
+ if owner_ids is not None:
+ try:
+ os.fchown(fd, *owner_ids)
+ except (OSError, AttributeError):
+ pass
+ return path, fd
+
+
+def _host_run_ids():
+ uid = os.environ.pop("UNSLOTH_RUN_UID", None)
+ gid = os.environ.pop("UNSLOTH_RUN_GID", None)
+ if uid is None and gid is None:
+ return None
+ if uid is None or gid is None or not uid.isdigit() or not gid.isdigit():
+ raise SystemExit("UNSLOTH_RUN_UID and UNSLOTH_RUN_GID must be non-negative integers")
+ return int(uid), int(gid)
+
+
+def _mapped_container_id(host_id, map_path):
+ try:
+ with open(map_path) as mapping:
+ ranges = [tuple(map(int, line.split())) for line in mapping if line.strip()]
+ except (OSError, ValueError) as exc:
+ raise SystemExit(f"unsloth-run could not read the container ID map: {exc}") from exc
+ for container_start, host_start, length in ranges:
+ if host_start <= host_id < host_start + length:
+ return container_start + host_id - host_start
+ raise SystemExit(f"host ID {host_id} is not mapped into this container")
+
+
+def _container_run_ids(
+ host_ids,
+ uid_map = "/proc/self/uid_map",
+ gid_map = "/proc/self/gid_map",
+):
+ if host_ids is None:
+ return None
+ uid, gid = host_ids
+ return _mapped_container_id(uid, uid_map), _mapped_container_id(gid, gid_map)
+
+
+def _host_owned_command(cmd, run_ids):
+ """run notebook code as the bind mount owner while retaining install permissions."""
+ if run_ids is None or run_ids == (0, 0):
+ return cmd
+ uid, gid = run_ids
+ capabilities = "-all,+chown,+dac_override,+fowner,+setgid,+setuid"
+ return [
+ "/usr/bin/setpriv",
+ f"--reuid={uid}",
+ f"--regid={gid}",
+ "--keep-groups",
+ f"--inh-caps={capabilities}",
+ f"--ambient-caps={capabilities}",
+ *cmd,
+ ]
+
+
def main():
ap = argparse.ArgumentParser(prog = "unsloth-run")
ap.add_argument("notebook")
@@ -163,27 +237,22 @@ def main():
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
+ run_ids = _container_run_ids(_host_run_ids())
- 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)
+ _makedirs_as_host(out_dir, run_ids)
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.
+ # keep URL inputs beside --out so relative artifacts land in the output directory
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.
+ # nbconvert uses the input directory as the kernel cwd, so keep local inputs in place
src_path = args.notebook
fd, publish_from = tempfile.mkstemp(
prefix = ".unsloth-run-out-", suffix = ".ipynb", dir = out_dir
@@ -191,9 +260,8 @@ def main():
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:
+ src_path, fd = _open_url_download(args.notebook, run_ids)
+ with os.fdopen(fd, "w") as f:
json.dump(nb, f)
out_path = src_path
else:
@@ -202,12 +270,9 @@ def main():
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.
+ if run_ids is not None and run_ids != (0, 0):
+ env["UNSLOTH_NB_ROOT_INSTALL"] = "1"
+ # nested runs need a fresh marker to avoid overwriting or reusing the caller's transformers pin
fd, marker = tempfile.mkstemp(prefix = ".unsloth-run-tfmarker-")
os.close(fd)
env["UNSLOTH_NB_TF_MARKER"] = marker
@@ -242,19 +307,18 @@ def main():
os.path.basename(args.notebook.split("?")[0]) if args.out else os.path.basename(src_path),
)
try:
- rc = subprocess.call(cmd, env = env)
+ rc = subprocess.call(_host_owned_command(cmd, run_ids), env = env)
if rc == 0 and publish_from is not None:
- _stage_metadata(publish_from, out_path)
+ _stage_metadata(publish_from, out_path, run_ids)
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
+ # bind-mounted output files return EBUSY from rename(2) and require writing the mounted inode
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
+ # preserve the result because the run may have taken hours
if publish_from in tmp_files:
tmp_files.remove(publish_from)
print(
@@ -264,8 +328,6 @@ def main():
)
raise
finally:
- if tmp_dir is not None:
- shutil.rmtree(tmp_dir, ignore_errors = True)
for p in tmp_files:
try:
os.remove(p)
diff --git a/tests/python/test_docker_run_url_keeps_outputs.py b/tests/python/test_docker_run_url_keeps_outputs.py
new file mode 100644
index 00000000000..59786ba6bb2
--- /dev/null
+++ b/tests/python/test_docker_run_url_keeps_outputs.py
@@ -0,0 +1,354 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-Present the Unsloth team. See /studio/LICENSE.AGPL-3.0
+
+from __future__ import annotations
+
+import importlib.util
+import json
+import os
+import shutil
+import stat
+import subprocess
+import sys
+from pathlib import Path
+
+import pytest
+
+REPO_ROOT = Path(__file__).resolve().parents[2]
+RUNNER_PATH = REPO_ROOT / "docker" / "unsloth_run.py"
+ROOT_SHIM_PATH = REPO_ROOT / "docker" / "unsloth_root_shim.py"
+RUN_SH = REPO_ROOT / "docker" / "run.sh"
+
+NOTEBOOK = {
+ "cells": [{"cell_type": "code", "source": ["print(1)\n"], "metadata": {}, "outputs": []}],
+ "metadata": {},
+ "nbformat": 4,
+ "nbformat_minor": 5,
+}
+EXECUTED = {**NOTEBOOK, "metadata": {"executed": True}}
+
+
+def runner(tmp_path, monkeypatch):
+ monkeypatch.setenv("UNSLOTH_NB_TF_MARKER", str(tmp_path / "marker"))
+ spec = importlib.util.spec_from_file_location("unsloth_run_url_under_test", RUNNER_PATH)
+ mod = importlib.util.module_from_spec(spec)
+ spec.loader.exec_module(mod)
+ monkeypatch.setattr(mod, "_load", lambda *_a, **_k: json.loads(json.dumps(NOTEBOOK)))
+ return mod
+
+
+def cwd(tmp_path, monkeypatch):
+ work = tmp_path / "work"
+ work.mkdir()
+ monkeypatch.chdir(work)
+ return work
+
+
+def _run(
+ runner,
+ monkeypatch,
+ argv,
+ rc = 0,
+):
+ seen = {}
+
+ def nbconvert(cmd, env = None):
+ seen["env"] = env
+ src = cmd[cmd.index("--output") - 1]
+ seen["input"] = src
+ kernel_cwd = os.path.dirname(os.path.abspath(src))
+ os.makedirs(os.path.join(kernel_cwd, "lora_model"), exist_ok = True)
+ Path(kernel_cwd, "lora_model", "adapter_model.safetensors").write_bytes(b"w")
+ if rc == 0:
+ name = cmd[cmd.index("--output") + 1]
+ if not name.endswith(".ipynb"):
+ name += ".ipynb"
+ out = Path(cmd[cmd.index("--output-dir") + 1], name)
+ out.write_text(json.dumps(EXECUTED), encoding = "utf-8")
+ seen["output"] = out
+ return rc
+
+ monkeypatch.setattr(runner.subprocess, "call", nbconvert)
+ monkeypatch.setattr(runner.sys, "argv", ["unsloth-run", *argv])
+ with pytest.raises(SystemExit) as exc:
+ runner.main()
+ assert exc.value.code == rc
+ return seen
+
+
+def test_a_url_run_keeps_the_executed_notebook_and_its_saves(runner, monkeypatch, cwd):
+ seen = _run(runner, monkeypatch, ["https://example.invalid/nb/Llama.ipynb"])
+
+ assert Path(seen["input"]).parent == cwd
+ assert (cwd / "lora_model" / "adapter_model.safetensors").is_file()
+ assert json.loads((cwd / "Llama.ipynb").read_text(encoding = "utf-8")) == EXECUTED
+
+
+def test_a_url_run_does_not_overwrite_a_notebook_already_in_cwd(runner, monkeypatch, cwd):
+ (cwd / "Llama.ipynb").write_text("mine", encoding = "utf-8")
+
+ _run(runner, monkeypatch, ["https://example.invalid/nb/Llama.ipynb"])
+
+ assert (cwd / "Llama.ipynb").read_text(encoding = "utf-8") == "mine"
+ assert json.loads((cwd / "Llama-1.ipynb").read_text(encoding = "utf-8")) == EXECUTED
+
+
+ "url, name",
+ [
+ (
+ "https://example.invalid/nb/Llama3.2_%281B%29-Chat.ipynb?raw=true#scrollTo=x",
+ "Llama3.2_(1B)-Chat.ipynb",
+ ),
+ ("https://example.invalid/get?nb=Llama.ipynb", "get.ipynb"),
+ ("https://example.invalid/", "notebook.ipynb"),
+ ],
+)
+def test_a_url_run_names_the_notebook_after_the_url_path(runner, monkeypatch, cwd, url, name):
+ seen = _run(runner, monkeypatch, [url])
+
+ assert seen["output"] == cwd / name
+ assert sorted(p.name for p in cwd.iterdir()) == sorted(["lora_model", name])
+
+
+def test_a_failed_url_run_keeps_what_it_saved(runner, monkeypatch, cwd):
+ _run(runner, monkeypatch, ["https://example.invalid/nb/Llama.ipynb"], rc = 1)
+
+ assert (cwd / "lora_model" / "adapter_model.safetensors").is_file()
+ assert json.loads((cwd / "Llama.ipynb").read_text(encoding = "utf-8")) == NOTEBOOK
+
+
+def test_a_url_download_takes_the_callers_mapped_owner(runner, monkeypatch, cwd):
+ owners = []
+ monkeypatch.setenv("UNSLOTH_RUN_UID", "1234")
+ monkeypatch.setenv("UNSLOTH_RUN_GID", "5678")
+ monkeypatch.setattr(runner, "_container_run_ids", lambda ids: ids)
+ monkeypatch.setattr(
+ runner.os, "fchown", lambda fd, uid, gid: owners.append((uid, gid)), raising = False
+ )
+ _run(runner, monkeypatch, ["https://example.invalid/nb/Llama.ipynb"])
+
+ assert owners == [(1234, 5678)]
+
+
+def test_a_url_out_path_uses_the_callers_owner_for_new_directories_and_output(
+ runner, monkeypatch, cwd
+):
+ owners = []
+ monkeypatch.setenv("UNSLOTH_RUN_UID", "1234")
+ monkeypatch.setenv("UNSLOTH_RUN_GID", "5678")
+ monkeypatch.setattr(runner, "_container_run_ids", lambda ids: ids)
+ monkeypatch.setattr(
+ runner.os,
+ "chown",
+ lambda path, uid, gid: owners.append((Path(path), uid, gid)),
+ )
+
+ _run(
+ runner,
+ monkeypatch,
+ ["https://example.invalid/nb/Llama.ipynb", "--out", "new/dir/result.ipynb"],
+ )
+
+ expected = {(cwd / "new", 1234, 5678), (cwd / "new" / "dir", 1234, 5678)}
+ assert expected.issubset(set(owners))
+ assert any(
+ path.name.startswith(".unsloth-run-out-") and (uid, gid) == (1234, 5678)
+ for path, uid, gid in owners
+ )
+
+
+def test_unsloth_run_reads_and_hides_the_requested_host_owner(runner, monkeypatch):
+ monkeypatch.setenv("UNSLOTH_RUN_UID", "1234")
+ monkeypatch.setenv("UNSLOTH_RUN_GID", "5678")
+
+ assert runner._host_run_ids() == (1234, 5678)
+
+ assert "UNSLOTH_RUN_UID" not in os.environ
+ assert "UNSLOTH_RUN_GID" not in os.environ
+
+
+def test_rootless_id_maps_translate_the_host_caller_to_container_root(runner, tmp_path):
+ uid_map = tmp_path / "uid_map"
+ gid_map = tmp_path / "gid_map"
+ uid_map.write_text("0 1000 1\n1 100000 65536\n", encoding = "utf-8")
+ gid_map.write_text("0 1000 1\n1 100000 65536\n", encoding = "utf-8")
+
+ assert runner._container_run_ids((1000, 1000), uid_map, gid_map) == (0, 0)
+ assert runner._container_run_ids((101234, 101234), uid_map, gid_map) == (1235, 1235)
+
+
+def test_an_unmapped_host_identity_is_rejected(runner, tmp_path):
+ uid_map = tmp_path / "uid_map"
+ gid_map = tmp_path / "gid_map"
+ uid_map.write_text("0 100000 65536\n", encoding = "utf-8")
+ gid_map.write_text("0 100000 65536\n", encoding = "utf-8")
+
+ with pytest.raises(SystemExit, match = "host ID 1000 is not mapped"):
+ runner._container_run_ids((1000, 1000), uid_map, gid_map)
+
+
+def test_url_run_uses_host_identity_with_a_privileged_install_path(runner, monkeypatch, cwd):
+ monkeypatch.setenv("UNSLOTH_RUN_UID", "1234")
+ monkeypatch.setenv("UNSLOTH_RUN_GID", "5678")
+ monkeypatch.setattr(runner, "_container_run_ids", lambda ids: ids)
+
+ seen = _run(runner, monkeypatch, ["https://example.invalid/nb/Llama.ipynb"])
+
+ assert seen["env"]["UNSLOTH_NB_ROOT_INSTALL"] == "1"
+ assert runner._host_owned_command(["jupyter"], (1234, 5678)) == [
+ "/usr/bin/setpriv",
+ "--reuid=1234",
+ "--regid=5678",
+ "--keep-groups",
+ "--inh-caps=-all,+chown,+dac_override,+fowner,+setgid,+setuid",
+ "--ambient-caps=-all,+chown,+dac_override,+fowner,+setgid,+setuid",
+ "jupyter",
+ ]
+
+
[email protected]("host_ids", [None, (0, 0)])
+def test_run_without_a_nonroot_mapped_identity_needs_no_privilege_wrapper(runner, host_ids):
+ cmd = ["jupyter"]
+ assert runner._host_owned_command(cmd, host_ids) is cmd
+
+
+def test_root_shim_restores_root_before_executing_system_tools(monkeypatch):
+ spec = importlib.util.spec_from_file_location("unsloth_root_shim_under_test", ROOT_SHIM_PATH)
+ shim = importlib.util.module_from_spec(spec)
+ spec.loader.exec_module(shim)
+ calls = []
+ monkeypatch.setenv("UNSLOTH_NB_ROOT_INSTALL", "1")
+ monkeypatch.setattr(shim.os, "setgid", lambda gid: calls.append(("gid", gid)))
+ monkeypatch.setattr(shim.os, "setuid", lambda uid: calls.append(("uid", uid)))
+ monkeypatch.setattr(
+ shim.os,
+ "execv",
+ lambda path, argv: calls.append(("exec", path, argv)),
+ )
+ monkeypatch.setattr(shim.sys, "argv", ["apt-get", "install", "-y", "git"])
+
+ shim.main()
+
+ assert calls == [
+ ("gid", 0),
+ ("uid", 0),
+ ("exec", "/usr/bin/apt-get", ["/usr/bin/apt-get", "install", "-y", "git"]),
+ ]
+
+
+def test_root_shim_emulates_common_sudo_flags(monkeypatch):
+ spec = importlib.util.spec_from_file_location(
+ "unsloth_root_shim_sudo_under_test", ROOT_SHIM_PATH
+ )
+ shim = importlib.util.module_from_spec(spec)
+ spec.loader.exec_module(shim)
+ calls = []
+ monkeypatch.setenv("UNSLOTH_NB_ROOT_INSTALL", "1")
+ monkeypatch.setattr(shim.os, "setgid", lambda gid: None)
+ monkeypatch.setattr(shim.os, "setuid", lambda uid: None)
+ monkeypatch.setattr(
+ shim.os,
+ "execvpe",
+ lambda file, argv, env: calls.append((file, argv, env)),
+ )
+ monkeypatch.setattr(shim.sys, "argv", ["sudo", "-E", "--", "apt-get", "update"])
+
+ shim.main()
+
+ assert calls == [("apt-get", ["apt-get", "update"], shim.os.environ)]
+
+
+def test_root_shim_does_not_elevate_an_unprivileged_container(monkeypatch):
+ spec = importlib.util.spec_from_file_location(
+ "unsloth_root_shim_unprivileged_under_test", ROOT_SHIM_PATH
+ )
+ shim = importlib.util.module_from_spec(spec)
+ spec.loader.exec_module(shim)
+ calls = []
+ monkeypatch.delenv("UNSLOTH_NB_ROOT_INSTALL", raising = False)
+ monkeypatch.setattr(shim.os, "geteuid", lambda: 1234)
+ monkeypatch.setattr(
+ shim.os,
+ "setuid",
+ lambda uid: pytest.fail(f"unexpected privilege restoration to UID {uid}"),
+ )
+ monkeypatch.setattr(
+ shim.os,
+ "setgid",
+ lambda gid: pytest.fail(f"unexpected privilege restoration to GID {gid}"),
+ )
+ monkeypatch.setattr(
+ shim.os,
+ "execv",
+ lambda path, argv: calls.append((path, argv)),
+ )
+ monkeypatch.setattr(shim.sys, "argv", ["dpkg", "--print-architecture"])
+
+ shim.main()
+
+ assert calls == [("/usr/bin/dpkg", ["/usr/bin/dpkg", "--print-architecture"])]
+
+
+def _run_sh_argv(tmp_path, *command):
+ bindir = tmp_path / "bin"
+ bindir.mkdir()
+ argv_log = tmp_path / "argv"
+ docker = bindir / "docker"
+ docker.write_text(
+ f'#!/usr/bin/env bash\nprintf "%s\\n" "$@" > "{argv_log}"\n', encoding = "utf-8"
+ )
+ docker.chmod(docker.stat().st_mode | stat.S_IEXEC)
+ env = {
+ "PATH": f"{bindir}:/usr/bin:/bin",
+ "HOME": str(tmp_path / "home"),
+ "UNSLOTH_WORKDIR": str(tmp_path),
+ "UNSLOTH_GPUS": "none",
+ }
+ proc = subprocess.run(
+ [shutil.which("bash"), str(RUN_SH), *command],
+ cwd = tmp_path,
+ env = env,
+ capture_output = True,
+ text = True,
+ timeout = 60,
+ )
+ assert proc.returncode == 0, proc.stderr
+ return argv_log.read_text(encoding = "utf-8").splitlines()
+
+
+ os.name != "posix" or shutil.which("bash") is None, reason = "POSIX shell required"
+)
+def test_run_sh_starts_unsloth_run_in_the_mounted_host_dir(tmp_path):
+ argv = _run_sh_argv(
+ tmp_path, "unsloth-run", "--timeout", "60", "https://example.invalid/nb/Llama.ipynb"
+ )
+ image = argv.index("unsloth/unsloth:latest")
+ assert ["-w", "/workspace/host"] in [argv[i : i + 2] for i in range(image)]
+ pairs = [argv[i : i + 2] for i in range(image)]
+ assert ["-e", f"UNSLOTH_RUN_UID={os.getuid()}"] in pairs
+ assert ["-e", f"UNSLOTH_RUN_GID={os.getgid()}"] in pairs
+ assert "--user" not in argv[:image]
+ assert f"{tmp_path}:/workspace/host" in argv[:image]
+
+
+ os.name != "posix" or shutil.which("bash") is None, reason = "POSIX shell required"
+)
+ "command",
+ [("jupyter", "lab"), ("unsloth-run", "unsloth-notebooks/nb/Llama.ipynb")],
+)
+def test_run_sh_leaves_other_commands_in_the_image_workdir(tmp_path, command):
+ argv = _run_sh_argv(tmp_path, *command)
+ flags = argv[: argv.index("unsloth/unsloth:latest")]
+ assert "-w" not in flags
+ assert not any(flag.startswith("UNSLOTH_RUN_UID=") for flag in flags)
+ assert not any(flag.startswith("UNSLOTH_RUN_GID=") for flag in flags)
+
+
+if __name__ == "__main__":
+ sys.exit(pytest.main([__file__, "-v"]))
diff --git a/tests/python/test_unsloth_pip_shim.py b/tests/python/test_unsloth_pip_shim.py
index f7118629f0b..12bff8a23c6 100644
--- a/tests/python/test_unsloth_pip_shim.py
+++ b/tests/python/test_unsloth_pip_shim.py
@@ -110,6 +110,19 @@ def _run(shim, tool, args):
return execd, marker
+def test_host_owned_notebook_pip_restores_root(shim, monkeypatch):
+ calls = []
+ monkeypatch.setenv("UNSLOTH_NB_ROOT_INSTALL", "1")
+ monkeypatch.setattr(shim.os, "setgid", lambda gid: calls.append(("gid", gid)))
+ monkeypatch.setattr(shim.os, "setuid", lambda uid: calls.append(("uid", uid)))
+ monkeypatch.setattr(shim.sys, "argv", ["pip", "--version"])
+
+ with pytest.raises(_Exec):
+ shim.main()
+
+ assert calls == [("gid", 0), ("uid", 0)]
+
+
UNSLOTH_VCS = "git+https://github.com/unslothai/unsloth.git#egg=unsloth"
KEPT = object()