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.

Studio: make studio/setup.sh read the recorded uv cache, and probe the cache the CLI hands it (#10647)

Daniel Hana3dbab3ce75f
diff --git a/studio/setup.sh b/studio/setup.sh
index 6b55102b3ce..ad9eb2d538a 100755
--- a/studio/setup.sh
+++ b/studio/setup.sh
@@ -955,8 +955,7 @@ STAGE_ROOT="${UNSLOTH_STUDIO_STAGE_ROOT:-}"
RUNTIME_ROOT="${STAGE_ROOT:-$STUDIO_HOME}"
VENV_DIR="$RUNTIME_ROOT/unsloth_studio"
-# Same uv cache install.sh chose, for the same reasons -- kept byte-identical to the
-# block there, including the write probe and the unwind on failure.
+# Same uv cache install.sh chose, for the same reasons.
#
# This script is also the standalone entry point: `unsloth studio update` runs it
# directly, without install.sh, so an export made only there covers the first install and
@@ -968,23 +967,311 @@ VENV_DIR="$RUNTIME_ROOT/unsloth_studio"
#
# STUDIO_HOME, not RUNTIME_ROOT: the cache has to be the one install.sh created, and the
# two agree whenever UNSLOTH_STUDIO_STAGE_ROOT is unset, which is every non-staged run.
-if [ -z "${UV_CACHE_DIR:-}" ]; then
- UV_CACHE_DIR="$STUDIO_HOME/cache/uv"
- export UV_CACHE_DIR
- # mktemp, not a $$-derived name: this branch exists for a cache directory another
- # account can write, and there a predictable path can be pre-created as a symlink,
- # which `: >` would follow and truncate -- as root, any file on the box. mktemp
- # creates O_EXCL with an unpredictable suffix, so it cannot follow one, and failing
- # to create IS the writability answer this probe wanted.
+# The LIVE marker, even under a stage root: the CLI promotes its parked choice on acceptance,
+# so an unactivated stage cannot move the live cache. setup.sh only infers; it never writes.
+_uv_no_cache_requested() {
+ # --no-cache outranks --cache-dir. Same spelling as install.sh's _uv_no_cache_requested.
+ case "$(printf '%s' "${UV_NO_CACHE:-}" | tr '[:upper:]' '[:lower:]')" in
+ 1|y|yes|t|true|on) return 0 ;;
+ esac
+ return 1
+}
+
+_uv_is_bucket_name() {
+ # install.sh's _uv_is_bucket_name, verbatim: the two have to call the same directories uv's.
+ case "$1" in
+ *-v[0-9]*) ;;
+ *) return 1 ;;
+ esac
+ case "${1##*-v}" in
+ ''|*[!0-9]*) return 1 ;;
+ esac
+ case "${1%-v*}" in
+ archive|binaries|builds|built-wheels|environments|flat-index) ;;
+ git|interpreter|osv|python|sdists|simple|wheels) ;;
+ *) return 1 ;;
+ esac
+ return 0
+}
+
+_uv_cache_probe_writable() {
+ # As install.sh's _uv_cache_root_is_writable: a real create, and mktemp (O_EXCL) not $$,
+ # since a predictable name can be pre-created as a symlink.
_uv_cache_probe=""
- if ! mkdir -p "$UV_CACHE_DIR" 2>/dev/null \
- || ! _uv_cache_probe=$(mktemp "$UV_CACHE_DIR/.unsloth-write-probe.XXXXXX" 2>/dev/null); then
- echo "[WARN] Cannot write to $UV_CACHE_DIR -- using uv's default cache." >&2
- unset UV_CACHE_DIR
+ if ! mkdir -p "$1" 2>/dev/null \
+ || ! _uv_cache_probe=$(mktemp "$1/.unsloth-write-probe.XXXXXX" 2>/dev/null); then
+ [ -z "$_uv_cache_probe" ] || rm -f "$_uv_cache_probe" 2>/dev/null || true
+ unset _uv_cache_probe
+ return 1
+ fi
+ # Creating is not enough: an ACL granting create but denying unlink leaves uv's renames to
+ # fail later. GONE is the answer, not rm's exit status, since a scanner holding the handle
+ # makes one delete fail and the next succeed. Retry, then believe the filesystem. Same
+ # bounded loop as install.sh's _uv_cache_root_is_writable.
+ _uv_cache_tries=0
+ while :; do
+ rm -f "$_uv_cache_probe" 2>/dev/null || true
+ [ -e "$_uv_cache_probe" ] || break
+ _uv_cache_tries=$((_uv_cache_tries + 1))
+ if [ "$_uv_cache_tries" -ge 3 ]; then
+ unset _uv_cache_probe _uv_cache_tries
+ return 1
+ fi
+ sleep 1
+ done
+ unset _uv_cache_probe _uv_cache_tries
+ return 0
+}
+
+_uv_cache_folds_case() { # <dir>
+ # Measured on the cache filesystem, not assumed from the platform, as install.sh does it:
+ # default APFS folds and ext4 does not, and a Mac can have either mounted. A cache we
+ # cannot write answers "no", which is the conservative reading.
+ _uvf_probe="$1/.unsloth-case-probe.$$-A"
+ mkdir "$_uvf_probe" 2>/dev/null || { unset _uvf_probe; return 1; }
+ if [ -d "$1/.unsloth-case-probe.$$-a" ]; then
+ rmdir "$_uvf_probe" 2>/dev/null || true
+ unset _uvf_probe
+ return 0
+ fi
+ rmdir "$_uvf_probe" 2>/dev/null || true
+ unset _uvf_probe
+ return 1
+}
+
+_uv_store_key() { # <entry name> <folds:1|0> -> the name uv opens it as, or nonzero
+ # Only the NAME folds; what the entry IS is the caller's business. Both scans go through
+ # here so they cannot disagree about which entries are uv's.
+ if _uv_is_bucket_name "$1"; then
+ printf '%s' "$1"
+ return 0
+ fi
+ [ "$2" = 1 ] || return 1
+ case "$1" in *[[:upper:]]*) ;; *) return 1 ;; esac
+ _uvk_lower=$(printf '%s' "$1" | tr '[:upper:]' '[:lower:]')
+ if _uv_is_bucket_name "$_uvk_lower"; then
+ printf '%s' "$_uvk_lower"
+ unset _uvk_lower
+ return 0
+ fi
+ unset _uvk_lower
+ return 1
+}
+
+_uv_cache_usable() {
+ # The stores uv owns: a 0555 archive-* or interpreter-v4 aborts uv. Not every subdirectory,
+ # or an unrelated read-only one disqualifies a usable cache. install.sh's
+ # _uv_cache_is_writable is the same check.
+ _uv_cache_probe_writable "$1" || return 1
+ _uv_cache_folds_case "$1" && _uvu_fold=1 || _uvu_fold=0
+ for _uvu_bucket in "$1"/*; do
+ _uvu_name=$(_uv_store_key "${_uvu_bucket##*/}" "$_uvu_fold") || continue
+ # Only the stores `uv pip install` CREATES, which is the one uv command this file runs
+ # (line 2053). The rule is what uv is measured to write, not what a 0555 directory
+ # happens to survive: a `git+` requirement creates git-v0 and builds-v0, so those stay,
+ # while flat-index-v2 is not created even by `--find-links --no-index`, and binaries,
+ # environments, osv and python belong to uv self-update, uv venv and uv python.
+ #
+ # A store is probed even where one trivial install tolerates it read-only, because that
+ # tolerance is the WORKLOAD, not the cache. On the pinned uv 0.12.1 a 0555 sdists-v9
+ # passes a wheel-only install and aborts the moment a source build needs it, and a 0555
+ # interpreter-v4 passes while its entry is cached and aborts on a new interpreter. An
+ # update installs a large, varying set, so a store it cannot write is a cache that
+ # breaks later rather than one that is fine. Re-measure on a pin bump.
+ case "${_uvu_name%-v*}" in
+ archive|builds|built-wheels|git|interpreter|sdists|simple|wheels) ;;
+ *) continue ;;
+ esac
+ if [ ! -d "$_uvu_bucket" ]; then
+ # A file, or a symlink dangling or not, is an existing path to mkdir(2), so uv
+ # cannot make the store and aborts. Measured on uv 0.10.7: a plain file at any of
+ # archive-v0, interpreter-v4, sdists-v9, simple-v20 or wheels-v6 exits 1 or 2.
+ if [ -e "$_uvu_bucket" ] || [ -L "$_uvu_bucket" ]; then
+ unset _uvu_bucket
+ return 1
+ fi
+ continue
+ fi
+ if ! _uv_cache_probe_writable "$_uvu_bucket"; then
+ unset _uvu_bucket _uvu_name _uvu_fold _uvu_ctl
+ return 1
+ fi
+ # Inside the store, and only inside one uv owns: a `*-v[0-9]*` glob also reaches
+ # `unused-v999/.git`, and a read-only file there condemned a cache real uv uses fine.
+ # sdists-* only: that is the one store measured to abort on a read-only .git, and
+ # rejecting a cache uv accepts costs the warm cache this path exists to find.
+ # One level inside the index stores, and only those. uv REWRITES this metadata on every
+ # resolve, so a shard another account owns aborts it. Measured on BOTH the pinned uv
+ # 0.12.1 and 0.10.7: a 0555 `simple-*/pypi` or `wheels-*/pypi` gives "Failed to write to
+ # the client cache", exit 2. One level is the leaf on both: 0.12.1 lays this out as
+ # `simple-v24/pypi`, not `simple-v24/index/<hash>`, and a 0555 `wheels-v6/pypi/requests`
+ # one level deeper installs fine. Bounded on purpose: the index level holds one entry per
+ # index, while the level below it grows with every package.
+ case "$_uvu_name" in
+ simple-* | wheels-*)
+ for _uvu_shard in "$_uvu_bucket"/* "$_uvu_bucket"/index/*; do
+ # `index/<hash>`, one per CUSTOM index, is where uv puts metadata when
+ # --index-url is set, which Studio does for the torch wheels. Measured on
+ # the pinned uv 0.12.1: a 0555 `simple-v24/index/<hash>` is adopted by a
+ # one-level probe and then aborts `uv pip install --refresh` with "Failed
+ # to write to the client cache". The literal `index` level is still bounded:
+ # one entry per index, where the level below THAT is one per package.
+ [ "${_uvu_shard#"$_uvu_bucket"/index/}" != "*" ] || continue
+ if [ ! -d "$_uvu_shard" ]; then
+ # Same rule as the store level: a file, or a symlink dangling or not, is
+ # an existing path uv can neither open nor mkdir. Measured on the pinned
+ # uv 0.12.1, a plain file OR a dangling symlink at simple-v24/pypi or
+ # wheels-v6/pypi aborts with "Failed to write to the client cache",
+ # exit 2. A `*/` glob skips both, which called the cache usable.
+ { [ -e "$_uvu_shard" ] || [ -L "$_uvu_shard" ]; } || continue
+ unset _uvu_bucket _uvu_name _uvu_fold _uvu_ctl _uvu_shard
+ return 1
+ fi
+ if ! _uv_cache_probe_writable "$_uvu_shard"; then
+ unset _uvu_bucket _uvu_name _uvu_fold _uvu_ctl _uvu_shard
+ return 1
+ fi
+ done
+ unset _uvu_shard
+ ;;
+ esac
+ case "$_uvu_name" in sdists-*) _uvu_ctl=.git ;; *) _uvu_ctl="" ;; esac
+ if [ -n "$_uvu_ctl" ] && ! _uv_control_files_writable "$_uvu_bucket" "$_uvu_ctl"; then
+ unset _uvu_bucket _uvu_name _uvu_fold _uvu_ctl
+ return 1
+ fi
+ done
+ unset _uvu_bucket _uvu_name _uvu_fold _uvu_ctl _uvu_shard
+ _uv_control_files_writable "$1" .lock || return 1
+ return 0
+}
+
+_uv_control_files_writable() { # <dir> <name>...
+ # Only the names uv is measured to need writable, because rejecting more throws away the
+ # warm cache this whole path exists to find. Every control file at 0444 against uv 0.10.7:
+ # root .lock ABORTS (exit 2) and sdists-v9/.git ABORTS (exit 2); root CACHEDIR.TAG and
+ # .gitignore, and .git/.gitignore/.lock under archive-v0, interpreter-v4, simple-v20 and
+ # wheels-v6, all install fine. uv itself creates only the three root files, so a per-store
+ # .git is someone else's, and one of them is proven to break uv. Re-measure on a pin bump.
+ _uvc_dir=$1
+ shift
+ for _uvc_name in "$@"; do
+ _uvc_path="$_uvc_dir/$_uvc_name"
+ { [ -e "$_uvc_path" ] || [ -L "$_uvc_path" ]; } || continue
+ # Not a regular file, so uv cannot open it at all: measured on uv 0.10.7, a `.lock`
+ # DIRECTORY (or a symlink to one) exits 2 with "Could not acquire lock ... Is a
+ # directory". `-f` alone skipped it and called the cache usable.
+ if [ ! -f "$_uvc_path" ] || [ ! -r "$_uvc_path" ] || [ ! -w "$_uvc_path" ]; then
+ unset _uvc_dir _uvc_name _uvc_path
+ return 1
+ fi
+ done
+ unset _uvc_dir _uvc_name _uvc_path
+ return 0
+}
+
+_uv_cache_warm() {
+ # Package BYTES, not metadata (wheels-* is .msgpack/.http after a bare resolve). Mirrors
+ # install.sh's scan and unsloth_cli's _uv_cache_has_packages.
+ [ -n "${1:-}" ] && [ -d "$1" ] && [ -r "$1" ] || return 1
+ # One pass over the entries, not five lowercase globs: on a folding filesystem `Archive-V0`
+ # IS the store uv opens as `archive-v0`, and a glob does not fold, so a cache holding every
+ # wheel read as cold and the offline update failed. _uv_cache_usable normalises the same way.
+ _uv_cache_folds_case "$1" && _uvw_fold=1 || _uvw_fold=0
+ for _uvw_bucket in "$1"/*; do
+ [ -d "$_uvw_bucket" ] || continue
+ # Stricter than the probe, deliberately, and exactly as install.sh's scan: `archive-*`
+ # also matches `archive-v0.backup`, whose bytes uv cannot reuse. Counting those reads a
+ # cache as warm that then fails an offline update (measured: uv exit 1, not in cache).
+ _uvw_base=$(_uv_store_key "${_uvw_bucket##*/}" "$_uvw_fold") || continue
+ case "${_uvw_base%-v*}" in
+ archive|builds|built-wheels|wheels|sdists) ;;
+ *) continue ;;
+ esac
+ # Unreadable is not empty, but it is also not proof of warmth.
+ [ -r "$_uvw_bucket" ] && [ -x "$_uvw_bucket" ] || continue
+ # -L: a bucket can be a symlink, as Get-ChildItem -Recurse follows. -print -quit, never
+ # `| head -n 1`: under this file's pipefail head's early exit SIGPIPEs find on a bucket
+ # over 64K of names, and the warm cache then reads as cold.
+ _uvw_hit=$(find -L "$_uvw_bucket" -type f \
+ ! -name CACHEDIR.TAG ! -name .git ! -name .gitignore \
+ ! -name '*.lock' ! -name '*.msgpack' ! -name '*.http' ! -name '*.rev' \
+ -print -quit 2>/dev/null) || true
+ # `|| true`: find exits nonzero after an unreadable leaf even once it printed the hit,
+ # and the hit is already assigned.
+ if [ -n "$_uvw_hit" ]; then
+ unset _uvw_bucket _uvw_hit _uvw_base _uvw_fold
+ return 0
+ fi
+ done
+ unset _uvw_bucket _uvw_hit _uvw_base _uvw_fold
+ return 1
+}
+
+_recorded_uv_cache() {
+ # The marker as unsloth_cli writes it: one absolute path, one trailing newline. Tolerates a
+ # BOM (PowerShell 5.1) and a CR, otherwise byte-for-byte. The sentinel keeps the bytes, and
+ # exactly one delimiter is removed, so a pathname ending in a newline round-trips.
+ _ruc_raw=$(cat "$STUDIO_HOME/cache/uv-cache-dir" 2>/dev/null && printf x) || return 1
+ _ruc_raw=${_ruc_raw%x}
+ _ruc_raw=${_ruc_raw%"$_UV_MARKER_LF"}
+ _ruc_raw=${_ruc_raw#"$_UV_MARKER_BOM"}
+ _ruc_raw=${_ruc_raw%"$_UV_MARKER_CR"}
+ case "$_ruc_raw" in
+ # Absolute only, as install.sh records (_absolutize_uv_cache_dir): setup.sh has already
+ # changed directory. No [:print:] filter: in the C locale it rejects every non-ASCII home.
+ "") unset _ruc_raw; return 1 ;;
+ /*) ;;
+ *) unset _ruc_raw; return 1 ;;
+ esac
+ printf '%s' "$_ruc_raw"
+ unset _ruc_raw
+ return 0
+}
+_UV_MARKER_BOM=$(printf '\357\273\277')
+_UV_MARKER_CR=$(printf '\r')
+_UV_MARKER_LF=$(printf '\n.')
+_UV_MARKER_LF=${_UV_MARKER_LF%.}
+
+# Three tiers: a caller value, --no-cache, then the recorded marker or the Studio cache. No
+# "uv's default if warm" tier, unlike install.sh, which decides before anything is recorded:
+# here it would move an update off the installer's cache with nothing recording the change.
+_uv_caller_value=false
+# `*[![:space:]]*`, not `-n`: install.sh's test, so an all-whitespace value is not a caller's
+# choice here and `--cache-dir ' '` there. The two selectors have to answer alike.
+case "${UV_CACHE_DIR-}" in
+ *[![:space:]]*) _uv_caller_value=true ;;
+esac
+if [ "$_uv_caller_value" = true ]; then
+ # A caller value wins outright, here as in install.sh and in the CLI.
+ :
+elif _uv_no_cache_requested; then
+ # Unset, not left alone: uv parses an exported EMPTY value as `--cache-dir ''` and fails.
+ unset UV_CACHE_DIR
+else
+ # Same sentinel as the reader: substitution would strip the newline it preserved.
+ _uv_recorded=$(_recorded_uv_cache && printf x) || _uv_recorded=""
+ _uv_recorded=${_uv_recorded%x}
+ if [ -n "$_uv_recorded" ] && _uv_cache_warm "$_uv_recorded" \
+ && _uv_cache_usable "$_uv_recorded"; then
+ # Only while it holds packages and uv can write to it: an emptied cache would refetch
+ # everything, and uv aborts on a read-only one (a share remounted since the install).
+ UV_CACHE_DIR="$_uv_recorded"
+ export UV_CACHE_DIR
+ else
+ UV_CACHE_DIR="$STUDIO_HOME/cache/uv"
+ export UV_CACHE_DIR
+ # The whole cache, not just its root, and the same check the recorded branch gets: a
+ # Studio cache whose archive-v0 went read-only passes a root probe and then aborts uv
+ # (measured: exit 1, "Permission denied"). Leaving it unset lets uv use its own.
+ if ! _uv_cache_usable "$UV_CACHE_DIR"; then
+ echo "[WARN] Cannot write to $UV_CACHE_DIR -- using uv's default cache." >&2
+ unset UV_CACHE_DIR
+ fi
fi
- [ -z "$_uv_cache_probe" ] || rm -f "$_uv_cache_probe" 2>/dev/null || true
- unset _uv_cache_probe
+ unset _uv_recorded
fi
+unset _uv_caller_value
VENV_T5_530_DIR="$RUNTIME_ROOT/.venv_t5_530"
VENV_T5_550_DIR="$RUNTIME_ROOT/.venv_t5_550"
VENV_T5_510_DIR="$RUNTIME_ROOT/.venv_t5_510"
diff --git a/tests/python/test_uv_cache_selector_agreement.py b/tests/python/test_uv_cache_selector_agreement.py
new file mode 100644
index 00000000000..d0290aaa180
--- /dev/null
+++ b/tests/python/test_uv_cache_selector_agreement.py
@@ -0,0 +1,245 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""studio/setup.sh and unsloth_cli must answer the same question the same way.
+
+The contract this branch adds is that `unsloth studio update` reuses the cache the install
+recorded, and it is implemented twice: once in POSIX shell for a standalone `bash
+studio/setup.sh`, once in Python for the CLI and the desktop updater. Whenever the two
+disagree about one cache directory, one of them picks a cache the other would have rejected,
+which is the divergence the branch exists to remove.
+
+tests/python/test_cross_platform_parity.py pins the SOURCE of the installers against each
+other. This pins BEHAVIOUR: it runs both real implementations over the same fixtures and
+fails on any disagreement. Every rule here was added to one side and missed on the other at
+least once during review, which is why the check is a test rather than a convention.
+"""
+
+from __future__ import annotations
+
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+import pytest
+
+_REPO_ROOT = Path(__file__).resolve().parents[2]
+if str(_REPO_ROOT) not in sys.path:
+ sys.path.insert(0, str(_REPO_ROOT))
+
+_SETUP_SH = _REPO_ROOT / "studio" / "setup.sh"
+
+pytestmark = pytest.mark.skipif(
+ os.name != "posix", reason = "studio/setup.sh only ever runs on POSIX; install.ps1 is Windows"
+)
+
+# Windows has no os.geteuid, and a skipif DECORATOR is evaluated at collection, before the
+# module-level skip above can spare it. Reading it through getattr keeps the file importable
+# there; a non-root default is the right answer on a platform with no euid.
+_IS_ROOT = getattr(os, "geteuid", lambda: 1)() == 0
+
+# The helpers the two scans are built from. Sliced out by name because setup.sh does work at
+# load and cannot be sourced whole; a missing one would make every shell answer read as false,
+# so the extraction is asserted rather than assumed.
+_HELPERS = (
+ "_uv_is_bucket_name",
+ "_uv_cache_probe_writable",
+ "_uv_cache_folds_case",
+ "_uv_store_key",
+ "_uv_cache_usable",
+ "_uv_control_files_writable",
+ "_uv_cache_warm",
+)
+
+
+def _shell_helpers() -> str:
+ out: list[str] = []
+ grab = False
+ for line in _SETUP_SH.read_text(encoding = "utf-8").splitlines(keepends = True):
+ if any(line.startswith(f"{name}() {{") for name in _HELPERS):
+ grab = True
+ if grab:
+ out.append(line)
+ if line.startswith("}"):
+ grab = False
+ text = "".join(out)
+ missing = [name for name in _HELPERS if f"{name}() {{" not in text]
+ assert not missing, f"could not extract {missing} from studio/setup.sh"
+ return text
+
+
+def _ask_shell(func: str, cache: Path) -> bool:
+ script = _shell_helpers() + f'\nif {func} "$1"; then exit 0; else exit 1; fi\n'
+ # No inherited UV_* : a developer's own cache settings must not decide the answer.
+ env = {k: v for k, v in os.environ.items() if not k.startswith("UV_")}
+ return (
+ subprocess.run(
+ ["bash", "-c", script, "_", str(cache)], capture_output = True, env = env
+ ).returncode
+ == 0
+ )
+
+
+def _studio():
+ from unsloth_cli.commands import studio as _studio_mod
+ return _studio_mod
+
+
+def _warm(cache: Path, bucket: str = "archive-v0") -> Path:
+ (cache / bucket / "pkg").mkdir(parents = True, exist_ok = True)
+ (cache / bucket / "pkg" / "torch.whl").write_bytes(b"\0" * 8)
+ return cache
+
+
+def _build(cache: Path, shape: str) -> None:
+ cache.mkdir(parents = True, exist_ok = True)
+ if shape == "cold":
+ return
+ if shape == "metadata only":
+ (cache / "wheels-v6").mkdir()
+ (cache / "wheels-v6" / "resolve.msgpack").write_bytes(b"\0")
+ return
+ if shape == "lookalike bucket":
+ _warm(cache, "archive-v0.backup")
+ return
+ if shape == "unicode digit version":
+ _warm(cache, "archive-v١")
+ return
+ _warm(cache)
+ if shape == "warm":
+ return
+ if shape == "unrelated store":
+ (cache / "osv-v0").mkdir()
+ elif shape == "git store":
+ (cache / "git-v0").mkdir()
+ elif shape == "file at a store":
+ (cache / "interpreter-v4").write_bytes(b"")
+ elif shape == "lock is a directory":
+ (cache / ".lock").mkdir()
+ elif shape == "stray version-shaped dir":
+ (cache / "unused-v999").mkdir()
+ (cache / "unused-v999" / ".lock").write_bytes(b"")
+ elif shape == "index leaf is a symlinked dir":
+ (cache / "simple-v20").mkdir()
+ (cache / "elsewhere").mkdir()
+ (cache / "simple-v20" / "pypi").symlink_to(cache / "elsewhere")
+ elif shape == "index leaf is a file":
+ (cache / "simple-v20").mkdir()
+ (cache / "simple-v20" / "pypi").write_bytes(b"")
+ elif shape == "index leaf is a dangling link":
+ (cache / "wheels-v6").mkdir()
+ (cache / "wheels-v6" / "pypi").symlink_to(cache / "gone")
+ elif shape == "custom index hash leaf":
+ (cache / "simple-v20" / "index" / "e1d141a6ca947dff").mkdir(parents = True)
+ (cache / "wheels-v6" / "index" / "e1d141a6ca947dff").mkdir(parents = True)
+ elif shape == "index shard":
+ (cache / "simple-v20" / "pypi").mkdir(parents = True)
+ (cache / "wheels-v6" / "pypi").mkdir(parents = True)
+ (cache / "interpreter-v4" / "abcd").mkdir(parents = True)
+ elif shape == "control files present":
+ (cache / ".lock").write_bytes(b"")
+ (cache / "CACHEDIR.TAG").write_bytes(b"Signature")
+ else: # pragma: no cover - a typo in the parametrisation, not a product state
+ raise AssertionError(f"unknown shape {shape!r}")
+
+
+_SHAPES = [
+ "warm",
+ "cold",
+ "metadata only",
+ "lookalike bucket",
+ "unicode digit version",
+ "unrelated store",
+ "git store",
+ "file at a store",
+ "lock is a directory",
+ "stray version-shaped dir",
+ "control files present",
+ "index shard",
+ "index leaf is a file",
+ "index leaf is a dangling link",
+ "index leaf is a symlinked dir",
+ "custom index hash leaf",
+]
+
+
[email protected]("shape", _SHAPES)
+def test_both_implementations_agree_on_warmth(tmp_path, shape):
+ """Warmth decides WHICH cache is used, so a disagreement sends the two down different
+ caches for the same install."""
+ cache = tmp_path / "uv"
+ _build(cache, shape)
+ assert _ask_shell("_uv_cache_warm", cache) is _studio()._uv_cache_has_packages(cache)
+
+
[email protected]("shape", _SHAPES)
+def test_both_implementations_agree_on_usability(tmp_path, shape):
+ """Usability decides whether a cache is handed to uv at all. One side accepting what the
+ other rejects means uv aborts on one entry point and not the other."""
+ cache = tmp_path / "uv"
+ _build(cache, shape)
+ assert _ask_shell("_uv_cache_usable", cache) is _studio()._uv_cache_is_writable(cache)
+
+
[email protected](_IS_ROOT, reason = "root can write anywhere")
+ "store, usable",
+ [
+ # Probed, because `uv pip install` writes them: a read-only one aborts uv.
+ ("archive-v0", False),
+ ("sdists-v9", False),
+ ("git-v0", False),
+ # Not probed: measured on uv 0.10.7, `uv pip install` succeeds with these at 0555, so
+ # rejecting for them would throw away the warm cache the branch exists to find.
+ ("osv-v0", True),
+ ("binaries-v0", True),
+ ("environments-v2", True),
+ ("python-v0", True),
+ ("flat-index-v2", True),
+ ],
+)
+def test_both_implementations_agree_on_which_stores_are_probed(tmp_path, store, usable):
+ cache = _warm(tmp_path / "uv")
+ (cache / store).mkdir(exist_ok = True)
+ (cache / store).chmod(0o555)
+ try:
+ shell = _ask_shell("_uv_cache_usable", cache)
+ python = _studio()._uv_cache_is_writable(cache)
+ finally:
+ (cache / store).chmod(0o755)
+ assert shell is python, f"{store}: shell={shell} python={python}"
+ assert shell is usable
+
+
[email protected](_IS_ROOT, reason = "root can write anywhere")
+ "shard, usable",
+ [
+ # uv REWRITES index metadata on every resolve, so a shard it cannot write aborts it.
+ ("simple-v20/pypi", False),
+ ("wheels-v6/pypi", False),
+ # Content-addressed stores are only added to; measured, uv installs fine with these
+ # at 0555, and rejecting would discard the warm cache over a shard uv never rewrites.
+ ("interpreter-v4/abcd", True),
+ ("archive-v0/pkg", True),
+ # `index/<hash>` is where uv puts metadata for a CUSTOM --index-url, which Studio uses
+ # for the torch wheels. Measured on the pinned uv 0.12.1, a 0555 one aborts.
+ ("simple-v20/index/e1d141a6ca947dff", False),
+ ("wheels-v6/index/e1d141a6ca947dff", False),
+ # Bounded on purpose: the level below the hash is one per package and is measured fine.
+ ("wheels-v6/index/e1d141a6ca947dff/idna", True),
+ ("simple-v20/pypi/deeper", True),
+ ],
+)
+def test_both_implementations_agree_on_which_shards_are_probed(tmp_path, shard, usable):
+ cache = _warm(tmp_path / "uv")
+ (cache / shard).mkdir(parents = True, exist_ok = True)
+ (cache / shard).chmod(0o555)
+ try:
+ shell = _ask_shell("_uv_cache_usable", cache)
+ python = _studio()._uv_cache_is_writable(cache)
+ finally:
+ (cache / shard).chmod(0o755)
+ assert shell is python, f"{shard}: shell={shell} python={python}"
+ assert shell is usable
diff --git a/tests/sh/test_setup_uv_cache_marker.sh b/tests/sh/test_setup_uv_cache_marker.sh
new file mode 100644
index 00000000000..f40a43a3627
--- /dev/null
+++ b/tests/sh/test_setup_uv_cache_marker.sh
@@ -0,0 +1,554 @@
+#!/bin/sh
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+#
+# studio/setup.sh (the `unsloth studio update` entry point) used to pick $STUDIO_HOME/cache/uv
+# unconditionally, the EMPTY one on a shared-mode install, and refetched every wheel. It now
+# reads install.sh's marker on the CLI's terms (unsloth_cli/commands/studio.py): an explicit
+# UV_CACHE_DIR wins and is never recorded, UV_NO_CACHE leaves it unset, the marker wins only
+# while its cache holds packages, otherwise the Studio path if writable. setup.sh never
+# WRITES the marker: a recorded inference outlives its install.
+set -e
+
+SCRIPT_DIR=$(CDPATH= cd -- "$(dirname "$0")" && pwd)
+. "$SCRIPT_DIR/_harness.sh"
+SETUP_SH="$SCRIPT_DIR/../../studio/setup.sh"
+
+WORK=$(mktemp -d)
+trap 'rm -rf "$WORK"' EXIT INT TERM
+
+# The real helpers and selector, sliced out of setup.sh by their anchors (the selector is not a function).
+HELPERS=$(awk '
+ /^_uv_is_bucket_name\(\) \{/ { grab = 1 }
+ /^_uv_no_cache_requested\(\) \{/ { grab = 1 }
+ /^_uv_cache_probe_writable\(\) \{/ { grab = 1 }
+ /^_uv_cache_folds_case\(\) \{/ { grab = 1 }
+ /^_uv_store_key\(\) \{/ { grab = 1 }
+ /^_uv_cache_usable\(\) \{/ { grab = 1 }
+ /^_uv_control_files_writable\(\) \{/ { grab = 1 }
+ /^_uv_cache_warm\(\) \{/ { grab = 1 }
+ /^_recorded_uv_cache\(\) \{/ { grab = 1 }
+ /^_UV_MARKER_BOM=/ { print; next }
+ /^_UV_MARKER_CR=/ { print; next }
+ /^_UV_MARKER_LF=/ { print; next }
+ grab { print }
+ grab && /^}/ { grab = 0 }
+' "$SETUP_SH")
+SELECTOR=$(awk '
+ /^_uv_caller_value=false$/ { grab = 1 }
+ grab { print }
+ grab && /^fi$/ { exit }
+' "$SETUP_SH")
+
+for _need in _uv_is_bucket_name _uv_no_cache_requested _uv_cache_probe_writable _uv_cache_folds_case _uv_store_key _uv_cache_usable _uv_control_files_writable _uv_cache_warm _recorded_uv_cache; do
+ if ! printf '%s\n' "$HELPERS" | grep -q "^${_need}() {"; then
+ echo "FATAL: could not extract $_need from setup.sh" >&2
+ exit 1
+ fi
+done
+printf '%s\n' "$HELPERS" | grep -q '^_UV_MARKER_BOM=' || {
+ echo "FATAL: the BOM constant is gone" >&2; exit 1; }
+printf '%s\n' "$SELECTOR" | grep -q '_uv_cache_warm "\$_uv_recorded"' || {
+ echo "FATAL: could not extract the selector from setup.sh" >&2; exit 1; }
+
+PROBE_HELPERS="$WORK/helpers.sh"
+printf '%s\n' "$HELPERS" > "$PROBE_HELPERS"
+PROBE="$WORK/probe.sh"
+{
+ printf '%s\n' "$HELPERS"
+ cat <<'PROBE_BODY'
+case "$1" in
+ unset) unset UV_CACHE_DIR ;;
+ value) UV_CACHE_DIR=$2 ;;
+ *) exit 2 ;;
+esac
+case "$3" in
+ unset) unset UV_NO_CACHE ;;
+ value) UV_NO_CACHE=$4 ;;
+ *) exit 2 ;;
+esac
+STUDIO_HOME=$5
+PROBE_BODY
+ printf '%s\n' "$SELECTOR"
+ cat <<'PROBE_TAIL'
+printf '%s' "${UV_CACHE_DIR-<unset>}"
+PROBE_TAIL
+} > "$PROBE"
+
+warm() { # warm <cache dir> [bucket] [filename]
+ mkdir -p "$1/${2:-archive-v0}/pkg"
+ : > "$1/${2:-archive-v0}/pkg/${3:-payload.whl}"
+}
+
+record() { # record <studio home> <bytes...>
+ mkdir -p "$1/cache"
+ printf "$2" > "$1/cache/uv-cache-dir"
+}
+
+run() { # run <shell> <state> <input> <no-cache-state> <no-cache> <studio home>
+ "$1" "$PROBE" "$2" "$3" "$4" "$5" "$6"
+}
+
+# The same probe under setup.sh's own options (line 5): `set -o pipefail` turns a SIGPIPE inside
+# a command substitution into a failed pipeline, the difference between warm and refetched.
+run_strict() { # run_strict <state> <input> <no-cache-state> <no-cache> <studio home>
+ bash -e -u -o pipefail "$PROBE" "$1" "$2" "$3" "$4" "$5"
+}
+
+# A bucket with more names than a 64K pipe holds, built once (touching it is the slow part).
+# `find ... -print | head -n 1` reads THIS cache as cold under pipefail; every other fixture is
+# a handful of files, which is why the suite stayed green while updates refetched warm caches.
+BIG="$WORK/big cache/uv"
+mkdir -p "$BIG/archive-v0/pkg"
+awk -v d="$BIG/archive-v0/pkg" 'BEGIN { for (i = 0; i < 4000; i++)
+ printf "%s/wheel_payload_%05d.whl%c", d, i, 0 }' | xargs -0 touch
+
+echo "=== test_setup_uv_cache_marker ==="
+for shell in sh bash; do
+ command -v "$shell" >/dev/null 2>&1 || continue
+ CASE="$WORK/$shell case"
+ HOME_DIR="$CASE/studio home"
+ STUDIO_CACHE="$HOME_DIR/cache/uv"
+ SHARED="$CASE/shared cache/uv"
+ mkdir -p "$HOME_DIR"
+
+ assert_eq "$shell: no marker falls back to the Studio cache" \
+ "$STUDIO_CACHE" "$(run "$shell" unset "" unset "" "$HOME_DIR")"
+
+ warm "$SHARED"
+ record "$HOME_DIR" "$SHARED\\n"
+ assert_eq "$shell: a warm recorded cache is adopted" \
+ "$SHARED" "$(run "$shell" unset "" unset "" "$HOME_DIR")"
+
+ # Same file, written by Windows PowerShell 5.1 `-Encoding utf8`: BOM plus CRLF.
+ record "$HOME_DIR" "\\357\\273\\277$SHARED\\r\\n"
+ assert_eq "$shell: a BOM and a CRLF do not hide the path" \
+ "$SHARED" "$(run "$shell" unset "" unset "" "$HOME_DIR")"
+
+ # A recorded cache gone read-only since the install: warm, and useless to uv, which aborts on it.
+ RO="$CASE/read-only recorded/uv"
+ warm "$RO"
+ record "$HOME_DIR" "$RO\\n"
+ if [ "$(id -u 2>/dev/null || echo 0)" != 0 ] && chmod 555 "$RO" 2>/dev/null; then
+ assert_eq "$shell: a warm recorded cache that is not writable loses to the Studio cache" \
+ "$STUDIO_CACHE" "$(run "$shell" unset "" unset "" "$HOME_DIR")"
+ chmod 755 "$RO" 2>/dev/null || true
+ fi
+
+ # A cache the user cleared: content, not the record, has the last word on emptiness.
+ COLD="$CASE/emptied cache/uv"
+ mkdir -p "$COLD"
+ record "$HOME_DIR" "$COLD\\n"
+ assert_eq "$shell: an emptied recorded cache loses to the default" \
+ "$STUDIO_CACHE" "$(run "$shell" unset "" unset "" "$HOME_DIR")"
+
+ # uv 0.10 leaves .msgpack/.http in wheels-* after a bare resolve; that is not warm.
+ META="$CASE/metadata only/uv"
+ warm "$META" wheels-v6 resolve.msgpack
+ warm "$META" wheels-v6 wheel.http
+ record "$HOME_DIR" "$META\\n"
+ assert_eq "$shell: metadata alone is not a warm cache" \
+ "$STUDIO_CACHE" "$(run "$shell" unset "" unset "" "$HOME_DIR")"
+ warm "$META" wheels-v6 torch.whl
+ assert_eq "$shell: package bytes beside metadata do count" \
+ "$META" "$(run "$shell" unset "" unset "" "$HOME_DIR")"
+
+ # A writable root is not a usable cache: uv unpacks into the buckets, so a root-only probe
+ # adopts a recorded cache uv then aborts on (uv 0.10.7: "failed to rename", exit 1).
+ BLOCKED="$CASE/bucket blocked/uv"
+ warm "$BLOCKED"
+ record "$HOME_DIR" "$BLOCKED\\n"
+ if [ "$(id -u 2>/dev/null || echo 0)" != 0 ] && chmod 0555 "$BLOCKED/archive-v0" 2>/dev/null; then
+ assert_eq "$shell: a recorded cache with an unwritable bucket falls back to Studio" \
+ "$STUDIO_CACHE" "$(run "$shell" unset "" unset "" "$HOME_DIR")"
+ chmod 0755 "$BLOCKED/archive-v0" 2>/dev/null || true
+ fi
+ assert_eq "$shell: the same cache is adopted once its bucket is writable again" \
+ "$BLOCKED" "$(run "$shell" unset "" unset "" "$HOME_DIR")"
+
+ # Store versions reach two digits (uv 0.12.1 ships simple-v24), and `*-v[0-9]*` is "a digit
+ # then anything", so it matches those too. This pins that against a narrower glob.
+ MULTI="$CASE/multi-digit store/uv"
+ warm "$MULTI"
+ mkdir -p "$MULTI/simple-v24"
+ record "$HOME_DIR" "$MULTI\\n"
+ if [ "$(id -u 2>/dev/null || echo 0)" != 0 ] && chmod 0555 "$MULTI/simple-v24" 2>/dev/null; then
+ assert_eq "$shell: an unwritable multi-digit store falls back to Studio" \
+ "$STUDIO_CACHE" "$(run "$shell" unset "" unset "" "$HOME_DIR")"
+ chmod 0755 "$MULTI/simple-v24" 2>/dev/null || true
+ fi
+
+ # `archive-*` also matches `archive-v0.backup`, whose bytes uv cannot reuse. Counting them
+ # reads this cache as warm and then fails the offline update it was picked for (measured on
+ # uv 0.10.7: exit 1, "not found in the cache"). install.sh's scan rejects it the same way.
+ LOOKALIKE="$CASE/lookalike bucket/uv"
+ mkdir -p "$LOOKALIKE/archive-v0.backup/pkg"
+ : > "$LOOKALIKE/archive-v0.backup/pkg/torch.whl"
+ record "$HOME_DIR" "$LOOKALIKE\\n"
+ assert_eq "$shell: a lookalike bucket is not warmth" \
+ "$STUDIO_CACHE" "$(run "$shell" unset "" unset "" "$HOME_DIR")"
+
+ # A store path occupied by a FILE is an existing path to mkdir(2), so uv cannot create the
+ # store and aborts (measured: a plain file at archive-v0 exits 1, at interpreter-v4,
+ # sdists-v9, simple-v20 or wheels-v6 exits 2). Skipping it would call the cache usable.
+ BLOCKFILE="$CASE/store is a file/uv"
+ warm "$BLOCKFILE"
+ : > "$BLOCKFILE/interpreter-v4"
+ record "$HOME_DIR" "$BLOCKFILE\\n"
+ assert_eq "$shell: a file where a store belongs is not usable" \
+ "$STUDIO_CACHE" "$(run "$shell" unset "" unset "" "$HOME_DIR")"
+ rm -f "$BLOCKFILE/interpreter-v4"
+ assert_eq "$shell: and the same cache is adopted once it is gone" \
+ "$BLOCKFILE" "$(run "$shell" unset "" unset "" "$HOME_DIR")"
+
+ # `*-v[0-9]*/.lock` also reaches `unused-v999`, a kind `_uv_is_bucket_name` rejects on
+ # purpose. A read-only control-looking file there condemned a cache real uv uses fine
+ # (measured: probe REJECT, uv exit 0), so the standalone update lost its warm cache.
+ STRAY_CTL="$CASE/stray control file/uv"
+ warm "$STRAY_CTL"
+ mkdir -p "$STRAY_CTL/unused-v999"
+ : > "$STRAY_CTL/unused-v999/.lock"
+ record "$HOME_DIR" "$STRAY_CTL\\n"
+ if [ "$(id -u 2>/dev/null || echo 0)" != 0 ] && chmod 0444 "$STRAY_CTL/unused-v999/.lock" 2>/dev/null; then
+ assert_eq "$shell: a control file outside uv's stores does not condemn the cache" \
+ "$STRAY_CTL" "$(run "$shell" unset "" unset "" "$HOME_DIR")"
+ chmod 0644 "$STRAY_CTL/unused-v999/.lock" 2>/dev/null || true
+ fi
+ # ...while a .git inside a store still does. Measured on uv 0.10.7: sdists-v9/.git at 0444
+ # aborts with "Permission denied", exit 2. uv creates no per-store control files itself, so
+ # this one is someone else's, and it is the one proven to break uv.
+ mkdir -p "$STRAY_CTL/sdists-v9"
+ : > "$STRAY_CTL/sdists-v9/.git"
+ if [ "$(id -u 2>/dev/null || echo 0)" != 0 ] && chmod 0444 "$STRAY_CTL/sdists-v9/.git" 2>/dev/null; then
+ assert_eq "$shell: a read-only .git inside a store still does" \
+ "$STUDIO_CACHE" "$(run "$shell" unset "" unset "" "$HOME_DIR")"
+ chmod 0644 "$STRAY_CTL/sdists-v9/.git" 2>/dev/null || true
+ fi
+ # And the root .lock, the other one measured to abort (exit 2).
+ : > "$STRAY_CTL/.lock"
+ if [ "$(id -u 2>/dev/null || echo 0)" != 0 ] && chmod 0444 "$STRAY_CTL/.lock" 2>/dev/null; then
+ assert_eq "$shell: a read-only root .lock is not usable either" \
+ "$STUDIO_CACHE" "$(run "$shell" unset "" unset "" "$HOME_DIR")"
+ chmod 0644 "$STRAY_CTL/.lock" 2>/dev/null || true
+ fi
+ # A CACHEDIR.TAG at 0444 installs fine (measured), so it must not cost the warm cache.
+ : > "$STRAY_CTL/CACHEDIR.TAG"
+ if [ "$(id -u 2>/dev/null || echo 0)" != 0 ] && chmod 0444 "$STRAY_CTL/CACHEDIR.TAG" 2>/dev/null; then
+ assert_eq "$shell: a read-only CACHEDIR.TAG does not, since uv tolerates it" \
+ "$STRAY_CTL" "$(run "$shell" unset "" unset "" "$HOME_DIR")"
+ chmod 0644 "$STRAY_CTL/CACHEDIR.TAG" 2>/dev/null || true
+ fi
+
+ # uv cannot open a `.lock` that is not a regular file. Measured on uv 0.10.7: a directory
+ # there, and a symlink to one, both exit 2 with "Could not acquire lock ... Is a directory".
+ LOCKDIR="$CASE/lock is a directory/uv"
+ warm "$LOCKDIR"
+ mkdir -p "$LOCKDIR/.lock"
+ record "$HOME_DIR" "$LOCKDIR\\n"
+ assert_eq "$shell: a .lock directory is not a usable cache" \
+ "$STUDIO_CACHE" "$(run "$shell" unset "" unset "" "$HOME_DIR")"
+ rmdir "$LOCKDIR/.lock"
+ assert_eq "$shell: and the same cache is adopted once it is a file again" \
+ "$LOCKDIR" "$(run "$shell" unset "" unset "" "$HOME_DIR")"
+ mkdir -p "$CASE/lock target"
+ ln -s "$CASE/lock target" "$LOCKDIR/.lock"
+ assert_eq "$shell: a .lock symlinked to a directory is not either" \
+ "$STUDIO_CACHE" "$(run "$shell" unset "" unset "" "$HOME_DIR")"
+ rm -f "$LOCKDIR/.lock"
+
+ # The fold, at the two call sites rather than only in the helper. ext4 does not fold, so the
+ # measurement is stubbed both ways and what is pinned is that each scan acts on the answer.
+ fold_probe() { # fold_probe <shell> <folds:0|1> <expr>
+ # _FOLDS, not $2: inside the stub $2 is the STUB's argument, not the script's, so the
+ # answer read as empty and every fold case passed for the wrong reason.
+ "$1" -c '. "$1"
+_FOLDS=$2
+_uv_cache_folds_case() { [ "$_FOLDS" = 1 ]; }
+if eval "$3"; then echo yes; else echo no; fi' _ "$PROBE_HELPERS" "$2" "$3"
+ }
+ FOLDED="$CASE/folded store/uv"
+ mkdir -p "$FOLDED/Archive-V0/pkg"
+ : > "$FOLDED/Archive-V0/pkg/torch.whl"
+ assert_eq "$shell: a folded bucket counts as warmth on a folding filesystem" \
+ "yes" "$(fold_probe "$shell" 1 '_uv_cache_warm "'"$FOLDED"'"')"
+ assert_eq "$shell: and does not where the filesystem is case-sensitive" \
+ "no" "$(fold_probe "$shell" 0 '_uv_cache_warm "'"$FOLDED"'"')"
+
+ # Same for the control file: `Sdists-V9` passes the folded store test, so the .git inside it
+ # has to be probed under uv's spelling, not the raw one.
+ FOLDCTL="$CASE/folded sdists/uv"
+ mkdir -p "$FOLDCTL/archive-v0/pkg" "$FOLDCTL/Sdists-V9"
+ : > "$FOLDCTL/archive-v0/pkg/torch.whl"
+ : > "$FOLDCTL/Sdists-V9/.git"
+ if [ "$(id -u 2>/dev/null || echo 0)" != 0 ] && chmod 0444 "$FOLDCTL/Sdists-V9/.git" 2>/dev/null; then
+ assert_eq "$shell: a read-only .git in a folded sdists store is caught" \
+ "no" "$(fold_probe "$shell" 1 '_uv_cache_usable "'"$FOLDCTL"'"')"
+ assert_eq "$shell: and is left alone where the name is not uv's" \
+ "yes" "$(fold_probe "$shell" 0 '_uv_cache_usable "'"$FOLDCTL"'"')"
+ chmod 0644 "$FOLDCTL/Sdists-V9/.git" 2>/dev/null || true
+ fi
+
+ # A folding filesystem opens `Archive-V0` as the store uv writes at `archive-v0`, and a
+ # lowercase glob does not fold, so the warm scan read a full cache as cold and the offline
+ # update failed. Both scans go through _uv_store_key now, so they agree on the entry.
+ assert_eq "$shell: a folded store name resolves to uv's spelling" \
+ "archive-v0" "$($shell -c '. "$1"; _uv_store_key "Archive-V0" 1' _ "$PROBE_HELPERS")"
+ assert_eq "$shell: and is not claimed on a case-sensitive filesystem" \
+ "" "$($shell -c '. "$1"; _uv_store_key "Archive-V0" 0 || true' _ "$PROBE_HELPERS")"
+ assert_eq "$shell: a lookalike is never a store, folding or not" \
+ "" "$($shell -c '. "$1"; _uv_store_key "Archive-V0.backup" 1 || true' _ "$PROBE_HELPERS")"
+
+ # The FALLBACK Studio cache gets the same check as a recorded one. A root-only probe passes
+ # on a Studio cache whose archive-v0 went read-only, and uv then aborts (measured: exit 1,
+ # "Permission denied") instead of falling back to uv's own.
+ SICK="$CASE/sick studio/cache/uv"
+ mkdir -p "$SICK/archive-v0/pkg"
+ : > "$SICK/archive-v0/pkg/x.whl"
+ rm -f "$CASE/sick studio/cache/uv-cache-dir"
+ if [ "$(id -u 2>/dev/null || echo 0)" != 0 ] && chmod 0555 "$SICK/archive-v0" 2>/dev/null; then
+ assert_eq "$shell: an unusable Studio cache is dropped, not exported" \
+ "<unset>" "$(run "$shell" unset "" unset "" "$CASE/sick studio" 2>/dev/null)"
+ chmod 0755 "$SICK/archive-v0" 2>/dev/null || true
+ fi
+ assert_eq "$shell: and is used again once its store is writable" \
+ "$SICK" "$(run "$shell" unset "" unset "" "$CASE/sick studio")"
+
+ # Only the stores `uv pip install` writes, since that is the one uv command this file runs.
+ # Measured on uv 0.10.7 at 0555: binaries-v0, environments-v2, flat-index-v2, git-v0, osv-v0
+ # and python-v0 all install fine, so probing them only threw the warm cache away.
+ OFFSCOPE="$CASE/unrelated store/uv"
+ warm "$OFFSCOPE"
+ record "$HOME_DIR" "$OFFSCOPE\\n"
+ for store in binaries-v0 osv-v0 environments-v2 python-v0 flat-index-v2; do
+ mkdir -p "$OFFSCOPE/$store"
+ if [ "$(id -u 2>/dev/null || echo 0)" != 0 ] && chmod 0555 "$OFFSCOPE/$store" 2>/dev/null; then
+ assert_eq "$shell: a read-only $store does not condemn the cache" \
+ "$OFFSCOPE" "$(run "$shell" unset "" unset "" "$HOME_DIR")"
+ chmod 0755 "$OFFSCOPE/$store" 2>/dev/null || true
+ fi
+ done
+ # ...while a store pip install DOES write still does. git-v0 counts: a `git+` requirement
+ # writes it (measured: a git install creates git-v0 and builds-v0).
+ for store in archive-v0 git-v0 builds-v0; do
+ mkdir -p "$OFFSCOPE/$store"
+ if [ "$(id -u 2>/dev/null || echo 0)" != 0 ] && chmod 0555 "$OFFSCOPE/$store" 2>/dev/null; then
+ assert_eq "$shell: a read-only $store still does" \
+ "$STUDIO_CACHE" "$(run "$shell" unset "" unset "" "$HOME_DIR")"
+ chmod 0755 "$OFFSCOPE/$store" 2>/dev/null || true
+ fi
+ done
+
+ # One level inside the INDEX stores, which uv rewrites on every resolve. Measured on uv
+ # 0.10.7: a 0555 shard under simple-v20 or wheels-v6 aborts with "Failed to write to the
+ # client cache", exit 2, while one under archive-v0 or interpreter-v4 installs fine.
+ SHARD="$CASE/nested shard/uv"
+ warm "$SHARD"
+ mkdir -p "$SHARD/simple-v20/pypi" "$SHARD/wheels-v6/pypi" "$SHARD/interpreter-v4/abcd"
+ record "$HOME_DIR" "$SHARD\\n"
+ for blocked in simple-v20/pypi wheels-v6/pypi; do
+ if [ "$(id -u 2>/dev/null || echo 0)" != 0 ] && chmod 0555 "$SHARD/$blocked" 2>/dev/null; then
+ assert_eq "$shell: an unwritable $blocked shard falls back to Studio" \
+ "$STUDIO_CACHE" "$(run "$shell" unset "" unset "" "$HOME_DIR")"
+ chmod 0755 "$SHARD/$blocked" 2>/dev/null || true
+ fi
+ done
+ # ...and not deeper than that, nor in the content stores, where uv tolerates it and
+ # rejecting would throw away the warm cache over a shard it never rewrites.
+ if [ "$(id -u 2>/dev/null || echo 0)" != 0 ] && chmod 0555 "$SHARD/interpreter-v4/abcd" 2>/dev/null; then
+ assert_eq "$shell: an unwritable interpreter shard does not" \
+ "$SHARD" "$(run "$shell" unset "" unset "" "$HOME_DIR")"
+ chmod 0755 "$SHARD/interpreter-v4/abcd" 2>/dev/null || true
+ fi
+ mkdir -p "$SHARD/simple-v20/pypi/deeper"
+ if [ "$(id -u 2>/dev/null || echo 0)" != 0 ] && chmod 0555 "$SHARD/simple-v20/pypi/deeper" 2>/dev/null; then
+ assert_eq "$shell: nor a directory two levels down" \
+ "$SHARD" "$(run "$shell" unset "" unset "" "$HOME_DIR")"
+ chmod 0755 "$SHARD/simple-v20/pypi/deeper" 2>/dev/null || true
+ fi
+
+ # A non-directory AT the index leaf. Measured on the pinned uv 0.12.1: a plain file and a
+ # dangling symlink at simple-*/pypi or wheels-*/pypi both abort with "Failed to write to
+ # the client cache", exit 2. A `*/` glob matched neither, so the cache read as usable.
+ LEAFND="$CASE/leaf not a dir/uv"
+ warm "$LEAFND"
+ mkdir -p "$LEAFND/simple-v20"
+ : > "$LEAFND/simple-v20/pypi"
+ record "$HOME_DIR" "$LEAFND\\n"
+ assert_eq "$shell: a file at the index leaf is not a usable cache" \
+ "$STUDIO_CACHE" "$(run "$shell" unset "" unset "" "$HOME_DIR")"
+ rm -f "$LEAFND/simple-v20/pypi"
+ ln -s "$LEAFND/nowhere" "$LEAFND/simple-v20/pypi"
+ assert_eq "$shell: nor a dangling symlink there" \
+ "$STUDIO_CACHE" "$(run "$shell" unset "" unset "" "$HOME_DIR")"
+ # A symlink TO a directory is not the same thing and must stay adopted: uv writes through
+ # it (measured on the pinned uv 0.12.1, installs fine), and rejecting every link here would
+ # discard a cache whose index leaf is deliberately relocated.
+ rm -f "$LEAFND/simple-v20/pypi"
+ mkdir -p "$CASE/relocated index"
+ ln -s "$CASE/relocated index" "$LEAFND/simple-v20/pypi"
+ assert_eq "$shell: a leaf symlinked to a real directory is still adopted" \
+ "$LEAFND" "$(run "$shell" unset "" unset "" "$HOME_DIR")"
+ rm -f "$LEAFND/simple-v20/pypi"
+ mkdir -p "$LEAFND/simple-v20/pypi"
+ assert_eq "$shell: and it is adopted once the leaf is a directory" \
+ "$LEAFND" "$(run "$shell" unset "" unset "" "$HOME_DIR")"
+
+ # A CUSTOM --index-url, which Studio uses for the torch wheels, puts metadata at
+ # `<store>/index/<hash>`, not `<store>/pypi`. Measured on the pinned uv 0.12.1: a 0555
+ # `simple-*/index/<hash>` was ADOPTED by a one-level probe and then aborted the install
+ # with "Failed to write to the client cache". The only unsafe direction found so far.
+ CIDX="$CASE/custom index/uv"
+ warm "$CIDX"
+ mkdir -p "$CIDX/simple-v20/index/e1d141a6ca947dff" "$CIDX/wheels-v6/index/e1d141a6ca947dff/idna"
+ record "$HOME_DIR" "$CIDX\\n"
+ for blocked in simple-v20/index/e1d141a6ca947dff wheels-v6/index/e1d141a6ca947dff; do
+ if [ "$(id -u 2>/dev/null || echo 0)" != 0 ] && chmod 0555 "$CIDX/$blocked" 2>/dev/null; then
+ assert_eq "$shell: an unwritable $blocked falls back to Studio" \
+ "$STUDIO_CACHE" "$(run "$shell" unset "" unset "" "$HOME_DIR")"
+ chmod 0755 "$CIDX/$blocked" 2>/dev/null || true
+ fi
+ done
+ # ...and no deeper: the level below the hash is one directory per package.
+ if [ "$(id -u 2>/dev/null || echo 0)" != 0 ] && chmod 0555 "$CIDX/wheels-v6/index/e1d141a6ca947dff/idna" 2>/dev/null; then
+ assert_eq "$shell: a package directory under the hash does not" \
+ "$CIDX" "$(run "$shell" unset "" unset "" "$HOME_DIR")"
+ chmod 0755 "$CIDX/wheels-v6/index/e1d141a6ca947dff/idna" 2>/dev/null || true
+ fi
+
+ # An all-whitespace UV_CACHE_DIR is not a caller's choice. install.sh's selector decides
+ # this with `case *[![:space:]]*`; a plain `-n` here would read the same value as a choice
+ # and hand uv `--cache-dir ' '`, so the two selectors would answer differently for one
+ # environment. Whitespace-only falls through to the marker, exactly as it does in install.sh.
+ WS="$CASE/whitespace/uv"
+ warm "$WS"
+ record "$HOME_DIR" "$WS\\n"
+ assert_eq "$shell: an all-whitespace UV_CACHE_DIR is not a caller value" \
+ "$WS" "$(run "$shell" value " " unset "" "$HOME_DIR")"
+ assert_eq "$shell: a tab-only UV_CACHE_DIR is not a caller value" \
+ "$WS" "$(run "$shell" value "$(printf '\t')" unset "" "$HOME_DIR")"
+ # ...while one real character in it still is.
+ assert_eq "$shell: a caller value with surrounding space is still a caller value" \
+ " /caller/uv " "$(run "$shell" value " /caller/uv " unset "" "$HOME_DIR")"
+
+ for bucket in archive-v0 builds-v0 built-wheels-v3 sdists-v9; do
+ BUCKET_CACHE="$CASE/$bucket/uv"
+ warm "$BUCKET_CACHE" "$bucket"
+ record "$HOME_DIR" "$BUCKET_CACHE\\n"
+ assert_eq "$shell: $bucket counts as package data" \
+ "$BUCKET_CACHE" "$(run "$shell" unset "" unset "" "$HOME_DIR")"
+ done
+
+ # ...and one warm by thousands of files: the old `-print | head -n 1` scan read it as cold.
+ record "$HOME_DIR" "$BIG\\n"
+ assert_eq "$shell: a cache too big for one pipe buffer is still warm" \
+ "$BIG" "$(run "$shell" unset "" unset "" "$HOME_DIR")"
+ if [ "$shell" = bash ]; then
+ assert_eq "$shell: ...under setup.sh's own set -euo pipefail too" \
+ "$BIG" "$(run_strict unset "" unset "" "$HOME_DIR")"
+ fi
+
+ # ...and one with a leaf this user cannot read, walked before the hit (find exits nonzero
+ # after it, even once the hit printed, and `|| _uvw_hit=""` threw the hit away). Denied
+ # leaves are created and named first, and added until `ls -f` shows one ahead of the hit.
+ DENIED="$CASE/denied leaf/uv"
+ mkdir -p "$DENIED/archive-v0/hidden 1"
+ : > "$DENIED/archive-v0/hidden 1/other.whl"
+ chmod 000 "$DENIED/archive-v0/hidden 1" 2>/dev/null || true
+ warm "$DENIED" archive-v0 visible.whl
+ _leaf=1
+ while [ "$_leaf" -lt 40 ] && \
+ [ "$(ls -f "$DENIED/archive-v0" | grep -v '^\.\.*$' | head -n 1)" = pkg ]; do
+ _leaf=$((_leaf + 1))
+ mkdir -p "$DENIED/archive-v0/hidden $_leaf"
+ : > "$DENIED/archive-v0/hidden $_leaf/other.whl"
+ chmod 000 "$DENIED/archive-v0/hidden $_leaf" 2>/dev/null || true
+ done
+ if [ "$(id -u 2>/dev/null || echo 0)" != 0 ] && [ ! -r "$DENIED/archive-v0/hidden 1" ]; then
+ record "$HOME_DIR" "$DENIED\\n"
+ assert_eq "$shell: a warm cache with an unreadable leaf is still warm" \
+ "$DENIED" "$(run "$shell" unset "" unset "" "$HOME_DIR")"
+ if [ "$shell" = bash ]; then
+ assert_eq "$shell: ...under setup.sh's own set -euo pipefail too" \
+ "$DENIED" "$(run_strict unset "" unset "" "$HOME_DIR")"
+ fi
+ fi
+ for _leaf in "$DENIED/archive-v0"/hidden*; do
+ chmod 755 "$_leaf" 2>/dev/null || true
+ done
+
+ # A relative record names a different directory in each phase: declined, not guessed at.
+ record "$HOME_DIR" "relative/cache\\n"
+ assert_eq "$shell: a relative record is declined" \
+ "$STUDIO_CACHE" "$(run "$shell" unset "" unset "" "$HOME_DIR")"
+
+ record "$HOME_DIR" "\\n"
+ assert_eq "$shell: an empty record is declined" \
+ "$STUDIO_CACHE" "$(run "$shell" unset "" unset "" "$HOME_DIR")"
+
+ # A pathname ending in a newline: the CLI writes one delimiter and removes exactly one; a
+ # reader that let substitution strip every trailing newline checked another directory.
+ NLCACHE="$CASE/trailing newline"
+ NLCACHE="$NLCACHE$(printf '\nx')"
+ NLCACHE=${NLCACHE%x}
+ warm "$NLCACHE"
+ record "$HOME_DIR" "$NLCACHE\\n"
+ assert_eq "$shell: a pathname ending in a newline round-trips" \
+ "${NLCACHE}x" "$(run "$shell" unset "" unset "" "$HOME_DIR"; printf x)"
+
+ # A caller value outranks every inference, and is never written anywhere.
+ record "$HOME_DIR" "$SHARED\\n"
+ OVERRIDE="$CASE/caller cache"
+ assert_eq "$shell: an explicit UV_CACHE_DIR wins over the marker" \
+ "$OVERRIDE" "$(run "$shell" value "$OVERRIDE" unset "" "$HOME_DIR")"
+
+ for truthy in 1 true TRUE yes ON y t; do
+ assert_eq "$shell: UV_NO_CACHE=[$truthy] leaves the cache unset" \
+ "<unset>" "$(run "$shell" unset "" value "$truthy" "$HOME_DIR")"
+ done
+ # An exported EMPTY UV_CACHE_DIR is not a caller value; uv fails on it, so no-cache mode unsets it.
+ assert_eq "$shell: an empty UV_CACHE_DIR under UV_NO_CACHE is unset, not kept" \
+ "<unset>" "$(run "$shell" value "" value 1 "$HOME_DIR")"
+ # A padded value is not truthy: clap rejects ` on ` outright rather than reading it as
+ # true, so uv's cache stays ON and the selection must not stand down. install.sh and the
+ # CLI both strip nothing for the same reason.
+ for falsy in 0 false "" maybe " on "; do
+ assert_eq "$shell: UV_NO_CACHE=[$falsy] changes nothing" \
+ "$SHARED" "$(run "$shell" unset "" value "$falsy" "$HOME_DIR")"
+ done
+
+ # uv aborts on a cache it cannot create: an unwritable Studio path unsets rather than exports.
+ BLOCKED="$CASE/blocked"
+ : > "$BLOCKED"
+ assert_eq "$shell: an uncreatable Studio cache is dropped, not exported" \
+ "<unset>" "$(run "$shell" unset "" unset "" "$BLOCKED")"
+
+ # ...and the probe file does not survive into the cache uv then fills.
+ PROBED="$CASE/probed home"
+ run "$shell" unset "" unset "" "$PROBED" >/dev/null
+ assert_eq "$shell: the write probe cleans up after itself" \
+ "" "$(ls -A "$PROBED/cache/uv" 2>/dev/null)"
+done
+
+# setup.sh must never become a marker writer: only an installer's own choice is one.
+_writes=$(awk '
+ /^_uv_is_bucket_name\(\) \{/ { grab = 1 }
+ /^_uv_no_cache_requested\(\) \{/ { grab = 1 }
+ /^if \[ -n "\$\{UV_CACHE_DIR:-\}" \]; then$/ { grab = 1 }
+ grab { print }
+ grab && /^fi$/ { exit }
+' "$SETUP_SH" | grep -c 'uv-cache-dir"' || true)
+assert_eq "the block reads the marker and never writes it" "1" "$_writes"
+if grep -n 'uv-cache-dir' "$SETUP_SH" | grep -vq 'cat "\$STUDIO_HOME/cache/uv-cache-dir"'; then
+ bad "setup.sh names the uv cache marker somewhere other than the one read"
+else
+ ok "setup.sh names the uv cache marker exactly once, to read it"
+fi
+
+echo ""
+echo " PASS: $PASS"
+echo " FAIL: $FAIL"
+if [ "$FAIL" -gt 0 ]; then
+ echo "FAILED"
+ exit 1
+fi
+echo "ALL PASSED"
diff --git a/unsloth_cli/commands/studio.py b/unsloth_cli/commands/studio.py
index 625012d90d4..d04637fcd52 100644
--- a/unsloth_cli/commands/studio.py
+++ b/unsloth_cli/commands/studio.py
@@ -3172,6 +3172,21 @@ _PS_PROXY_DEFAULTS_PRELUDE = (
_UV_CACHE_BUCKETS = ("archive", "builds", "built-wheels", "wheels", "sdists")
+# The subset `uv pip install` CREATES, which is the only uv command studio/setup.sh runs. The
+# rule is what uv is measured to write: a `git+` requirement creates git-v0 and builds-v0, so
+# those are in, while flat-index-v2 is not created even by `--find-links --no-index`, and
+# binaries, environments, osv and python belong to uv self-update, uv venv and uv python.
+# Probing a store uv never touches only throws warm caches away. Re-measure on a pin bump.
+_UV_PIP_STORES = (
+ "archive",
+ "builds",
+ "built-wheels",
+ "git",
+ "interpreter",
+ "sdists",
+ "simple",
+ "wheels",
+)
_UV_CACHE_METADATA_SUFFIXES = (".lock", ".msgpack", ".http", ".rev")
@@ -3186,6 +3201,24 @@ def _uv_is_bucket_name(name: str) -> bool:
return bool(marker) and version.isascii() and version.isdigit() and kind in _UV_CACHE_BUCKETS
+def _uv_bucket_entry_name(cache_dir: Path, entry: Path) -> Optional[str]:
+ """The name uv opens this entry as, or None if uv does not own it.
+
+ On APFS or NTFS `Archive-V0` IS the directory uv writes at `archive-v0`, so a case-sensitive
+ match called a full cache cold while studio/setup.sh, which folds, called it warm, and the
+ two then chose different caches. samefile rather than a write probe: only existing entries
+ matter here, so the filesystem can be asked without creating anything."""
+ if _uv_is_bucket_name(entry.name):
+ return entry.name
+ lowered = entry.name.lower()
+ if lowered == entry.name or not _uv_is_bucket_name(lowered):
+ return None
+ try:
+ return lowered if (cache_dir / lowered).samefile(entry) else None
+ except OSError:
+ return None
+
+
def _uv_cache_has_packages(cache_dir: Path) -> bool:
"""wheels-* is metadata only on uv 0.10, so counting any file reads a merely-resolved cache
as warm. Same rule as install.sh:_configure_uv_cache, the WHOLE `-v` suffix included: a
@@ -3195,7 +3228,7 @@ def _uv_cache_has_packages(cache_dir: Path) -> bool:
buckets = [
entry
for entry in cache_dir.iterdir()
- if _uv_is_bucket_name(entry.name) and entry.is_dir()
+ if entry.is_dir() and _uv_bucket_entry_name(cache_dir, entry) is not None
]
except (OSError, ValueError):
return False
@@ -3317,24 +3350,161 @@ def _backfill_uv_cache_marker(env: Optional[dict]) -> None:
pass
+def _uv_is_store_name(name: str) -> bool:
+ """The kinds `uv pip install` writes: _uv_is_bucket_name answers warmth, this answers what a
+ write probe has to cover. Narrower than install.sh's list on purpose, since install.sh also
+ runs uv venv and uv python; re-read uv-cache/src/lib.rs on a pin bump."""
+ kind, marker, version = name.rpartition("-v")
+ return bool(marker) and version.isascii() and version.isdigit() and kind in _UV_PIP_STORES
+
+
+def _uv_cache_folds_case(cache_dir: Path) -> bool:
+ """Measured on the cache filesystem, not assumed from the platform, exactly as install.sh
+ does it: default APFS folds, ext4 does not, and a Mac can have either mounted."""
+ probe = cache_dir / f".unsloth-case-probe.{os.getpid()}-A"
+ try:
+ probe.mkdir()
+ except OSError:
+ return False
+ try:
+ return (cache_dir / f".unsloth-case-probe.{os.getpid()}-a").is_dir()
+ finally:
+ try:
+ probe.rmdir()
+ except OSError:
+ pass
+
+
+def _uv_cache_is_writable(cache_dir: Path) -> bool:
+ """A real create, as install.sh's write probe does: mode bits do not answer for a network mount, and uv aborts on a cache it
+ cannot write rather than falling back.
+
+ The stores too, not just the root: uv writes into them, so a root-only probe passes on a
+ cache uv then aborts on. Mirrors install.sh's _uv_cache_is_writable."""
+ probes = [cache_dir]
+ folds = _uv_cache_folds_case(cache_dir)
+ try:
+ # Only the directories uv OWNS: an unrelated read-only one must not disqualify a
+ # usable cache, and that is what the kind list above is for.
+ for entry in cache_dir.iterdir():
+ if not _uv_is_store_name(entry.name):
+ # On APFS or NTFS `Python-V0` is the same path uv opens as `python-v0`, so
+ # skipping it would report a cache writable that uv then aborts on.
+ if not (folds and _uv_is_store_name(entry.name.lower())):
+ continue
+ if not entry.is_dir():
+ # A file, or a symlink dangling or not, is an existing path to mkdir, so uv
+ # cannot make the store and aborts. Skipping it would report the cache writable.
+ return False
+ probes.append(entry)
+ # One level inside the index stores, and only those. uv REWRITES this metadata on
+ # every resolve, so a shard another account owns aborts it. Measured on BOTH the
+ # pinned uv 0.12.1 and 0.10.7: a 0555 `simple-*/pypi` or `wheels-*/pypi` gives
+ # "Failed to write to the client cache", exit 2. One level is the leaf on both:
+ # 0.12.1 lays this out as `simple-v24/pypi`, not `simple-v24/index/<hash>`, and a
+ # 0555 `wheels-v6/pypi/requests` one deeper installs fine. Bounded on purpose.
+ if entry.name.lower().startswith(("simple-", "wheels-")):
+ # `index/<hash>`, one per CUSTOM index, is where uv puts metadata when
+ # --index-url is set, which Studio does for the torch wheels. Measured on the
+ # pinned uv 0.12.1: a 0555 `simple-v24/index/<hash>` passes a one-level probe
+ # and then aborts with "Failed to write to the client cache".
+ shards = list(entry.iterdir())
+ index_dir = entry / "index"
+ if index_dir.is_dir():
+ shards.extend(index_dir.iterdir())
+ for shard in shards:
+ if not shard.is_dir():
+ # Same rule as the store level: a file, or a symlink dangling or not, is
+ # an existing path uv can neither open nor mkdir. Measured on the pinned
+ # uv 0.12.1, both abort with "Failed to write to the client cache".
+ return False
+ probes.append(shard)
+ except OSError:
+ return False
+ for target in probes:
+ try:
+ with tempfile.NamedTemporaryFile(dir = target, prefix = ".unsloth-write-probe."):
+ pass
+ except OSError:
+ return False
+ # Only the names uv is measured to need writable: rejecting more throws away the warm cache
+ # this path exists to find. Every control file at 0444 against uv 0.10.7: the root .lock
+ # aborts (exit 2) and sdists-v9/.git aborts (exit 2); root CACHEDIR.TAG and .gitignore, and
+ # .git/.gitignore/.lock under archive-v0, interpreter-v4, simple-v20 and wheels-v6, all
+ # install fine. uv creates only the three root files, so a per-store .git is someone else's.
+ for target in probes:
+ if target == cache_dir:
+ names = (".lock",)
+ elif target.name.lower().startswith("sdists-"):
+ # The one store measured to abort on a read-only .git. Rejecting a cache uv accepts
+ # costs the warm cache this path exists to find, so the rest are left alone.
+ names = (".git",)
+ else:
+ continue
+ for name in names:
+ control = target / name
+ if not control.exists() and not control.is_symlink():
+ continue
+ # Not a regular file, so uv cannot open it at all: measured on uv 0.10.7, a `.lock`
+ # DIRECTORY or a symlink to one exits 2 with "Could not acquire lock ... Is a
+ # directory". is_file() alone skipped it and reported the cache usable.
+ if not control.is_file() or not os.access(control, os.R_OK | os.W_OK):
+ return False
+ return True
+
+
def _with_studio_uv_cache(env: Optional[dict], cwd: Optional[Path] = None) -> Optional[dict]:
"""An update reached neither installer nor _setup_cache_env, so uv re-downloaded
what the install had just fetched."""
if (os.environ.get("UV_CACHE_DIR") or "").strip():
return env
if _uv_no_cache_requested():
- return env
+ # Removed, not left alone: uv parses an exported EMPTY value as `--cache-dir ''` even
+ # under --no-cache and exits 2, "a value is required for '--cache-dir'". setup.sh unsets
+ # it in its own no-cache branch; setup.ps1 has no cache handling at all, so on Windows a
+ # blank inherited value reached uv and failed the update before no-cache took effect.
+ no_cache = {**(env or os.environ)}
+ no_cache.pop("UV_CACHE_DIR", None)
+ return no_cache
studio_cache = STUDIO_HOME / "cache" / "uv"
recorded = _recorded_install_uv_cache()
- if recorded is not None and _uv_cache_has_packages(recorded):
- # Only while it holds something: a marker for an emptied cache loses to a warm one.
+ if (
+ recorded is not None
+ and _uv_cache_has_packages(recorded)
+ and _uv_cache_is_writable(recorded)
+ ):
+ # Only while it holds something and uv can still write to it: a marker for an emptied cache loses to a warm one, and setup treats
+ # the value this hands it as the caller's choice, so a cache gone read-only since the install would abort every uv command.
return {**(env or os.environ), "UV_CACHE_DIR": str(recorded)}
# Content cannot settle it: one on-demand wheel warms the Studio cache even in shared mode,
# so uv's default goes first and a warm Studio cache is the fallback below. The installers
# order the same three the same way.
default_cache = _uv_default_cache_dir(cwd)
- if default_cache is not None and _uv_cache_has_packages(default_cache):
+ if (
+ default_cache is not None
+ and _uv_cache_has_packages(default_cache)
+ and _uv_cache_is_writable(default_cache)
+ ):
return {**(env or os.environ), "UV_CACHE_DIR": str(default_cache)}
+ # setup.sh treats an inherited UV_CACHE_DIR as the caller's choice and skips its own write
+ # probe, so handing it an unwritable Studio cache aborts every uv command in the update --
+ # the one branch here that was still unprobed. Left unset, setup.sh probes and falls back.
+ #
+ # Only for a root that already exists, and the root is never created here: setup.sh fails
+ # fast on a STUDIO_HOME override that does not, exactly so a typo cannot materialise an
+ # empty workspace, and making the cache under it first would satisfy that guard and let the
+ # update run on against a tree with no venv.
+ if STUDIO_HOME.is_dir():
+ try:
+ studio_cache.mkdir(parents = True, exist_ok = True)
+ except OSError:
+ pass
+ if not _uv_cache_is_writable(studio_cache):
+ # Explicitly absent rather than a bare `return env`: the other branches all hand back
+ # a dict, and setup.sh's own probe wants the variable gone, not inherited from here.
+ unset = {**(env or os.environ)}
+ unset.pop("UV_CACHE_DIR", None)
+ return unset
return {**(env or os.environ), "UV_CACHE_DIR": str(studio_cache)}
diff --git a/unsloth_cli/tests/test_studio_update_uv_cache.py b/unsloth_cli/tests/test_studio_update_uv_cache.py
index 5611fc19f62..d16cf8dde50 100644
--- a/unsloth_cli/tests/test_studio_update_uv_cache.py
+++ b/unsloth_cli/tests/test_studio_update_uv_cache.py
@@ -981,3 +981,291 @@ def test_files_outside_a_bucket_are_not_warm(tmp_path):
(cache / "simple-v20" / "index.msgpack").write_bytes(b"\0")
assert studio._uv_cache_has_packages(cache) is False
+
+
+ os.name != "posix", reason = "POSIX mode bits; chmod(0o555) denies nothing on Windows"
+)
+def test_a_recorded_cache_that_is_no_longer_writable_loses_to_the_studio_cache(
+ monkeypatch, tmp_path, caches
+):
+ """setup treats the value this hands it as the caller's choice and never probes it
+ again, and uv aborts on a cache it cannot write, so a share remounted read-only since
+ the install has to lose here."""
+ if getattr(os, "geteuid", lambda: 1)() == 0:
+ pytest.skip("root can write anywhere")
+ studio = _studio()
+ studio_cache, _default = caches
+ recorded = tmp_path / "shared-uv"
+ _fill(recorded)
+ _fill(studio_cache)
+ (studio.STUDIO_HOME / "cache").mkdir(parents = True, exist_ok = True)
+ (studio.STUDIO_HOME / "cache" / "uv-cache-dir").write_text(f"{recorded}\n", encoding = "utf-8")
+ recorded.chmod(0o555)
+ try:
+ seen = _run_posix(monkeypatch, tmp_path)
+ finally:
+ recorded.chmod(0o755)
+ assert seen["env"]["UV_CACHE_DIR"] == str(studio_cache)
+ recorded.chmod(0o755)
+ seen = _run_posix(monkeypatch, tmp_path)
+ assert seen["env"]["UV_CACHE_DIR"] == str(recorded)
+
+
+ os.name != "posix", reason = "POSIX mode bits; chmod(0o555) denies nothing on Windows"
+)
+def test_an_unwritable_studio_cache_is_not_forced_on_setup(monkeypatch, tmp_path, caches):
+ """The last fallback was the one branch here that never probed.
+
+ setup.sh treats any UV_CACHE_DIR it inherits as the caller's choice and skips its own
+ write probe, so handing it a Studio cache uv cannot write aborts every uv command in
+ the update. Leaving the variable alone lets setup.sh probe and fall back to uv's
+ default, which is what it does when it runs standalone.
+ """
+ if getattr(os, "geteuid", lambda: 1)() == 0:
+ pytest.skip("root can write anywhere")
+ studio = _studio()
+ studio_cache, _default = caches
+ # Neither the marker nor uv's default can settle it, so the Studio cache is the choice.
+ studio_cache.parent.mkdir(parents = True, exist_ok = True)
+ studio_cache.mkdir(parents = True, exist_ok = True)
+ studio_cache.chmod(0o555)
+ try:
+ seen = _run_posix(monkeypatch, tmp_path)
+ finally:
+ studio_cache.chmod(0o755)
+ assert "UV_CACHE_DIR" not in seen["env"], seen["env"].get("UV_CACHE_DIR")
+
+ # Writable again, and it is handed over as before.
+ seen = _run_posix(monkeypatch, tmp_path)
+ assert seen["env"]["UV_CACHE_DIR"] == str(studio_cache)
+
+
+ os.name != "posix", reason = "POSIX mode bits; chmod(0o555) denies nothing on Windows"
+)
+def test_a_store_with_a_two_digit_version_is_probed(tmp_path):
+ """uv 0.12.1 names its registry store simple-v24, so the probe's `*-v[0-9]*` has to reach
+ two-digit versions as well as one-digit ones."""
+ if getattr(os, "geteuid", lambda: 1)() == 0:
+ pytest.skip("root can write anywhere")
+ studio = _studio()
+ cache = tmp_path / "shared-uv"
+ _fill(cache)
+ (cache / "simple-v24").mkdir()
+ (cache / "simple-v24").chmod(0o555)
+ try:
+ assert studio._uv_cache_is_writable(cache) is False
+ finally:
+ (cache / "simple-v24").chmod(0o755)
+ assert studio._uv_cache_is_writable(cache) is True
+
+
+def test_a_mistyped_studio_home_is_not_materialised_by_the_probe(monkeypatch, tmp_path):
+ """setup.sh fails fast on a STUDIO_HOME override that does not exist, so a typo cannot
+ leave an empty workspace behind. Creating the cache under it first satisfies that guard
+ and the update runs on against a tree with no venv."""
+ studio = _studio()
+ missing = tmp_path / "typo studio home"
+ monkeypatch.setattr(studio, "STUDIO_HOME", missing)
+ monkeypatch.delenv("UV_CACHE_DIR", raising = False)
+ monkeypatch.setattr(studio, "_uv_default_cache_dir", lambda cwd = None: tmp_path / "no default")
+
+ env = studio._with_studio_uv_cache(None)
+
+ assert not missing.exists(), sorted(p.name for p in tmp_path.iterdir())
+ # Still named, so setup.sh is told the same path it would have picked itself.
+ assert env["UV_CACHE_DIR"] == str(missing / "cache" / "uv")
+
+
+def test_a_file_where_a_store_belongs_makes_the_cache_unusable(tmp_path):
+ """An existing non-directory is an existing path to mkdir, so uv cannot create the store and
+ aborts: measured on uv 0.10.7, a plain file at archive-v0 exits 1 and at interpreter-v4,
+ sdists-v9, simple-v20 or wheels-v6 exits 2. Skipping it reports the cache writable."""
+ studio = _studio()
+ cache = tmp_path / "shared-uv"
+ _fill(cache)
+ blocked = cache / "interpreter-v4"
+ blocked.write_bytes(b"")
+ assert studio._uv_cache_is_writable(cache) is False
+ blocked.unlink()
+ assert studio._uv_cache_is_writable(cache) is True
+
+
+def test_a_dangling_symlink_where_a_store_belongs_is_rejected(tmp_path):
+ """Same reason, and the shape a moved cache leaves behind: mkdir fails on the link itself."""
+ studio = _studio()
+ cache = tmp_path / "shared-uv"
+ _fill(cache)
+ (cache / "simple-v24").symlink_to(tmp_path / "gone")
+ assert studio._uv_cache_is_writable(cache) is False
+
+
+ os.name != "posix", reason = "POSIX mode bits; chmod(0o555) denies nothing on Windows"
+)
+def test_a_case_folded_store_name_is_probed(monkeypatch, tmp_path):
+ """On APFS or NTFS `Python-V0` is the same path uv opens as `python-v0`. This box is ext4,
+ so the fold is stubbed: what is under test is that the probe acts on the answer, not that
+ it can measure a folding filesystem it does not have."""
+ if getattr(os, "geteuid", lambda: 1)() == 0:
+ pytest.skip("root can write anywhere")
+ studio = _studio()
+ cache = tmp_path / "shared-uv"
+ _fill(cache)
+ odd = cache / "Interpreter-V4"
+ odd.mkdir()
+ odd.chmod(0o555)
+ try:
+ monkeypatch.setattr(studio, "_uv_cache_folds_case", lambda cache_dir: False)
+ assert studio._uv_cache_is_writable(cache) is True, "case-sensitive: not uv's path"
+ monkeypatch.setattr(studio, "_uv_cache_folds_case", lambda cache_dir: True)
+ assert studio._uv_cache_is_writable(cache) is False, "folding: uv opens this one"
+ finally:
+ odd.chmod(0o755)
+
+
+def test_the_fold_probe_leaves_nothing_behind(tmp_path):
+ studio = _studio()
+ cache = tmp_path / "shared-uv"
+ _fill(cache)
+ before = sorted(p.name for p in cache.iterdir())
+ studio._uv_cache_folds_case(cache)
+ assert sorted(p.name for p in cache.iterdir()) == before
+
+
+def test_a_lock_that_is_not_a_regular_file_makes_the_cache_unusable(tmp_path):
+ """uv cannot open it at all. Measured on uv 0.10.7: a `.lock` directory, and a symlink to
+ one, both exit 2 with "Could not acquire lock ... Is a directory". is_file() skipped both."""
+ studio = _studio()
+ cache = tmp_path / "shared-uv"
+ _fill(cache)
+ lock = cache / ".lock"
+ lock.mkdir()
+ assert studio._uv_cache_is_writable(cache) is False
+ lock.rmdir()
+ assert studio._uv_cache_is_writable(cache) is True
+ (tmp_path / "lock target").mkdir()
+ lock.symlink_to(tmp_path / "lock target")
+ assert studio._uv_cache_is_writable(cache) is False
+ lock.unlink()
+ assert studio._uv_cache_is_writable(cache) is True
+
+
+ os.name != "posix", reason = "POSIX mode bits; chmod(0o555) denies nothing on Windows"
+)
+ "store", ["binaries-v0", "osv-v0", "environments-v2", "python-v0", "flat-index-v2"]
+)
+def test_a_store_pip_install_never_writes_does_not_condemn_the_cache(tmp_path, store):
+ """setup.sh runs only `uv pip install`. Measured on uv 0.10.7 at 0555: binaries-v0, osv-v0,
+ environments-v2, flat-index-v2, git-v0 and python-v0 all install fine, so probing the ones
+ pip never writes only threw away the warm cache this path exists to find."""
+ if getattr(os, "geteuid", lambda: 1)() == 0:
+ pytest.skip("root can write anywhere")
+ studio = _studio()
+ cache = tmp_path / "shared-uv"
+ _fill(cache)
+ (cache / store).mkdir()
+ (cache / store).chmod(0o555)
+ try:
+ assert studio._uv_cache_is_writable(cache) is True
+ finally:
+ (cache / store).chmod(0o755)
+
+
+ os.name != "posix", reason = "POSIX mode bits; chmod(0o555) denies nothing on Windows"
+)
[email protected]("store", ["archive-v0", "git-v0", "builds-v0"])
+def test_a_store_pip_install_does_write_still_condemns_it(tmp_path, store):
+ """git-v0 and builds-v0 count: a `git+` requirement writes both."""
+ if getattr(os, "geteuid", lambda: 1)() == 0:
+ pytest.skip("root can write anywhere")
+ studio = _studio()
+ cache = tmp_path / "shared-uv"
+ _fill(cache)
+ (cache / store).mkdir(exist_ok = True)
+ (cache / store).chmod(0o555)
+ try:
+ assert studio._uv_cache_is_writable(cache) is False
+ finally:
+ (cache / store).chmod(0o755)
+
+
+def _simulate_case_folding(monkeypatch):
+ """Make lookups fold, as APFS and NTFS do, without a folding filesystem to hand.
+
+ A symlink will NOT do: on a folding filesystem there is ONE directory entry, and adding a
+ lowercase link creates a second one that the case-SENSITIVE code path matches directly. A
+ test built that way passes with the fold removed, which is how the first version of this
+ got through its own mutation check.
+ """
+ real = Path.samefile
+
+ def folding_samefile(self, other):
+ if str(self).lower() == str(other).lower():
+ return True
+ return real(self, other)
+
+ monkeypatch.setattr(Path, "samefile", folding_samefile)
+
+
+def test_a_folded_bucket_name_counts_as_warmth(tmp_path, monkeypatch):
+ """On APFS or NTFS `Archive-V0` IS the directory uv writes at `archive-v0`. A case-sensitive
+ match called such a cache cold while studio/setup.sh, which folds, called it warm, so the
+ two chose different caches on exactly the platform Studio ships a Mac build for."""
+ studio = _studio()
+ cache = tmp_path / "shared-uv"
+ (cache / "Archive-V0" / "pkg").mkdir(parents = True)
+ (cache / "Archive-V0" / "pkg" / "torch.whl").write_bytes(b"\0" * 8)
+
+ # On a filesystem that really folds (APFS, NTFS) the bytes are already where uv looks, and
+ # asserting the case-SENSITIVE answer first would fail there. Ask the filesystem rather than
+ # assume: this was green on ext4 and red on the macOS runner until it did.
+ if (cache / "archive-v0").exists():
+ assert studio._uv_cache_has_packages(cache) is True
+ return
+ # Case-sensitive: uv opens archive-v0, which is not there, so those bytes are unreachable.
+ assert studio._uv_cache_has_packages(cache) is False
+ _simulate_case_folding(monkeypatch)
+ assert studio._uv_cache_has_packages(cache) is True
+
+
+def test_a_folded_lookalike_is_still_not_a_bucket(tmp_path, monkeypatch):
+ """Folding must not smuggle in a name that is not uv's either way."""
+ studio = _studio()
+ cache = tmp_path / "shared-uv"
+ (cache / "Archive-V0.backup" / "pkg").mkdir(parents = True)
+ (cache / "Archive-V0.backup" / "pkg" / "torch.whl").write_bytes(b"\0" * 8)
+ # Holds on a folding filesystem and a case-sensitive one alike: the name is not uv's either
+ # way, so the stub only has to make the folding case reachable on ext4.
+ _simulate_case_folding(monkeypatch)
+ assert studio._uv_cache_has_packages(cache) is False
+
+
[email protected]("blank", ["", " ", "\t"])
+def test_no_cache_mode_removes_a_blank_inherited_cache_dir(monkeypatch, tmp_path, caches, blank):
+ """uv parses an exported EMPTY UV_CACHE_DIR as `--cache-dir ''` even under --no-cache, and
+ exits 2 with "a value is required for '--cache-dir'" (measured on uv 0.10.7, both `uv cache
+ dir` and `uv pip install`). setup.sh unsets it in its own no-cache branch; setup.ps1 has no
+ cache handling at all, so on Windows the blank reached uv and failed the update."""
+ studio = _studio()
+ monkeypatch.setenv("UV_CACHE_DIR", blank)
+ monkeypatch.setenv("UV_NO_CACHE", "1")
+ seen = _run_posix(monkeypatch, tmp_path)
+ assert seen["env"] is not None, "inheriting os.environ would keep the blank value"
+ assert "UV_CACHE_DIR" not in seen["env"], seen["env"].get("UV_CACHE_DIR")
+
+
+def test_no_cache_mode_still_leaves_a_real_caller_value_alone(monkeypatch, tmp_path, caches):
+ """--no-cache outranks --cache-dir inside uv; a caller's explicit path is still not ours
+ to strip, and uv accepts the pair."""
+ studio = _studio()
+ chosen = str(tmp_path / "caller cache")
+ monkeypatch.setenv("UV_CACHE_DIR", chosen)
+ monkeypatch.setenv("UV_NO_CACHE", "1")
+ seen = _run_posix(monkeypatch, tmp_path)
+ assert seen["env"] is None or seen["env"]["UV_CACHE_DIR"] == chosen