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: keep a nested active HF hub clearable and listed (#16215)

Daniel Han781f00401eb8
diff --git a/studio/backend/tests/test_cache_inventory.py b/studio/backend/tests/test_cache_inventory.py
index 994ebb96116..7a34cd8f20e 100644
--- a/studio/backend/tests/test_cache_inventory.py
+++ b/studio/backend/tests/test_cache_inventory.py
@@ -1,7 +1,6 @@
# SPDX-License-Identifier: AGPL-3.0-only
# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
-"""Only caches this backend resolved itself may be deleted; a purge key becomes a directory here."""
import os
import sys
@@ -30,7 +29,7 @@ def _write(path: Path, text: str = "x") -> Path:
@pytest.fixture
def isolated_caches(tmp_path, monkeypatch):
- """Point every resolver at tmp_path; the host's real HF_HOME and XDG_CACHE_HOME must not leak in."""
+ "Isolate every cache resolver from host data."
from utils import cache_cleanup, hf_cache_settings
hf_home = tmp_path / "hf"
@@ -131,7 +130,6 @@ def test_a_root_at_or_near_the_filesystem_root_is_refused(raw):
def test_a_shallow_root_is_refused_even_when_nothing_protects_it(tmp_path):
- # The depth rule alone stops a variable pointed one level down from an rmtree of its contents.
shallow = Path(*tmp_path.parts[:2])
if not shallow.is_dir() or shallow.is_symlink() or len(shallow.parts) != 2:
pytest.skip(f"no shallow non-symlink directory to test with ({shallow})")
@@ -275,9 +273,7 @@ def test_a_refused_root_reports_itself_and_deletes_nothing(tmp_path, monkeypatch
@pytest.fixture
def only_the_configured_compiled_cache(monkeypatch, tmp_path):
- """Clear must not touch install-tree caches; tests chdir to an empty dir, as unsloth fills CWD."""
from utils import cache_cleanup
-
monkeypatch.setattr(cache_cleanup, "_CACHE_DIRS", [])
monkeypatch.chdir(tmp_path)
@@ -345,8 +341,6 @@ def test_a_purge_forgets_the_size_it_measured_before_it(tmp_path, isolated_cache
def test_the_compiled_cache_is_never_swept_up_by_a_bulk_purge():
- """A bulk purge may cost a recompile or a re-download, not a running job: a
- worker imports generated modules from here long after it started."""
definition = definition_for("unsloth_compiled")
assert definition.opt_in is True
@@ -363,8 +357,6 @@ def test_the_compiled_cache_is_never_swept_up_by_a_bulk_purge():
def test_a_junctioned_cache_root_is_refused_like_a_symlink(tmp_path, monkeypatch):
- """Only IO_REPARSE_TAG_SYMLINK sets S_IFLNK, so is_symlink() is False for a
- junction while realpath() follows it and the TARGET would be emptied."""
target = tmp_path / "somewhere" / "deep"
target.mkdir(parents = True)
kept = _write(target / "not-a-cache.txt", "mine")
@@ -384,7 +376,6 @@ def test_a_junctioned_cache_root_is_refused_like_a_symlink(tmp_path, monkeypatch
def test_a_bulk_clear_cannot_reach_an_opt_in_cache_nested_in_another_root(
tmp_path, monkeypatch, isolated_caches
):
- """HF_DATASETS_CACHE below UV_CACHE_DIR would otherwise go with the outer root."""
uv = tmp_path / "uv"
datasets = uv / "hf-datasets"
_write(uv / "wheels" / "wheel.whl", "w" * 10)
@@ -406,8 +397,6 @@ def test_a_bulk_clear_cannot_reach_an_opt_in_cache_nested_in_another_root(
def test_an_explicit_hub_cache_outside_a_hub_folder_stays_clearable(
tmp_path, monkeypatch, isolated_caches
):
- """HF_HUB_CACHE=/mnt/hf-cache makes the DISPLAY home the hub itself, and
- protecting it there guards no credential: the token lives in the HF home."""
from utils import hf_cache_settings
hub = tmp_path / "hf-cache"
@@ -425,10 +414,109 @@ def test_an_explicit_hub_cache_outside_a_hub_folder_stays_clearable(
assert_purgeable_root(isolated_caches)
[email protected]("shared_blob", [False, True])
+def test_an_active_hub_nested_in_a_remembered_hub_stays_clearable(
+ tmp_path, monkeypatch, isolated_caches, shared_blob
+):
+ from utils import hf_cache_settings
+
+ old_hub = isolated_caches / "hub"
+ active = old_hub / "new-downloads"
+ old_blob = _write(old_hub / "models--test--old" / "blobs" / "weights", "o" * 256)
+ active_blob = _write(active / "models--test--active" / "blobs" / "weights", "a" * 128)
+ if shared_blob:
+ os.link(active_blob, old_blob.parent / "shared")
+ paths = hf_cache_settings.HuggingFaceCachePaths(
+ active, active, isolated_caches / "xet", "environment", "HF_HUB_CACHE"
+ )
+ monkeypatch.setattr(hf_cache_settings, "get_hf_cache_paths", lambda: paths)
+ monkeypatch.setattr(hf_cache_settings, "known_hf_hub_caches", lambda: [active, old_hub])
+
+ described = describe_cache(definition_for("hf_hub"))
+ assert described["purgeable"] is True, described["blocked_reason"]
+ assert described["size_bytes"] == 384
+ assert described["clear_size_bytes"] == (0 if shared_blob else 128)
+ assert described["clear_entry_count"] == 1
+
+ rows = {row["name"]: row for row in cache_inventory.cache_breakdown("hf_hub")["entries"]}
+ assert set(rows) == {"models--test--old", "models--test--active"}
+ assert rows["models--test--active"]["size_bytes"] == 128
+ assert rows["models--test--active"]["cache_path"] == str(
+ (active / "models--test--active").resolve()
+ )
+
+ purge_caches(["hf_hub"])
+ assert not active_blob.exists()
+ assert old_blob.exists()
+
+
[email protected]("depth", [1, 3])
+def test_a_nested_hub_breakdown_walks_each_active_directory_once(
+ monkeypatch, isolated_caches, depth
+):
+ from utils import hf_cache_settings
+
+ old_hub = isolated_caches / "hub"
+ active = old_hub.joinpath(*(["nested"] * depth))
+ blob = _write(active / "models--test--active" / "blobs" / "weights", "a" * 128)
+ paths = hf_cache_settings.HuggingFaceCachePaths(
+ active, active, isolated_caches / "xet", "environment", "HF_HUB_CACHE"
+ )
+ monkeypatch.setattr(hf_cache_settings, "get_hf_cache_paths", lambda: paths)
+ monkeypatch.setattr(hf_cache_settings, "known_hf_hub_caches", lambda: [active, old_hub])
+ scandir = os.scandir
+ visits = []
+
+ def tracked_scandir(path):
+ visits.append(Path(path))
+ return scandir(path)
+
+ monkeypatch.setattr(cache_inventory.os, "scandir", tracked_scandir)
+ rows = cache_inventory.cache_breakdown("hf_hub")["entries"]
+ assert visits.count(blob.parent) == 1
+ assert sum(row["size_bytes"] for row in rows) == 128
+ assert any(row.get("repo_id") == "test/active" for row in rows)
+
+
+def test_a_growing_nested_hub_does_not_offer_more_bytes_than_it_measured(
+ monkeypatch, isolated_caches
+):
+ from utils import hf_cache_settings
+
+ old_hub = isolated_caches / "hub"
+ active = old_hub / "new-downloads"
+ _write(old_hub / "models--test--old" / "blobs" / "weights", "o" * 256)
+ active_blob = _write(active / "models--test--active" / "blobs" / "weights", "a" * 128)
+ paths = hf_cache_settings.HuggingFaceCachePaths(
+ active, active, isolated_caches / "xet", "environment", "HF_HUB_CACHE"
+ )
+ monkeypatch.setattr(hf_cache_settings, "get_hf_cache_paths", lambda: paths)
+ monkeypatch.setattr(hf_cache_settings, "known_hf_hub_caches", lambda: [active, old_hub])
+ measure = cache_inventory._measure_root
+ scandir = os.scandir
+ visits = []
+
+ def tracked_scandir(path):
+ visits.append(Path(path))
+ return scandir(path)
+
+ def grow_after_measure(root, **kwargs):
+ result = measure(root, **kwargs)
+ if root == old_hub:
+ active_blob.write_text("a" * 1024, encoding = "utf-8")
+ return result
+
+ monkeypatch.setattr(cache_inventory, "_measure_root", grow_after_measure)
+ monkeypatch.setattr(cache_inventory.os, "scandir", tracked_scandir)
+ described = describe_cache(definition_for("hf_hub"))
+ assert described["size_bytes"] == 384
+ assert described["clear_size_bytes"] == 128
+ assert visits.count(active_blob.parent) == 1
+
+
def test_the_inductor_cache_follows_the_account_name_torch_uses(
tmp_path, monkeypatch, isolated_caches
):
- """A container with no USER puts torch's cache at torchinductor_root, not _0."""
import tempfile
monkeypatch.delenv("TORCHINDUCTOR_CACHE_DIR", raising = False)
@@ -448,8 +536,6 @@ def test_the_inductor_cache_follows_the_account_name_torch_uses(
def test_the_vllm_cache_is_vllms_own_default_on_every_platform(
tmp_path, monkeypatch, isolated_caches, platform
):
- """vllm/envs.py is XDG_CACHE_HOME or ~/.cache then "vllm", which the platform
- convention matches on Linux only."""
import sys as _sys
monkeypatch.delenv("VLLM_CACHE_ROOT", raising = False)
@@ -465,7 +551,6 @@ def test_the_vllm_cache_honours_xdg_because_vllm_does(tmp_path, monkeypatch, iso
def test_a_refused_root_is_never_walked(tmp_path, monkeypatch, isolated_caches):
- """Or the Resources tab measures it recursively on every open."""
outputs = tmp_path / "outputs"
monkeypatch.setattr(
cache_inventory, "protected_trees", lambda: {Path(os.path.realpath(outputs))}
@@ -490,8 +575,6 @@ def test_a_refused_root_is_never_walked(tmp_path, monkeypatch, isolated_caches):
def test_a_cache_anywhere_under_the_documents_folder_is_refused(
tmp_path, monkeypatch, isolated_caches
):
- """A protected TREE, not only a protected path: an inherited
- UV_CACHE_DIR=~/Documents/archive would otherwise be reported purgeable."""
from utils.paths import storage_roots
documents = tmp_path / "Documents"
@@ -507,8 +590,6 @@ def test_a_cache_anywhere_under_the_documents_folder_is_refused(
def test_a_junction_inside_a_cache_is_not_walked(tmp_path, monkeypatch, isolated_caches):
- """is_dir() sees a directory and is_symlink() no link, so descending sizes the
- junction's target, and one pointing at an ancestor never terminates."""
root = tmp_path / "uv"
_write(root / "real.bin", "r" * 10)
_write(root / "wheels" / "junction" / "elsewhere.bin", "z" * 4096)
@@ -521,8 +602,6 @@ def test_a_junction_inside_a_cache_is_not_walked(tmp_path, monkeypatch, isolated
def test_a_compiled_cache_that_survives_the_clear_says_so(
tmp_path, monkeypatch, only_the_configured_compiled_cache
):
- """cache_cleanup swallows every failure, so a read-only directory looked
- identical to a clean clear and the UI said so."""
from utils import cache_cleanup
compiled = tmp_path / "compiled_cache"
@@ -539,7 +618,6 @@ def test_a_compiled_cache_that_survives_the_clear_says_so(
def test_purging_a_hub_cache_invalidates_the_hugging_face_scans(tmp_path, isolated_caches):
- """Or the picker keeps listing deleted models for the scan's TTL."""
from hub.utils import inventory_scan
_write(isolated_caches / "hub" / "models--org--model" / "blob", "m" * 10)
@@ -556,8 +634,6 @@ def test_purging_a_hub_cache_invalidates_the_hugging_face_scans(tmp_path, isolat
def test_a_pattern_limited_cache_nested_in_another_root_is_sheltered(
tmp_path, monkeypatch, isolated_caches
):
- """MPLCONFIGDIR keeps matplotlibrc, which is why its own clear is
- pattern-limited, so an outer root must not take it whole."""
uv = tmp_path / "uv"
config = uv / "matplotlib"
_write(uv / "wheels" / "wheel.whl", "w" * 10)
@@ -580,8 +656,6 @@ def test_a_pattern_limited_cache_nested_in_another_root_is_sheltered(
def test_a_cache_home_left_behind_is_protected_but_never_purged(
tmp_path, monkeypatch, isolated_caches
):
- """An API key may append to that history through an endpoint the purge route
- itself refuses, so only the ACTIVE home is a purge root."""
from utils import hf_cache_settings
previous = tmp_path / "old-home"
@@ -613,7 +687,6 @@ def test_a_cache_home_left_behind_is_protected_but_never_purged(
def test_the_pip_cache_is_the_one_pip_reports(tmp_path, monkeypatch, isolated_caches):
- """pip.conf moves the cache and Studio's pip calls do not pass --isolated."""
import subprocess as real_subprocess
from utils import cache_inventory as module
@@ -655,8 +728,6 @@ def test_the_pip_probe_runs_once_and_survives_a_failure(tmp_path, monkeypatch, i
def test_the_child_caches_follow_the_real_home_not_the_displayed_one(
tmp_path, monkeypatch, isolated_caches
):
- """An explicit HF_HUB_CACHE makes cache_home the hub's PARENT, so the display
- home misses the real assets and datasets and offers somebody else's."""
from utils import hf_cache_settings
project = tmp_path / "project"
@@ -684,7 +755,6 @@ def test_the_child_caches_follow_the_real_home_not_the_displayed_one(
def test_a_measurement_that_began_before_a_purge_is_not_remembered(
tmp_path, monkeypatch, isolated_caches
):
- """Or it offers space already gone for the rest of the memo window."""
root = tmp_path / "uv"
_write(root / "wheel.whl", "w" * 100)
definition = definition_for("uv")
@@ -705,8 +775,6 @@ def test_a_measurement_that_began_before_a_purge_is_not_remembered(
def test_the_pip_probe_asks_the_child_for_utf8(tmp_path, monkeypatch, isolated_caches):
- """A redirected child takes the locale encoding, so a non-ASCII cache path
- comes back mangled and resolves to nothing."""
import subprocess as real_subprocess
from utils import cache_inventory as module
@@ -732,8 +800,6 @@ def test_the_pip_probe_asks_the_child_for_utf8(tmp_path, monkeypatch, isolated_c
def test_a_scoped_dataset_fallback_override_is_not_a_purge_root(
tmp_path, monkeypatch, isolated_caches
):
- """cache_safe points HF_DATASETS_CACHE there mid-load, in this process, while
- load_dataset writes Arrow files and lock state into it."""
from utils.paths import storage_roots
studio_cache = tmp_path / "studio-cache"
@@ -762,8 +828,6 @@ def test_a_scoped_dataset_fallback_override_is_not_a_purge_root(
def test_the_matplotlib_cache_is_where_matplotlib_puts_it(
tmp_path, monkeypatch, isolated_caches, platform, name, expected, patterned
):
- """get_cachedir takes the XDG branch for linux and freebsd only; elsewhere it
- is ~/.matplotlib, which is get_configdir() too, so only cache entries go."""
import sys as _sys
from utils import cache_inventory as module
@@ -779,7 +843,6 @@ def test_the_matplotlib_cache_is_where_matplotlib_puts_it(
def test_the_cuda_cache_is_roaming_appdata_on_windows(tmp_path, monkeypatch, isolated_caches):
- """The CUDA guide's default is %APPDATA%, which is Roaming, not Local."""
import sys as _sys
from utils import cache_inventory as module
@@ -798,8 +861,6 @@ def test_the_cuda_cache_is_roaming_appdata_on_windows(tmp_path, monkeypatch, iso
def test_numbas_user_wide_fallback_cache_is_reported(tmp_path, monkeypatch, isolated_caches):
- """__pycache__ next to the source is not ours, but UserWideCacheLocator's
- AppDirs("numba", appauthor = False).user_cache_dir is."""
monkeypatch.delenv("NUMBA_CACHE_DIR", raising = False)
root = tmp_path / "xdg" / "numba"
_write(root / "somemodule.nbi", "n" * 30)
@@ -810,8 +871,6 @@ def test_numbas_user_wide_fallback_cache_is_reported(tmp_path, monkeypatch, isol
def test_the_studio_executables_directory_is_refused(tmp_path, monkeypatch, isolated_caches):
- """Descendants of the studio home are deliberately allowed, since the caches
- live there, so the shim and the managed executables need naming."""
from utils.paths import storage_roots
studio = tmp_path / "studio"
@@ -832,7 +891,6 @@ def test_the_studio_executables_directory_is_refused(tmp_path, monkeypatch, isol
def test_the_npm_cache_follows_npmrc(tmp_path, monkeypatch, isolated_caches):
- """No environment variable carries it, and the backend launches npm for MCP."""
import shutil as real_shutil
import subprocess as real_subprocess
@@ -856,7 +914,6 @@ def test_the_npm_cache_follows_npmrc(tmp_path, monkeypatch, isolated_caches):
def test_a_probe_that_answers_with_a_relative_path_is_ignored(monkeypatch, isolated_caches):
- """npm prints "undefined" rather than failing when it has no answer."""
import subprocess as real_subprocess
from utils import cache_inventory as module
@@ -871,8 +928,6 @@ def test_a_probe_that_answers_with_a_relative_path_is_ignored(monkeypatch, isola
def test_the_recorded_install_uv_cache_is_reported(tmp_path, monkeypatch, isolated_caches):
- """The seeded UV_CACHE_DIR is not always the one updates fill: an installer
- that used a warm cache elsewhere records it, and the CLI obeys the record."""
from utils.paths import storage_roots
studio_cache = tmp_path / "studio-cache"
@@ -905,7 +960,6 @@ def test_a_blank_or_missing_uv_marker_adds_nothing(tmp_path, monkeypatch, isolat
def test_the_studio_temporary_workspace_is_refused(tmp_path, monkeypatch, isolated_caches):
- """tmp_root() is not a cache: decoding and training read files back from it."""
from utils.paths import storage_roots
workspace = tmp_path / "unsloth-studio"
@@ -922,8 +976,6 @@ def test_the_studio_temporary_workspace_is_refused(tmp_path, monkeypatch, isolat
def test_two_cold_probes_do_not_race_into_the_fallback(tmp_path, monkeypatch, isolated_caches):
- """Recording the miss before the probe finished had the second cold request
- read it as a finished failure and show the fallback path."""
import subprocess as real_subprocess
import threading
@@ -956,8 +1008,6 @@ def test_two_cold_probes_do_not_race_into_the_fallback(tmp_path, monkeypatch, is
def test_the_inductor_row_ignores_the_diffusion_override(tmp_path, monkeypatch, isolated_caches):
- """begin() repoints TORCHINDUCTOR_CACHE_DIR while a model is resident and
- restore() puts it back, so a row that followed it and the clear disagree."""
import getpass
import tempfile
@@ -986,8 +1036,6 @@ def test_the_inductor_row_ignores_the_diffusion_override(tmp_path, monkeypatch,
def test_a_configured_token_path_is_protected(tmp_path, monkeypatch, isolated_caches):
- """HF_TOKEN_PATH is read instead of <home>/token and can name a file inside a
- clearable cache."""
assets = tmp_path / "mnt-hf"
token = _write(assets / "token", "hf_secret")
_write(assets / "blob", "a" * 10)
@@ -1003,8 +1051,6 @@ def test_a_configured_token_path_is_protected(tmp_path, monkeypatch, isolated_ca
def test_a_purge_waits_for_the_downloads_writing_into_the_cache(
tmp_path, monkeypatch, isolated_caches
):
- """A download writes blobs, locks and partials straight into the hub cache,
- which is why the per-repository deletes refuse for this reason too."""
from utils import cache_inventory as module
blob = _write(isolated_caches / "hub" / "models--org--model" / "blob", "m" * 10)
@@ -1020,8 +1066,6 @@ def test_a_purge_waits_for_the_downloads_writing_into_the_cache(
def test_the_hub_cache_is_reserved_in_both_registries(monkeypatch):
- """A dataset download snapshot_downloads its datasets-- entries into the same
- hub root, so a job in either registry has to hold the purge off."""
from hub.utils import download_registry
from utils import cache_inventory as module
@@ -1041,7 +1085,6 @@ def test_the_hub_cache_is_reserved_in_both_registries(monkeypatch):
models, datasets = _Registry(), _Registry()
monkeypatch.setattr(download_registry, "get_models_registry", lambda: models)
- # The purge reserves datasets through the service, so stub it there.
monkeypatch.setattr(download_registry, "get_datasets_registry", lambda: datasets)
from hub.services.datasets import downloads as dataset_downloads
@@ -1065,7 +1108,6 @@ def test_the_hub_cache_is_reserved_in_both_registries(monkeypatch):
def test_one_blocked_root_does_not_put_the_others_out_of_reach(
tmp_path, monkeypatch, isolated_caches
):
- """purge_cache skips a refused root and carries on, so the row has to say so."""
from utils.paths import storage_roots
studio_cache = tmp_path / "studio-cache"
@@ -1089,7 +1131,6 @@ def test_one_blocked_root_does_not_put_the_others_out_of_reach(
def test_two_cold_reads_of_one_cache_walk_it_once(tmp_path, monkeypatch, isolated_caches):
- """Simultaneous misses would each pay a cold walk for the same answer."""
import threading
from utils import cache_inventory as module
@@ -1129,8 +1170,6 @@ def test_two_cold_reads_of_one_cache_walk_it_once(tmp_path, monkeypatch, isolate
def test_a_forced_read_does_not_take_a_walk_that_began_before_it(
tmp_path, monkeypatch, isolated_caches
):
- """Recheck asks for a fresh look, and a walk already running when the request
- arrived read the cache before whatever the user changed."""
import threading
from utils import cache_inventory as module
@@ -1174,8 +1213,6 @@ def test_a_forced_read_does_not_take_a_walk_that_began_before_it(
def test_the_child_caches_ignore_a_studio_selected_models_folder(
tmp_path, monkeypatch, isolated_caches
):
- """It moves the hub and xet caches, not HF_HOME, so the token, assets and
- datasets stay at the platform default."""
from utils import hf_cache_settings
chosen = tmp_path / "MyModels"
@@ -1199,7 +1236,6 @@ def test_the_child_caches_ignore_a_studio_selected_models_folder(
def test_the_npx_cache_is_cleared_with_the_package_cache(tmp_path, monkeypatch, isolated_caches):
- """<cache>/_npx is npm's cache as much as _cacache is; the logs are not."""
npm = tmp_path / "npm"
package = _write(npm / "_cacache" / "index-v5" / "entry", "c" * 20)
executable = _write(npm / "_npx" / "abc123" / "node_modules" / "server.js", "x" * 30)
@@ -1216,8 +1252,6 @@ def test_the_npx_cache_is_cleared_with_the_package_cache(tmp_path, monkeypatch,
def test_a_purge_holds_the_registry_against_a_download_claimed_after_the_check(tmp_path):
- """The reservation closes the check-then-delete race, which is why
- begin_delete exists for the per-repository path."""
from hub.utils.download_registry import DownloadRegistry
registry = DownloadRegistry()
@@ -1236,8 +1270,6 @@ def test_a_purge_holds_the_registry_against_a_download_claimed_after_the_check(t
def test_the_xet_cache_is_reserved_like_the_hub(monkeypatch):
- """Both download services pass the active xet cache into their claim, so a
- worker is fetching chunks into it while a clear would be emptying it."""
from hub.utils import download_registry
from utils import cache_inventory as module
@@ -1254,7 +1286,6 @@ def test_the_xet_cache_is_reserved_like_the_hub(monkeypatch):
models, datasets = _Registry(), _Registry()
monkeypatch.setattr(download_registry, "get_models_registry", lambda: models)
- # The purge reserves datasets through the service, so stub it there.
monkeypatch.setattr(download_registry, "get_datasets_registry", lambda: datasets)
from hub.services.datasets import downloads as dataset_downloads
@@ -1268,7 +1299,6 @@ def test_the_xet_cache_is_reserved_like_the_hub(monkeypatch):
def test_a_repository_delete_and_a_whole_cache_purge_exclude_each_other():
- """Both are removing files from the same root, in either order."""
from hub.utils.download_registry import DownloadRegistry
registry = DownloadRegistry()
@@ -1285,8 +1315,6 @@ def test_a_repository_delete_and_a_whole_cache_purge_exclude_each_other():
def test_a_running_training_job_holds_off_the_model_cache_clears(
tmp_path, monkeypatch, isolated_caches
):
- """A spawned trainer gets the same HF_HUB_CACHE and HF_XET_CACHE and calls
- snapshot_download and load_dataset itself, outside every registry here."""
import core.training as training_module
from utils import cache_inventory as module
@@ -1319,8 +1347,6 @@ def test_a_running_training_job_holds_off_the_model_cache_clears(
def test_the_torch_extensions_cache_repeats_the_name_on_windows(
tmp_path, monkeypatch, isolated_caches
):
- """get_default_build_root() is user_cache_dir(appname = "torch_extensions")
- with no appauthor, which torch/_appdirs defaults to the app name."""
from utils import cache_inventory as module
monkeypatch.delenv("TORCH_EXTENSIONS_DIR", raising = False)
@@ -1336,8 +1362,6 @@ def test_the_torch_extensions_cache_repeats_the_name_on_windows(
def test_a_diffusion_run_holds_off_the_model_cache_clears(monkeypatch):
- """Diffusion jobs are tracked apart from the LLM trainer, and their worker
- loads the base model from the same hub and xet caches."""
import core.training as training_module
from core.training import diffusion_training_service
from utils import cache_inventory as module
@@ -1362,9 +1386,6 @@ def test_a_diffusion_run_holds_off_the_model_cache_clears(monkeypatch):
def test_a_compiled_cache_the_clear_would_refuse_says_so_on_the_row(
tmp_path, monkeypatch, only_the_configured_compiled_cache
):
- """It is cleared through its own module, so the standard gate never saw it:
- the row offered a button that _purge_unsloth_compiled always refused, and
- walked a protected tree the ordinary path is careful not to."""
from utils import cache_cleanup
from utils.paths import storage_roots
@@ -1388,7 +1409,6 @@ def test_a_compiled_cache_the_clear_would_refuse_says_so_on_the_row(
def test_moving_the_models_folder_forgets_the_old_roots_sizes(
tmp_path, monkeypatch, isolated_caches
):
- """Keyed by cache, not path, so a new root never evicts it; API callers cannot force a refresh."""
from utils import cache_inventory as module
_write(tmp_path / "hub" / "blob", "b" * 40)
@@ -1408,7 +1428,6 @@ def test_moving_the_models_folder_forgets_the_old_roots_sizes(
def test_setting_the_cache_home_invalidates_the_inventory(monkeypatch):
- """Wired into set_hf_cache_home, not merely available to it. The real function is called."""
import hub.utils.hf_cache_state as hf_cache_state
import hub.utils.inventory_scan as inventory_scan
import storage.studio_db as studio_db
@@ -1429,7 +1448,6 @@ def test_setting_the_cache_home_invalidates_the_inventory(monkeypatch):
def test_bytes_still_linked_from_outside_are_not_called_reclaimable(tmp_path, isolated_caches):
- """Bytes still hardlinked from outside are not reclaimable; unlinking the cache copy frees nothing."""
root = tmp_path / "uv"
shared = _write(root / "archive" / "wheel.so", "w" * 800)
venv = tmp_path / "venv" / "lib"
@@ -1458,7 +1476,6 @@ def test_a_purge_reports_only_the_bytes_it_actually_freed(tmp_path, isolated_cac
def test_a_whole_hub_clear_waits_for_a_loaded_model(monkeypatch, isolated_caches):
- """A whole-cache clear must honor load guards too; sd.cpp re-reads companion files every generation."""
import hub.services.models.deletion as deletion
monkeypatch.setattr(
@@ -1471,7 +1488,6 @@ def test_a_whole_hub_clear_waits_for_a_loaded_model(monkeypatch, isolated_caches
def _idle_dictation(monkeypatch, **state):
- """Point the guard's dictation probe at a stated load state."""
from core.inference import stt_registry
resident = {"model": None, "engine": None, "device": None, "loading": False}
@@ -1480,11 +1496,7 @@ def _idle_dictation(monkeypatch, **state):
def test_a_whole_hub_clear_waits_for_a_loaded_dictation_model(monkeypatch):
- """Dictation is the fifth backend, and stt_sidecar keeps its checkpoints in the same hub
- cache this clear empties. The four backends the guard already asks cannot see it, so a
- resident Whisper worker would have had its snapshot unlinked from under it."""
from hub.services.models.deletion import any_model_load_blocks_cache_clear
-
_idle_dictation(monkeypatch, model = "openai/whisper-large-v3", engine = "transformers")
assert any_model_load_blocks_cache_clear() == (
@@ -1493,10 +1505,7 @@ def test_a_whole_hub_clear_waits_for_a_loaded_dictation_model(monkeypatch):
def test_a_whole_hub_clear_waits_for_a_loading_dictation_model(monkeypatch):
- """A sidecar still starting is the worse case, not the safer one: the snapshot is being read
- right now. Mirrors the Images / Video loading_repo_ids branch."""
from hub.services.models.deletion import any_model_load_blocks_cache_clear
-
_idle_dictation(monkeypatch, loading = True)
assert any_model_load_blocks_cache_clear() == (
@@ -1505,8 +1514,7 @@ def test_a_whole_hub_clear_waits_for_a_loading_dictation_model(monkeypatch):
def test_idle_dictation_does_not_block_a_hub_clear(monkeypatch):
- """The negative control. Without it the two tests above pass against a guard that refuses
- every clear, which is the opposite of the behaviour being added."""
+ "An idle sidecar is the negative control for guards that refuse every clear."
from hub.services.models.deletion import any_model_load_blocks_cache_clear
_idle_dictation(monkeypatch)
@@ -1515,9 +1523,6 @@ def test_idle_dictation_does_not_block_a_hub_clear(monkeypatch):
def test_an_unreachable_dictation_probe_does_not_block_a_hub_clear(monkeypatch):
- """Fail open on ACQUIRE, like every other backend here: a sidecar that cannot be asked is not
- holding anything this process can see. cache_inventory still fails CLOSED on a raising guard,
- which test_an_unverifiable_load_state_refuses_rather_than_clears covers."""
from core.inference import stt_registry
from hub.services.models.deletion import any_model_load_blocks_cache_clear
@@ -1530,7 +1535,6 @@ def test_an_unreachable_dictation_probe_does_not_block_a_hub_clear(monkeypatch):
def test_a_whole_hub_clear_waits_for_a_chat_load_that_has_not_spawned_yet(monkeypatch):
- """A chat load before llama-server spawns still blocks a whole-cache clear during GGUF download."""
from core.inference import llama_cpp
from hub.services.models.deletion import any_model_load_blocks_cache_clear
@@ -1543,7 +1547,6 @@ def test_a_whole_hub_clear_waits_for_a_chat_load_that_has_not_spawned_yet(monkey
def test_a_whole_hub_clear_waits_for_a_draining_image_load(monkeypatch):
- """Repos a cancelled diffusers load still drains must block a whole-cache clear, as per-repo does."""
import types
from hub.services.models.deletion import any_model_load_blocks_cache_clear
@@ -1565,8 +1568,6 @@ def test_a_whole_hub_clear_waits_for_a_draining_image_load(monkeypatch):
def test_an_unverifiable_load_state_refuses_rather_than_clears(monkeypatch, isolated_caches):
- """Not being able to tell whether weights are in use is not permission to unlink them.
- The per-repo path answers 503 for the same reason."""
import hub.services.models.deletion as deletion
def _raise():
@@ -1581,8 +1582,6 @@ def test_an_unverifiable_load_state_refuses_rather_than_clears(monkeypatch, isol
def test_a_cache_the_environment_is_symlinked_into_is_not_offered(
tmp_path, monkeypatch, isolated_caches
):
- """uv help sync: clearing the cache under UV_LINK_MODE=symlink "will break all installed
- packages". A bulk clear is meant to cost a re-download at worst, never a broken install."""
_write(tmp_path / "uv" / "archive" / "pkg" / "__init__.py", "x")
site = tmp_path / "site-packages"
site.mkdir()
@@ -1620,7 +1619,6 @@ def test_an_ordinary_uv_cache_is_still_offered(tmp_path, isolated_caches):
def test_a_partial_purge_reports_only_what_it_actually_removed(tmp_path, isolated_caches):
- """A partial rmtree reports only bytes it removed; survivors are subtracted from the freed total."""
root = tmp_path / "uv"
_write(root / "tree" / "gone.bin", "g" * 100)
stubborn = root / "tree" / "stays"
@@ -1637,7 +1635,6 @@ def test_a_partial_purge_reports_only_what_it_actually_removed(tmp_path, isolate
def test_a_curated_dataset_import_holds_off_a_model_cache_clear():
- """A curated dataset import must hold off a model cache clear, since it calls load_dataset directly."""
from hub.utils.download_registry import get_datasets_registry
registry = get_datasets_registry()
@@ -1653,8 +1650,7 @@ def test_a_curated_dataset_import_holds_off_a_model_cache_clear():
def test_the_import_route_takes_that_claim_and_gives_it_back():
- """The interlock has to be reached, not merely available. The route is checked as source
- because driving the import needs the network and a real dataset repo."""
+ "Inspect the route as source because executing its import requires a real dataset and network."
import ast
import inspect
@@ -1675,7 +1671,6 @@ def test_the_import_route_takes_that_claim_and_gives_it_back():
def test_every_account_dataset_registry_is_reserved_by_a_purge(monkeypatch):
- """Each managed account has its own dataset registry; a purge must reserve all of them."""
from hub.services.datasets import downloads as dataset_downloads
from hub.utils import download_registry
@@ -1691,8 +1686,6 @@ def test_every_account_dataset_registry_is_reserved_by_a_purge(monkeypatch):
def test_a_registry_created_during_a_purge_is_born_reserved(monkeypatch):
- """A registry minted during a purge must be born reserved, as _deleting already is for new
- registries."""
from hub.services.datasets import downloads as dataset_downloads
from hub.utils import download_registry
diff --git a/studio/backend/utils/cache_inventory.py b/studio/backend/utils/cache_inventory.py
index 26333492130..90e2dca1f3d 100644
--- a/studio/backend/utils/cache_inventory.py
+++ b/studio/backend/utils/cache_inventory.py
@@ -1,8 +1,6 @@
# SPDX-License-Identifier: AGPL-3.0-only
# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
-"""Empties (never removes) only CACHE_DEFINITIONS roots, refusing protected paths, protected trees
-and symlink roots; symlinks inside are unlinked, never followed"""
from __future__ import annotations
@@ -35,15 +33,11 @@ class CachePurgeRefused(RuntimeError):
class CacheDefinition:
key: str
group: str
- # True when emptying costs a user-chosen re-download; never in a bulk purge.
opt_in: bool
resolve: Callable[[], list[Path]]
- # Only top-level entries matching these globs are measured or deleted, for config-holding roots.
patterns: Optional[tuple[str, ...]] = None
custom_purge: Optional[Callable[[], "PurgeOutcome"]] = None
- # Sized by its own rule, when a walk would not match what a clear removes.
custom_measure: Optional[Callable[[], "tuple[int, int]"]] = None
- # Its own gate, for a cache whose roots the standard one cannot check.
custom_block: Optional[Callable[[], Optional[str]]] = None
@@ -105,7 +99,7 @@ _UV_CACHE_MARKER = "uv-cache-dir"
def _recorded_uv_cache() -> Optional[Path]:
- """Read the way unsloth_cli parses it: no expanduser, since uv makes a literal ~ directory."""
+ "Match the CLI: uv treats ~ literally in the recorded path."
try:
from utils.paths.storage_roots import cache_root
recorded = (cache_root() / _UV_CACHE_MARKER).read_text(
@@ -123,7 +117,6 @@ def _recorded_uv_cache() -> Optional[Path]:
def _uv_dirs() -> list[Path]:
- # Both: _setup_cache_env seeds one, the installer may record another; either can be multi-gigabyte.
roots = _first(_env_dir("UV_CACHE_DIR"), _platform_cache_dir("uv"))
recorded = _recorded_uv_cache()
if recorded is not None:
@@ -137,7 +130,6 @@ _probe_lock = threading.Lock()
def _probe_tool_cache_dir(name: str, command: list[str]) -> Optional[Path]:
- """Asks the tool itself, since pip.conf and .npmrc can move the cache with no environment variable."""
from utils.child_stdio import utf8_child_env
with _probe_lock:
if name in _probed_cache_dirs:
@@ -160,7 +152,6 @@ def _probe_tool_cache_dir(name: str, command: list[str]) -> Optional[Path]:
reported = done.stdout.strip() if done.returncode == 0 else ""
if reported:
candidate = Path(reported).expanduser()
- # npm prints "undefined" rather than failing with no answer.
if candidate.is_absolute():
answer = candidate
_probed_cache_dirs[name] = answer
@@ -176,12 +167,10 @@ def _pip_dirs() -> list[Path]:
def _npm_configured_dir() -> Optional[Path]:
- # Any npm on PATH will do: .npmrc is per user, not per install.
npm = shutil.which("npm")
return None if npm is None else _probe_tool_cache_dir("npm", [npm, "config", "get", "cache"])
-# Not the rest of ~/.npm: _logs is the user's.
_NPM_CACHE_CHILDREN = ("_cacache", "_npx")
@@ -204,7 +193,7 @@ def _hf_paths():
def _hf_homes() -> list[Path]:
- """For protection only: an API key can append to this history, so it must never pick a purge root."""
+ "History is API-writable and must never select purge roots."
from utils.hf_cache_settings import known_hf_cache_homes
return list(known_hf_cache_homes())
@@ -214,13 +203,11 @@ def _hf_hub_dirs() -> list[Path]:
def _hf_child_dirs(name: str, configured: Optional[Path]) -> list[Path]:
- # HF reads the variable instead of <home>/<name>, so these are alternatives; the home is the effective one, not the one Settings displays.
from utils.hf_cache_settings import effective_cache_home
return _first(configured, effective_cache_home() / name)
def _studio_datasets_fallback() -> Optional[Path]:
- """The Studio cache a dataset load retries in when HF's is not writable."""
try:
from utils.paths.storage_roots import cache_root
return _safe_resolve(cache_root() / "hf-datasets")
@@ -269,7 +256,6 @@ def _torch_inductor_dirs() -> list[Path]:
import re
import tempfile
- # Mirrors torch cache_dir_utils exactly; uses getpass, not a bare uid, since a container with no USER puts the cache at another directory.
try:
user = getpass.getuser()
except (KeyError, ModuleNotFoundError, OSError):
@@ -286,7 +272,6 @@ def _torch_extensions_dirs() -> list[Path]:
if configured is not None:
return [configured]
if _is_windows():
- # torch/_appdirs defaults appauthor to the app name, so the name appears twice.
return [_local_app_data() / "torch_extensions" / "torch_extensions" / "Cache"]
return [_platform_cache_dir("torch_extensions")]
@@ -299,7 +284,6 @@ def _cuda_dirs() -> list[Path]:
configured = _env_dir("CUDA_CACHE_PATH")
if configured is not None:
return [configured]
- # CUDA's defaults: ROAMING AppData (Windows), Application Support (macOS), ~/.nv elsewhere.
if _is_windows():
roaming = (os.environ.get("APPDATA") or "").strip()
base = Path(roaming) if roaming else _home() / "AppData" / "Roaming"
@@ -315,9 +299,6 @@ def _numba_dirs() -> list[Path]:
def _matplotlib_dirs() -> list[Path]:
- """get_cachedir()'s own rules: _get_config_or_cache_dir takes the XDG branch
- for linux and freebsd only, and otherwise ~/.matplotlib, with win32
- preferring %LOCALAPPDATA%\\matplotlib when the legacy dir is absent."""
configured = _env_dir("MPLCONFIGDIR")
if configured is not None:
return [configured]
@@ -344,7 +325,6 @@ def _matplotlib_patterns() -> Optional[tuple[str, ...]]:
def _vllm_dirs() -> list[Path]:
- # vllm/envs.py: XDG_CACHE_HOME or ~/.cache, then vllm, on every platform (Linux-only in the helper).
xdg = (os.environ.get("XDG_CACHE_HOME") or "").strip()
base = Path(xdg).expanduser() if xdg else _home() / ".cache"
return _first(_env_dir("VLLM_CACHE_ROOT"), base / "vllm")
@@ -356,7 +336,6 @@ def _unsloth_compiled_dirs() -> list[Path]:
def _measure_unsloth_compiled() -> tuple[int, int]:
- """Counts only what a clear removes: directories Unsloth made whole, the rest only generated modules."""
from utils.cache_cleanup import _cleanable_cache_dirs
total = 0
@@ -371,14 +350,12 @@ def _measure_unsloth_compiled() -> tuple[int, int]:
def _compiled_cache_refusal() -> Optional[str]:
- """Its own gate: the clear is all-or-nothing across the directories it owns, so one refusal stops it."""
from utils.cache_cleanup import _cleanable_cache_dirs
protected = protected_paths()
trees = protected_trees()
keep = sheltered_roots("unsloth_compiled")
for directory, dedicated in _cleanable_cache_dirs():
- # Only the generated module files are ever touched in a shared one.
if not dedicated:
continue
try:
@@ -389,7 +366,6 @@ def _compiled_cache_refusal() -> Optional[str]:
def _purge_unsloth_compiled() -> PurgeOutcome:
- """Delegates to cache_cleanup, which knows what Unsloth created and serializes with sibling backends."""
from utils.cache_cleanup import (
LOCK_BUSY,
_cleanable_cache_dirs,
@@ -414,7 +390,6 @@ def _purge_unsloth_compiled() -> PurgeOutcome:
outcome.freed_bytes = max(0, before - after)
outcome.removed_entries = max(0, entries - remaining)
if after > 0:
- # Failures are swallowed: check remaining bytes, not entries, as a dedicated cache keeps a marker.
outcome.errors.append(
"Part of the compiled cache could not be removed and is still in place."
)
@@ -456,7 +431,6 @@ CACHE_KEYS: tuple[str, ...] = tuple(definition.key for definition in CACHE_DEFIN
_DEFINITIONS_BY_KEY = {definition.key: definition for definition in CACHE_DEFINITIONS}
-# Concurrent sweeps of one root race into spurious errors.
_purge_lock = threading.Lock()
@@ -475,7 +449,7 @@ def _safe_resolve(path: Path) -> Optional[Path]:
def _is_junction(path: Path | str) -> bool:
- """On Windows is_symlink() is False for a junction yet realpath follows it, so check separately; os.path.isjunction needs 3.12 and the package supports 3.9."""
+ "Windows junctions escape is_symlink(); Python 3.9 needs the fallback."
isjunction = getattr(os.path, "isjunction", None)
if isjunction is not None:
try:
@@ -492,7 +466,6 @@ def _is_junction(path: Path | str) -> bool:
def protected_paths() -> set[Path]:
- """User data, never purged; the Hugging Face home stays protected because it holds the access token."""
from utils.paths.storage_roots import (
assets_root,
auth_db_path,
@@ -515,7 +488,6 @@ def protected_paths() -> set[Path]:
Path.home(),
studio_root(),
studio_db_path(),
- # The shim and the managed executables. No cache belongs there.
studio_bin_root(),
auth_root(),
auth_db_path(),
@@ -525,11 +497,9 @@ def protected_paths() -> set[Path]:
exports_root(),
rag_root(),
tensorboard_root(),
- # Not a cache: decoding and training read files back from it.
tmp_root(),
documents_root(),
project_workspaces_root(),
- # Not a cache root of ours as a whole: the parent of per-tool cache dirs, plus llama.cpp slot state.
cache_root(),
]
for name in ("DATA_DESIGNER_HOME", "UNSLOTH_STUDIO_PROJECTS_HOME", "UNSLOTH_STUDIO_HOME"):
@@ -560,7 +530,6 @@ def protected_paths() -> set[Path]:
def protected_trees() -> set[Path]:
- """Refuses a cache root beneath user data, e.g. TRITON_CACHE_DIR inside projects; studio and HF cache homes are absent since real caches live in both."""
from utils.paths.storage_roots import (
assets_root,
auth_root,
@@ -584,7 +553,6 @@ def protected_trees() -> set[Path]:
rag_root(),
tensorboard_root(),
project_workspaces_root(),
- # Studio home and temp dir descendants are allowed (caches live there), so name these.
documents_root(),
studio_bin_root(),
tmp_root(),
@@ -613,7 +581,6 @@ def _is_within(child: Path, parent: Path) -> bool:
def sheltered_roots(exclude_key: Optional[str] = None) -> dict[Path, str]:
- """Roots another key's clear must not empty: emptying one takes what its narrower clear keeps."""
roots: dict[Path, str] = {}
for definition in CACHE_DEFINITIONS:
if definition.key == exclude_key:
@@ -638,7 +605,6 @@ def assert_purgeable_root(
trees: Optional[set[Path]] = None,
keep: Optional[dict[Path, str]] = None,
) -> Path:
- """Judges the resolved directory, so a variable pointed at a symlink cannot smuggle in a target."""
protected = protected_paths() if protected is None else protected
trees = protected_trees() if trees is None else trees
raw = Path(root)
@@ -653,7 +619,6 @@ def assert_purgeable_root(
if resolved is None:
raise CachePurgeRefused(f"Cache root cannot be resolved: {raw}")
if len(resolved.parts) < 3:
- # "/", "/home", "C:\\", "C:\\Users": nothing that shallow is a cache.
raise CachePurgeRefused(f"Cache root is too close to the filesystem root: {resolved}")
if not resolved.is_dir():
raise CachePurgeRefused(f"Cache root is not a directory: {resolved}")
@@ -685,17 +650,7 @@ def _matching(name: str, patterns: Optional[Iterable[str]]) -> bool:
class LinkLedger:
- """Bytes a removal would actually free, counted per inode rather than per name.
-
- One link frees its bytes when it goes. Several free nothing unless every one of them goes
- too, and that is not a corner case: uv's default link mode on Windows is hardlink, so an
- installed environment's files ARE links into the uv cache. The Hugging Face cache does the
- same for blobs on filesystems without symlinks, but there both links live inside the cache.
-
- So links are tallied as they are met and a multi-link inode contributes only once the number
- seen inside the roots being measured reaches st_nlink. Anything still linked from outside is
- left out, which understates rather than promises space that unlinking will not return.
- """
+ "Count an inode only when all its hardlinks are removed."
def __init__(self) -> None:
self._single = 0
@@ -719,8 +674,6 @@ class LinkLedger:
class _OccupancyLedger:
- """Disk occupancy includes shared files even when clearing cannot free them."""
-
def __init__(self) -> None:
self._seen: set[tuple] = set()
self.bytes = 0
@@ -767,12 +720,10 @@ def _walk_into(
stack: list,
ledger: LinkLedger,
occupancy: Optional[_OccupancyLedger] = None,
+ *,
+ excluded_roots: Optional[set[Path]] = None,
) -> 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.
- """
+ "Keep paths as strings: uv/triton trees can contain millions of files."
count = 0
single = 0
add = ledger.add
@@ -781,6 +732,8 @@ def _walk_into(
try:
while stack:
current = pop()
+ if excluded_roots and Path(current) in excluded_roots:
+ continue
try:
with os.scandir(current) as entries:
for entry in entries:
@@ -814,7 +767,6 @@ def _measure_tree(
ledger: LinkLedger,
occupancy: Optional[_OccupancyLedger] = None,
) -> 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, occupancy)
@@ -824,6 +776,7 @@ def _measure_root(
patterns: Optional[Iterable[str]] = None,
ledger: Optional[LinkLedger] = None,
occupancy: Optional[_OccupancyLedger] = None,
+ excluded_roots: Optional[set[Path]] = None,
) -> tuple[int, int]:
ledger = LinkLedger() if ledger is None else ledger
entries = 0
@@ -832,7 +785,6 @@ def _measure_root(
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:
@@ -850,7 +802,7 @@ def _measure_root(
except OSError as exc:
logger.debug(f"Could not size {root}: {exc}")
subdirs.reverse()
- _walk_into(subdirs, ledger, occupancy)
+ _walk_into(subdirs, ledger, occupancy, excluded_roots = excluded_roots)
return ledger.freeable_bytes(), entries
@@ -881,7 +833,7 @@ def _resolve_roots(definition: CacheDefinition) -> list[Path]:
def _measurement_roots(definition: CacheDefinition) -> list[Path]:
- """Remembered HF locations count towards storage, but never widen a purge."""
+ "Remembered HF locations count storage without widening a purge."
roots = _resolve_roots(definition)
if definition.key == "hf_hub":
from utils.hf_cache_settings import known_hf_hub_caches
@@ -895,7 +847,6 @@ def _measurement_roots(definition: CacheDefinition) -> list[Path]:
resolved = _safe_resolve(root)
if resolved is None or resolved in unique:
continue
- # Never walk a protected root itself, or a link into one.
try:
assert_purgeable_root(root, protected = protected, trees = set(), keep = {})
except CachePurgeRefused:
@@ -907,8 +858,24 @@ def _measurement_roots(definition: CacheDefinition) -> list[Path]:
return unique
+def _nested_active_roots(definition: CacheDefinition, measured: list[Path]) -> list[Path]:
+ protected = protected_paths()
+ nested: list[Path] = []
+ for root in _resolve_roots(definition):
+ resolved = _safe_resolve(root)
+ if resolved is None or resolved in measured or resolved in nested:
+ continue
+ if not any(_is_within(resolved, parent) for parent in measured):
+ continue
+ try:
+ assert_purgeable_root(root, protected = protected, trees = set(), keep = {})
+ except CachePurgeRefused:
+ continue
+ nested.append(resolved)
+ return nested
+
+
def _system_disk_device():
- # The volume /api/system and models_disk_usage report, wherever Studio lives.
try:
return Path(os.path.abspath(os.sep)).stat().st_dev
except OSError:
@@ -940,7 +907,6 @@ def _system_disk_occupancy(occupancy: _OccupancyLedger) -> int:
def _model_cache_action(root: Path, entry: os.DirEntry) -> dict:
- """An identity for the existing guarded Hub action, never a path-delete grant."""
refused = {"delete_allowed": False}
try:
if (
@@ -959,7 +925,6 @@ def _model_cache_action(root: Path, entry: os.DirEntry) -> dict:
candidate = _safe_resolve(Path(entry.path))
if candidate is None or candidate.parent != root or candidate.name != entry.name:
return refused
- # cache_path is the repo directory; the Hub delete re-validates its root.
if scoped_delete_root("model", repo_id, str(candidate)) != root:
return refused
return {
@@ -973,20 +938,29 @@ def _model_cache_action(root: Path, entry: os.DirEntry) -> dict:
def cache_breakdown(key: str) -> dict:
- """Read-only, on-demand HF directory breakdown; never accepts a browser path."""
if key not in {"hf_hub", "hf_datasets", "hf_xet", "hf_assets"}:
raise ValueError("Only Hugging Face caches have a directory breakdown.")
rows = []
occupancy = _OccupancyLedger()
- for root in _measurement_roots(definition_for(key)):
+ definition = definition_for(key)
+ measured = _measurement_roots(definition)
+ nested = _nested_active_roots(definition, measured)
+ excluded_roots = set(nested)
+ for root in nested + measured:
try:
with os.scandir(root) as scan:
for entry in scan:
if entry.is_symlink() or _is_junction(entry.path):
continue
+ if nested and root not in nested and _safe_resolve(Path(entry.path)) in nested:
+ continue
before = occupancy.bytes
if entry.is_dir(follow_symlinks = False):
- _measure_root(Path(entry.path), occupancy = occupancy)
+ _measure_root(
+ Path(entry.path),
+ occupancy = occupancy,
+ excluded_roots = excluded_roots if root not in nested else None,
+ )
else:
info = (
os.stat(entry.path, follow_symlinks = False)
@@ -1009,12 +983,10 @@ def cache_breakdown(key: str) -> dict:
def describe_cache(definition: CacheDefinition) -> dict:
- """Size one cache and say whether it may be purged, without deleting."""
patterns = _patterns_for(definition)
roots = _resolve_roots(definition)
purgeable = True
blocked_reason: Optional[str] = None
- # Gate first so refused roots are never walked.
measurable = list(roots)
if roots and definition.custom_block is not None:
blocked_reason = definition.custom_block()
@@ -1032,9 +1004,7 @@ def describe_cache(definition: CacheDefinition) -> dict:
blocked_reason = str(exc)
continue
measurable.append(root)
- # purge_cache skips a refused root and carries on, so one bad root does not block the others.
purgeable = bool(measurable)
- # A LINKED cache is never offered, since removing it breaks the install; checked after root refusals.
if blocked_reason is None:
blocked_reason = _link_mode_refusal(definition.key)
if blocked_reason is not None:
@@ -1042,13 +1012,22 @@ def describe_cache(definition: CacheDefinition) -> dict:
measured_paths = roots
system_disk_bytes = None
if definition.key in {"hf_hub", "hf_datasets", "hf_xet", "hf_assets"}:
- # Occupancy is measured even where clearing is refused (e.g. under Documents).
measured_paths = _measurement_roots(definition)
entries = 0
clear_entries = 0
occupancy = _OccupancyLedger()
clear_ledger = LinkLedger()
clear_roots = {_safe_resolve(root) for root in measurable} if purgeable else set()
+ measured_keys = {_safe_resolve(root) for root in measured_paths}
+ nested = {root for root in clear_roots if root is not None and root not in measured_keys}
+ # Share one stat observation between both ledgers, even while downloads grow.
+ for root in measurable if purgeable else []:
+ if _safe_resolve(root) not in nested:
+ continue
+ _, count = _measure_root(
+ root, patterns = patterns, ledger = clear_ledger, occupancy = occupancy
+ )
+ clear_entries += count
for root in measured_paths:
clearable = _safe_resolve(root) in clear_roots
_, count = _measure_root(
@@ -1056,6 +1035,7 @@ def describe_cache(definition: CacheDefinition) -> dict:
patterns = patterns,
occupancy = occupancy,
ledger = clear_ledger if clearable else None,
+ excluded_roots = nested,
)
entries += count
if clearable:
@@ -1099,9 +1079,7 @@ def _patterns_for(definition: CacheDefinition) -> Optional[tuple[str, ...]]:
return definition.patterns
-# Walks take seconds on large uv/triton caches, so repeat reads within the TTL reuse the last answer.
_INVENTORY_TTL_SECONDS = 60.0
-# 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]] = {}
@@ -1120,7 +1098,6 @@ _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()
-# Caches with a background walk queued or running; the walk takes its flight only when it runs.
_background_pending: set = set()
@@ -1130,7 +1107,6 @@ def _flight_for(key: str) -> threading.Lock:
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()
@@ -1141,7 +1117,6 @@ def _walk_and_remember(definition: CacheDefinition, epoch: int) -> dict:
def _refresh_in_background(definition: CacheDefinition) -> bool:
- """At most one walk per cache; False when none could start, so the caller walks instead."""
key = definition.key
with _size_cache_lock:
if key in _background_pending:
@@ -1151,7 +1126,6 @@ def _refresh_in_background(definition: CacheDefinition) -> bool:
def walk() -> None:
try:
with _background_walk_lock:
- # Taken only once this walk can run, so a queued walk never holds up a read of its cache.
flight = _flight_for(key)
if not flight.acquire(blocking = False):
return
@@ -1159,7 +1133,6 @@ def _refresh_in_background(definition: CacheDefinition) -> bool:
with _size_cache_lock:
epoch = _size_epochs.get(key, 0)
remembered = _size_cache.get(key)
- # Overtaken while queued: a purge, download or Recheck already replaced the old size.
if (
remembered is None
or time.monotonic() - remembered[1] < _INVENTORY_TTL_SECONDS
@@ -1197,7 +1170,6 @@ def _described(
deferred: Optional[list] = None,
asked_at: Optional[float] = None,
) -> dict:
- """``deferred`` collects background refreshes to start after the caller's walks; a forced read accepts any walk begun after ``asked_at``."""
started = time.monotonic()
asked = started if asked_at is None else asked_at
with _size_cache_lock:
@@ -1205,14 +1177,12 @@ def _described(
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 not None:
deferred.append(definition)
return remembered[2]
if _refresh_in_background(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:
epoch = _size_epochs.get(definition.key, 0)
@@ -1228,7 +1198,6 @@ def _described(
def cache_inventory(*, refresh: bool = False) -> dict:
- # Started after the foreground walks, which would otherwise share the GIL with them.
deferred: list = []
asked_at = time.monotonic()
entries = [
@@ -1276,11 +1245,9 @@ def _total_disk_bytes() -> Optional[int]:
def _remove_entry(
entry: os.DirEntry, root: Path, outcome: PurgeOutcome, ledger: LinkLedger, survivors: LinkLedger
) -> None:
- """Freed bytes come from the ledger after the root: an inode still linked from outside frees nothing."""
path = Path(entry.path)
try:
if entry.is_symlink():
- # The link, never its target: this is the escape a cache can hold.
os.unlink(path)
elif entry.is_dir(follow_symlinks = False):
real = _safe_resolve(path)
@@ -1288,11 +1255,9 @@ def _remove_entry(
outcome.errors.append(f"Skipped {path}: it resolves outside the cache root")
return
_measure_tree(path, ledger)
- # rmtree refuses a symlinked dir and does not follow inner links, so it stays in root.
try:
shutil.rmtree(path)
except OSError:
- # Survivors are subtracted so freed bytes never count files still on disk.
_measure_tree(path, survivors)
raise
else:
@@ -1315,7 +1280,6 @@ def empty_cache_root(
outcome = PurgeOutcome()
resolved = assert_purgeable_root(root, protected = protected, trees = trees, keep = keep)
ledger = LinkLedger()
- # What a failed removal left behind, subtracted from the ledger below.
survivors = LinkLedger()
try:
with os.scandir(resolved) as scan:
@@ -1332,7 +1296,6 @@ def empty_cache_root(
return outcome
-# Hub and xet roots are written by models and datasets; dataset snapshots land in the same hub tree.
_DOWNLOAD_REGISTRIES = {
"hf_hub": ("models", "datasets"),
"hf_xet": ("models", "datasets"),
@@ -1343,7 +1306,6 @@ _PURGE_BUSY = "Cancel the active downloads before clearing this cache."
def _reserve_downloads(key: str) -> tuple[list, Optional[str]]:
- """Reserves rather than checks, since a worker could claim the cache before the rmtree; a registry that cannot be reached must not block the purge."""
kinds = _DOWNLOAD_REGISTRIES.get(key)
if not kinds:
return [], None
@@ -1385,9 +1347,6 @@ _WORKER_SENSITIVE_KEYS = frozenset({"hf_hub", "hf_xet", "hf_datasets"})
def _any_training_active() -> bool:
- """Either trainer. They are tracked separately and both spawn a worker that
- loads from the Hugging Face cache directly, the LLM one through
- snapshot_download and the diffusion one through from_pretrained."""
active = False
try:
from core.training import get_training_backend
@@ -1405,7 +1364,6 @@ def _any_training_active() -> bool:
def _uv_symlink_refusal() -> Optional[str]:
- """Refuse the uv cache when UV_LINK_MODE=symlink or site-packages entries link into it, since clearing it would break installed packages."""
if (os.environ.get("UV_LINK_MODE") or "").strip().lower() == "symlink":
return "uv is set to link packages from this cache; clearing it would break them."
try:
@@ -1448,7 +1406,7 @@ def _training_refusal(key: str) -> Optional[str]:
def _inference_refusal(key: str) -> Optional[str]:
- """Refuses a model-cache clear while a backend holds weights (sd.cpp re-reads them per generation); fails closed if the check raises."""
+ "sd.cpp re-reads resident weights on every generation."
if key not in _WORKER_SENSITIVE_KEYS:
return None
try:
@@ -1464,7 +1422,6 @@ def _inference_refusal(key: str) -> Optional[str]:
def purge_cache(key: str) -> dict:
- """Empty one cache by key. Never raises for a refusal; it reports it."""
definition = definition_for(key)
training = _training_refusal(key)
if training is not None:
@@ -1504,7 +1461,6 @@ def purge_cache(key: str) -> dict:
outcome.removed_entries += root_outcome.removed_entries
outcome.errors.extend(root_outcome.errors)
if definition.key == "hf_hub":
- # audio.cpp's link farm beside the hub hardlinks its blobs, so they would stay on disk.
from core.inference.audio_cpp_files import prune_link_farm
prune_link_farm(root)
return _purge_result(definition, outcome)
@@ -1521,9 +1477,7 @@ def _purge_result(definition: CacheDefinition, outcome: PurgeOutcome) -> dict:
}
-# Emptying either removes the repos the Hub inventory reports, so it invalidates inventory_scan.
_HF_SCANNED_KEYS = frozenset({"hf_hub", "hf_datasets"})
-# Caches under the configured HF root; they describe another directory once that root changes.
_HF_ROOTED_KEYS = frozenset({"hf_hub", "hf_xet", "hf_datasets"})
@@ -1537,13 +1491,12 @@ def _invalidate_hf_scans() -> None:
def invalidate_hf_rooted_sizes() -> None:
- """Memo is keyed by cache key, not path, so a moved Models Folder leaves stale sizes for the TTL."""
+ "Memo keys omit paths, so moving models must invalidate cached sizes."
for key in _HF_ROOTED_KEYS:
invalidate_cache_size(key)
def purge_caches(keys: Iterable[str]) -> dict:
- """Unknown keys raise before any deletion, so a request naming one unknown cache changes nothing."""
requested = [str(key) for key in keys]
if not requested:
raise ValueError("Choose at least one cache to clear.")