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: answer slow cache sizes at once and walk cache trees faster (#15627)

Daniel Han78ef9b53f42c
diff --git a/studio/backend/hub/utils/inventory_scan.py b/studio/backend/hub/utils/inventory_scan.py
index 6822ea0f096..5a08e47d060 100644
--- a/studio/backend/hub/utils/inventory_scan.py
+++ b/studio/backend/hub/utils/inventory_scan.py
@@ -100,6 +100,13 @@ def invalidate_hf_cache_scans() -> None:
_hf_cache_scans_cached_at = 0.0
_hf_cache_scans_epoch += 1
invalidate_scan_memos()
+ # Settings may answer a slow cache from its last walk; a download or delete must not show the old size.
+ try:
+ from utils.cache_inventory import invalidate_cache_size
+ for key in ("hf_hub", "hf_xet", "hf_datasets", "hf_assets"):
+ invalidate_cache_size(key)
+ except Exception: # noqa: BLE001 - the Settings sizes are best effort
+ pass
try:
from core.inference.audio_cpp_models import forget
except Exception: # noqa: BLE001 - no audio.cpp support, nothing memoized
diff --git a/studio/backend/tests/test_cache_inventory_walk.py b/studio/backend/tests/test_cache_inventory_walk.py
new file mode 100644
index 00000000000..560218d4540
--- /dev/null
+++ b/studio/backend/tests/test_cache_inventory_walk.py
@@ -0,0 +1,338 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""The cache walk must size exactly what the original per-entry walk sized, and a slow
+cache must not hold the Settings page once it has been measured."""
+
+import os
+import sys
+import threading
+import time
+from pathlib import Path
+from typing import Iterable, Optional
+
+import pytest
+
+from utils import cache_inventory
+from utils.cache_inventory import LinkLedger, definition_for
+
+
+def _reference_measure_tree(path: Path, ledger: LinkLedger) -> int:
+ """The walk as it was before it was tuned, kept here as the oracle."""
+ count = 0
+ stack = [path]
+ while stack:
+ current = stack.pop()
+ try:
+ with os.scandir(current) as entries:
+ for entry in entries:
+ count += 1
+ if entry.is_symlink():
+ continue
+ if entry.is_dir(follow_symlinks = False):
+ if cache_inventory._descendable(entry):
+ stack.append(Path(entry.path))
+ continue
+ cache_inventory._record_entry(entry, ledger)
+ except OSError:
+ continue
+ return count
+
+
+def _reference_measure_root(root: Path, patterns: Optional[Iterable[str]] = None) -> tuple:
+ ledger = LinkLedger()
+ entries = 0
+ try:
+ if root.is_symlink() or cache_inventory._is_junction(root) or not root.is_dir():
+ return 0, 0
+ except OSError:
+ return 0, 0
+ try:
+ with os.scandir(root) as scan:
+ for entry in scan:
+ if not cache_inventory._matching(entry.name, patterns):
+ continue
+ entries += 1
+ if entry.is_symlink():
+ continue
+ if entry.is_dir(follow_symlinks = False):
+ if cache_inventory._descendable(entry):
+ _reference_measure_tree(Path(entry.path), ledger)
+ continue
+ cache_inventory._record_entry(entry, ledger)
+ except OSError:
+ pass
+ return ledger.freeable_bytes(), entries
+
+
+def _blob(path: Path, size: int) -> Path:
+ path.parent.mkdir(parents = True, exist_ok = True)
+ path.write_bytes(b"x" * size)
+ return path
+
+
+def awkward_tree(tmp_path):
+ """Nested dirs, symlinks in and out, hard links in and out, and dirs the walk cannot read."""
+ root = tmp_path / "cache"
+ outside = tmp_path / "outside"
+ _blob(outside / "big.bin", 1 << 20)
+ _blob(root / "top.bin", 11)
+ for archive in range(4):
+ for depth in range(3):
+ nested = (
+ root / "archive-v0" / f"a{archive}" / Path(*[f"d{d}" for d in range(depth + 1)])
+ )
+ _blob(nested / f"f{archive}_{depth}.py", 100 + archive * 10 + depth)
+ os.symlink(outside, root / "archive-v0" / "linked_dir")
+ os.symlink(outside / "big.bin", root / "archive-v0" / "a0" / "linked_file.bin")
+ os.symlink(root / "missing", root / "dangling")
+ # Both links inside: counted once. One link outside: not reclaimable, so not counted.
+ inner = _blob(root / "wheels" / "pkg" / "inner.bin", 5000)
+ os.link(inner, root / "archive-v0" / "a1" / "inner_link.bin")
+ shared = _blob(root / "wheels" / "pkg" / "shared.bin", 7000)
+ os.link(shared, outside / "venv_link.bin")
+ # A three-link inode with two links in two different top-level dirs and one outside.
+ triple = _blob(root / "builds" / "t.bin", 3000)
+ os.link(triple, root / "wheels" / "t_link.bin")
+ os.link(triple, outside / "t_out.bin")
+ # Unlistable, and listable but not searchable.
+ _blob(root / "locked" / "hidden.bin", 900)
+ _blob(root / "noexec" / "child.bin", 800)
+ _blob(root / "archive-v0" / "a2" / "deep_locked" / "deeper" / "x.bin", 700)
+ os.chmod(root / "locked", 0)
+ os.chmod(root / "noexec", 0o600)
+ os.chmod(root / "archive-v0" / "a2" / "deep_locked", 0)
+ yield root
+ for path in (root / "locked", root / "noexec", root / "archive-v0" / "a2" / "deep_locked"):
+ os.chmod(path, 0o755)
+
+
[email protected](sys.platform == "win32", reason = "symlinks and chmod 0 need POSIX semantics")
[email protected]("patterns", [None, ("archive-v0", "wheels"), ("*.bin",)])
+def test_the_walk_sizes_exactly_what_the_reference_walk_sizes(awkward_tree, patterns):
+ expected = _reference_measure_root(awkward_tree, patterns)
+ assert cache_inventory._measure_root(awkward_tree, patterns = patterns) == expected
+ if patterns is None:
+ # Sanity on the oracle itself: the outside-linked and unreadable bytes are not counted.
+ nested = sum(100 + a * 10 + d for a in range(4) for d in range(3))
+ # Root bypasses permission checks (capabilities(7) CAP_DAC_OVERRIDE), so it reads the locked dirs.
+ locked = 900 + 800 + 700 if getattr(os, "geteuid", lambda: -1)() == 0 else 0
+ assert expected == (11 + nested + 5000 + locked, 7)
+
+
[email protected](sys.platform == "win32", reason = "symlinks need POSIX semantics")
+def test_the_tree_walk_counts_entries_like_the_reference(awkward_tree):
+ target = awkward_tree / "archive-v0"
+ reference, tuned = LinkLedger(), LinkLedger()
+ assert cache_inventory._measure_tree(target, tuned) == _reference_measure_tree(
+ target, reference
+ )
+ assert tuned.freeable_bytes() == reference.freeable_bytes()
+
+
+def test_the_walk_matches_the_reference_on_a_portable_tree(tmp_path):
+ """Runs on Windows too, where the awkward tree's symlinks and chmod are unavailable."""
+ root = tmp_path / "cache"
+ outside = tmp_path / "outside"
+ _blob(root / "top.bin", 11)
+ for archive in range(3):
+ _blob(root / f"a{archive}" / "d0" / "d1" / f"f{archive}.py", 100 + archive)
+ inner = _blob(root / "wheels" / "inner.bin", 5000)
+ os.link(inner, root / "a1" / "inner_link.bin")
+ shared = _blob(root / "wheels" / "shared.bin", 7000)
+ _blob(outside / "keep.txt", 1)
+ os.link(shared, outside / "venv_link.bin")
+ for patterns in (None, ("a*",), ("*.bin",)):
+ assert cache_inventory._measure_root(root, patterns = patterns) == _reference_measure_root(
+ root, patterns
+ )
+
+
+def test_a_junction_below_the_top_level_is_still_not_walked(tmp_path, monkeypatch):
+ root = tmp_path / "cache"
+ _blob(root / "a" / "b" / "junction" / "elsewhere.bin", 4096)
+ _blob(root / "a" / "kept.bin", 3)
+ monkeypatch.setattr(cache_inventory, "_is_junction", lambda path: Path(path).name == "junction")
+ assert cache_inventory._measure_root(root) == (3, 1)
+
+
+def clean_memo(monkeypatch):
+ monkeypatch.setattr(cache_inventory, "_size_cache", {})
+ monkeypatch.setattr(cache_inventory, "_size_epochs", {})
+ monkeypatch.setattr(cache_inventory, "_size_flights", {})
+ # A background walk an earlier test left running (a real cache walk under load) must not hold these up.
+ monkeypatch.setattr(cache_inventory, "_background_walk_lock", threading.Lock())
+
+
+def _expire(key: str, *, walk_seconds: float) -> None:
+ begun, _stored, entry, *_rest = cache_inventory._size_cache[key]
+ past = time.monotonic() - cache_inventory._INVENTORY_TTL_SECONDS - 1
+ cache_inventory._size_cache[key] = (past - walk_seconds, past, entry, walk_seconds)
+
+
+def test_an_expired_slow_cache_answers_at_once_and_refreshes_behind(monkeypatch, clean_memo):
+ definition = definition_for("uv")
+ sizes = iter([10, 20])
+ release = threading.Event()
+ walked = threading.Event()
+
+ def describe(target):
+ size = next(sizes)
+ if size == 20:
+ walked.set()
+ release.wait(10)
+ return {"key": target.key, "size_bytes": size}
+
+ monkeypatch.setattr(cache_inventory, "describe_cache", describe)
+ assert cache_inventory._described(definition, refresh = False)["size_bytes"] == 10
+ _expire("uv", walk_seconds = cache_inventory._BACKGROUND_WALK_SECONDS + 5)
+
+ started = time.monotonic()
+ assert cache_inventory._described(definition, refresh = False)["size_bytes"] == 10
+ assert time.monotonic() - started < 1.0
+ assert walked.wait(5), "no background walk was started"
+ # A second read while that walk runs neither waits nor starts another.
+ assert cache_inventory._described(definition, refresh = False)["size_bytes"] == 10
+ release.set()
+ for _ in range(100):
+ if cache_inventory._size_cache["uv"][2]["size_bytes"] == 20:
+ break
+ time.sleep(0.05)
+ assert cache_inventory._described(definition, refresh = False)["size_bytes"] == 20
+
+
+def test_a_studio_download_or_delete_is_never_answered_from_the_older_walk(monkeypatch, clean_memo):
+ """Downloads and deletes call invalidate_hf_cache_scans; Settings must then walk, as base did after the TTL."""
+ from hub.utils.inventory_scan import invalidate_hf_cache_scans
+ for key in ("hf_hub", "hf_xet", "hf_datasets", "hf_assets"):
+ definition = definition_for(key)
+ sizes = iter([100, 999])
+ monkeypatch.setattr(
+ cache_inventory,
+ "describe_cache",
+ lambda target, sizes = sizes: {"key": target.key, "size_bytes": next(sizes)},
+ )
+ assert cache_inventory._described(definition, refresh = False)["size_bytes"] == 100
+ _expire(key, walk_seconds = cache_inventory._BACKGROUND_WALK_SECONDS + 5)
+ invalidate_hf_cache_scans()
+ assert cache_inventory._described(definition, refresh = False)["size_bytes"] == 999, key
+
+
+def test_an_expired_quick_cache_is_still_walked_in_the_request(monkeypatch, clean_memo):
+ definition = definition_for("pip")
+ sizes = iter([10, 20])
+ monkeypatch.setattr(
+ cache_inventory,
+ "describe_cache",
+ lambda target: {"key": target.key, "size_bytes": next(sizes)},
+ )
+ assert cache_inventory._described(definition, refresh = False)["size_bytes"] == 10
+ _expire("pip", walk_seconds = 0.01)
+ assert cache_inventory._described(definition, refresh = False)["size_bytes"] == 20
+
+
+def test_recheck_waits_for_a_fresh_walk_even_for_a_slow_cache(monkeypatch, clean_memo):
+ definition = definition_for("triton")
+ sizes = iter([10, 20])
+ monkeypatch.setattr(
+ cache_inventory,
+ "describe_cache",
+ lambda target: {"key": target.key, "size_bytes": next(sizes)},
+ )
+ assert cache_inventory._described(definition, refresh = False)["size_bytes"] == 10
+ _expire("triton", walk_seconds = 60)
+ assert cache_inventory._described(definition, refresh = True)["size_bytes"] == 20
+
+
+def test_a_background_walk_overtaken_by_a_purge_does_not_store_its_size(monkeypatch, clean_memo):
+ definition = definition_for("uv")
+ sizes = iter([10, 20, 0])
+ walked = threading.Event()
+ release = threading.Event()
+
+ def describe(target):
+ size = next(sizes)
+ if size == 20:
+ walked.set()
+ release.wait(10)
+ return {"key": target.key, "size_bytes": size}
+
+ monkeypatch.setattr(cache_inventory, "describe_cache", describe)
+ cache_inventory._described(definition, refresh = False)
+ _expire("uv", walk_seconds = 30)
+ assert cache_inventory._described(definition, refresh = False)["size_bytes"] == 10
+ assert walked.wait(5)
+ cache_inventory.invalidate_cache_size("uv")
+ release.set()
+ # The purge's own read waits for the stale walk, then walks again rather than keep 20.
+ assert cache_inventory._described(definition, refresh = False)["size_bytes"] == 0
+
+
+def test_background_walks_run_one_at_a_time(monkeypatch, clean_memo):
+ running: list = []
+ peak: list = []
+ lock = threading.Lock()
+ first_pass = {"uv": True, "triton": True}
+
+ def describe(target):
+ if first_pass.pop(target.key, False):
+ return {"key": target.key, "size_bytes": 1}
+ with lock:
+ running.append(target.key)
+ peak.append(len(running))
+ time.sleep(0.2)
+ with lock:
+ running.remove(target.key)
+ return {"key": target.key, "size_bytes": 2}
+
+ monkeypatch.setattr(cache_inventory, "describe_cache", describe)
+ for key in ("uv", "triton"):
+ cache_inventory._described(definition_for(key), refresh = False)
+ _expire(key, walk_seconds = 30)
+ for key in ("uv", "triton"):
+ assert cache_inventory._described(definition_for(key), refresh = False)["size_bytes"] == 1
+ for _ in range(100):
+ if all(cache_inventory._size_cache[key][2]["size_bytes"] == 2 for key in ("uv", "triton")):
+ break
+ time.sleep(0.05)
+ assert peak == [1, 1]
+
+
+def test_the_inventory_starts_background_walks_after_its_own(monkeypatch, clean_memo):
+ order: list = []
+ real_refresh = cache_inventory._refresh_in_background
+ monkeypatch.setattr(
+ cache_inventory,
+ "describe_cache",
+ lambda target: (
+ order.append(("walk", target.key)),
+ {
+ "key": target.key,
+ "size_bytes": 1,
+ "present": False,
+ "purgeable": False,
+ "opt_in": False,
+ },
+ )[1],
+ )
+ monkeypatch.setattr(cache_inventory, "_free_bytes", lambda: None)
+ monkeypatch.setattr(cache_inventory, "_total_disk_bytes", lambda: None)
+ cache_inventory.cache_inventory()
+ for definition in cache_inventory.CACHE_DEFINITIONS:
+ _expire(definition.key, walk_seconds = 30 if definition.key == "uv" else 0.01)
+ order.clear()
+ monkeypatch.setattr(
+ cache_inventory,
+ "_refresh_in_background",
+ lambda definition: (order.append(("background", definition.key)), real_refresh(definition)),
+ )
+ cache_inventory.cache_inventory()
+ for _ in range(100):
+ if ("walk", "uv") in order:
+ break
+ time.sleep(0.05)
+ foreground = [key for kind, key in order if kind == "walk" and key != "uv"]
+ assert len(foreground) == len(cache_inventory.CACHE_DEFINITIONS) - 1
+ assert order.index(("background", "uv")) == len(foreground)
diff --git a/studio/backend/utils/cache_inventory.py b/studio/backend/utils/cache_inventory.py
index 803ab1c041a..9b684664b38 100644
--- a/studio/backend/utils/cache_inventory.py
+++ b/studio/backend/utils/cache_inventory.py
@@ -711,6 +711,9 @@ class LinkLedger:
else:
record[2] += 1
+ def add_single_link_bytes(self, size: int) -> None:
+ self._single += size
+
def freeable_bytes(self) -> int:
return self._single + sum(size for size, links, met in self._multi.values() if met >= links)
@@ -728,28 +731,50 @@ def _descendable(entry: os.DirEntry) -> bool:
return not _is_junction(entry.path)
-def _measure_tree(path: Path, ledger: LinkLedger) -> int:
- """Size is left to the ledger: a multi-link inode's cost is only known after every root is walked."""
+def _walk_into(stack: list, ledger: LinkLedger) -> int:
+ """Sizes every directory on the stack and below it; returns the entries seen.
+
+ A uv or triton cache can hold millions of files, so the loop body is the whole cost: paths
+ stay strings and single-link sizes are summed locally rather than through the ledger.
+ """
count = 0
- stack = [path]
- while stack:
- current = stack.pop()
- try:
- with os.scandir(current) as entries:
- for entry in entries:
- count += 1
- if entry.is_symlink():
- continue
- if entry.is_dir(follow_symlinks = False):
- if _descendable(entry):
- stack.append(Path(entry.path))
- continue
- _record_entry(entry, ledger)
- except OSError:
- continue
+ single = 0
+ add = ledger.add
+ pop = stack.pop
+ push = stack.append
+ try:
+ while stack:
+ current = pop()
+ try:
+ with os.scandir(current) as entries:
+ for entry in entries:
+ count += 1
+ if entry.is_symlink():
+ continue
+ if entry.is_dir(follow_symlinks = False):
+ if _descendable(entry):
+ push(entry.path)
+ continue
+ try:
+ found = entry.stat(follow_symlinks = False)
+ except OSError:
+ continue
+ if found.st_nlink <= 1:
+ single += found.st_size
+ else:
+ add(found)
+ except OSError:
+ continue
+ finally:
+ ledger.add_single_link_bytes(single)
return count
+def _measure_tree(path: Path, ledger: LinkLedger) -> int:
+ """Size is left to the ledger: a multi-link inode's cost is only known after every root is walked."""
+ return _walk_into([os.fspath(path)], ledger)
+
+
def _measure_root(root: Path, *, patterns: Optional[Iterable[str]] = None) -> tuple[int, int]:
ledger = LinkLedger()
entries = 0
@@ -758,6 +783,8 @@ def _measure_root(root: Path, *, patterns: Optional[Iterable[str]] = None) -> tu
return 0, 0
except OSError:
return 0, 0
+ # Subdirectories are walked after the listing, in one loop, so they are still sized when it fails part way.
+ subdirs: list = []
try:
with os.scandir(root) as scan:
for entry in scan:
@@ -768,11 +795,13 @@ def _measure_root(root: Path, *, patterns: Optional[Iterable[str]] = None) -> tu
continue
if entry.is_dir(follow_symlinks = False):
if _descendable(entry):
- _measure_tree(Path(entry.path), ledger)
+ subdirs.append(entry.path)
continue
_record_entry(entry, ledger)
except OSError as exc:
logger.debug(f"Could not size {root}: {exc}")
+ subdirs.reverse()
+ _walk_into(subdirs, ledger)
return ledger.freeable_bytes(), entries
@@ -865,8 +894,10 @@ def _patterns_for(definition: CacheDefinition) -> Optional[tuple[str, ...]]:
# Walks take seconds on large uv/triton caches, so repeat reads within the TTL reuse the last answer.
_INVENTORY_TTL_SECONDS = 60.0
-# Tuple of (walk start, store time, entry): TTL uses store time, forced reads compare walk start.
-_size_cache: dict[str, tuple[float, float, dict]] = {}
+# Past the TTL, a cache whose last walk took this long answers from it and re-walks in the background.
+_BACKGROUND_WALK_SECONDS = 2.0
+# Tuple of (walk start, store time, entry, walk seconds): TTL uses store time, forced reads compare walk start.
+_size_cache: dict[str, tuple[float, float, dict, float]] = {}
# Bumped per invalidation so a walk begun earlier cannot store a stale size.
_size_epochs: dict[str, int] = {}
_size_cache_lock = threading.Lock()
@@ -880,6 +911,8 @@ def invalidate_cache_size(key: str) -> None:
_size_flights: dict[str, threading.Lock] = {}
_size_flights_lock = threading.Lock()
+# Background walks run one at a time: two stat-bound walks in one process only trade the GIL.
+_background_walk_lock = threading.Lock()
def _flight_for(key: str) -> threading.Lock:
@@ -887,12 +920,61 @@ def _flight_for(key: str) -> threading.Lock:
return _size_flights.setdefault(key, threading.Lock())
-def _described(definition: CacheDefinition, *, refresh: bool) -> dict:
+def _walk_and_remember(definition: CacheDefinition, epoch: int) -> dict:
+ """Caller holds the key's flight; an invalidation since ``epoch`` keeps the answer out of the memo."""
+ begun = time.monotonic()
+ entry = describe_cache(definition)
+ finished = time.monotonic()
+ with _size_cache_lock:
+ if _size_epochs.get(definition.key, 0) == epoch:
+ _size_cache[definition.key] = (begun, finished, entry, finished - begun)
+ return entry
+
+
+def _refresh_in_background(definition: CacheDefinition) -> None:
+ """At most one walk per cache: one already running, foreground or not, stores the newer size anyway."""
+ flight = _flight_for(definition.key)
+ if not flight.acquire(blocking = False):
+ return
+
+ def walk() -> None:
+ try:
+ with _background_walk_lock:
+ with _size_cache_lock:
+ epoch = _size_epochs.get(definition.key, 0)
+ _walk_and_remember(definition, epoch)
+ except Exception as exc: # noqa: BLE001 - a failed refresh leaves the last size in place
+ logger.debug(f"Could not refresh the {definition.key} cache size: {exc}")
+ finally:
+ flight.release()
+
+ try:
+ threading.Thread(target = walk, name = f"cache-size-{definition.key}", daemon = True).start()
+ except Exception as exc: # noqa: BLE001 - e.g. no thread left; the next read walks in the foreground
+ flight.release()
+ logger.debug(f"Could not start a {definition.key} cache size refresh: {exc}")
+
+
+def _described(
+ definition: CacheDefinition,
+ *,
+ refresh: bool,
+ deferred: Optional[list] = None,
+) -> dict:
+ """``deferred`` collects the background refreshes for the caller to start, after its own walks."""
started = time.monotonic()
with _size_cache_lock:
remembered = None if refresh else _size_cache.get(definition.key)
- if remembered is not None and started - remembered[1] < _INVENTORY_TTL_SECONDS:
- return remembered[2]
+ if remembered is not None:
+ if started - remembered[1] < _INVENTORY_TTL_SECONDS:
+ return remembered[2]
+ # A forced read (the Recheck button) still waits for a fresh walk below.
+ if remembered[3] >= _BACKGROUND_WALK_SECONDS:
+ if deferred is None:
+ _refresh_in_background(definition)
+ else:
+ deferred.append(definition)
+ return remembered[2]
# One walk per cache at a time, or simultaneous misses (e.g. two open tabs) each pay a cold walk.
with _flight_for(definition.key):
with _size_cache_lock:
@@ -905,16 +987,18 @@ def _described(definition: CacheDefinition, *, refresh: bool) -> dict:
return remembered[2]
elif time.monotonic() - remembered[1] < _INVENTORY_TTL_SECONDS:
return remembered[2]
- begun = time.monotonic()
- entry = describe_cache(definition)
- with _size_cache_lock:
- if _size_epochs.get(definition.key, 0) == epoch:
- _size_cache[definition.key] = (begun, time.monotonic(), entry)
- return entry
+ return _walk_and_remember(definition, epoch)
def cache_inventory(*, refresh: bool = False) -> dict:
- entries = [_described(definition, refresh = refresh) for definition in CACHE_DEFINITIONS]
+ # Started after the foreground walks, which would otherwise share the GIL with them.
+ deferred: list = []
+ entries = [
+ _described(definition, refresh = refresh, deferred = deferred)
+ for definition in CACHE_DEFINITIONS
+ ]
+ for definition in deferred:
+ _refresh_in_background(definition)
total = sum(entry["size_bytes"] for entry in entries if entry["present"])
reclaimable = sum(
entry["size_bytes"]