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: show what the caches cost and let them be cleared (#10528)

Daniel Hanf18373631609
diff --git a/studio/backend/hub/services/datasets/downloads.py b/studio/backend/hub/services/datasets/downloads.py
index ca0c4a3c603..da856f5ba56 100644
--- a/studio/backend/hub/services/datasets/downloads.py
+++ b/studio/backend/hub/services/datasets/downloads.py
@@ -55,6 +55,9 @@ _account_registries = {}
_account_registry_lock = threading.Lock()
# The HF cache is shared across per-account registries, so a reservation must reach all of them.
_deleting: set[str] = set()
+# Whole-cache purges in flight. Counted, like DownloadRegistry._purging, and kept here
+# so a registry created for an account DURING a purge starts out reserved too.
+_purging = 0
def _account_registry():
@@ -67,6 +70,11 @@ def _account_registry():
registry = download_registry.DownloadRegistry()
for reserved in _deleting:
registry.begin_delete(reserved)
+ # Same reason as the line above: a purge holding every OTHER registry would not
+ # hold this one, and the account whose first download creates it would write into
+ # a tree being removed.
+ for _ in range(_purging):
+ registry.begin_cache_purge()
_account_registries[account_id] = registry
return registry
@@ -94,6 +102,37 @@ def end_delete(repo_id: str) -> None:
registry.end_delete(repo_id)
+def begin_cache_purge() -> bool:
+ """Reserve EVERY dataset registry for a whole-cache purge, or none of them.
+
+ A managed-account install does not have one dataset registry, it has one per account
+ (:func:`_account_registry`). Reserving only the singleton left every other account's
+ download invisible to the purge, which would then remove files under its worker. Same
+ all-or-nothing shape as :func:`begin_delete`, and the count is recorded so a registry
+ created after this returns is born reserved rather than free to claim work.
+ """
+ global _purging
+ with _account_registry_lock:
+ reserved = []
+ for registry in (_registry, *_account_registries.values()):
+ if not registry.begin_cache_purge():
+ for done in reserved:
+ done.end_cache_purge()
+ return False
+ reserved.append(registry)
+ _purging += 1
+ return True
+
+
+def end_cache_purge() -> None:
+ global _purging
+ with _account_registry_lock:
+ if _purging:
+ _purging -= 1
+ for registry in (_registry, *_account_registries.values()):
+ registry.end_cache_purge()
+
+
def _download_job_key(repo_id: str) -> str:
return download_registry.normalize_repo_key(repo_id)
diff --git a/studio/backend/hub/services/models/deletion.py b/studio/backend/hub/services/models/deletion.py
index 21ce726714a..bee977d82ad 100644
--- a/studio/backend/hub/services/models/deletion.py
+++ b/studio/backend/hub/services/models/deletion.py
@@ -656,6 +656,95 @@ def _diffusion_blocks_delete(repo_id: str) -> Optional[str]:
return None
+def any_model_load_blocks_cache_clear() -> Optional[str]:
+ """The refusal detail if ANY inference backend is holding a cached model, else None.
+
+ The guards above ask whether one repo is in use. Emptying the whole Hugging Face cache is
+ every repo at once, so there is no repo to match on and anything loaded or loading is enough.
+ sd.cpp in particular re-reads its companion VAE and text-encoder files for every generation,
+ so a clear can break a model that was loaded long before it.
+
+ Fail-open on ACQUIRE, like the guards above: a backend that cannot be reached is not holding
+ anything this process can see. A backend that IS reachable and raises while being asked is a
+ different matter, and the caller fails closed on it rather than unlink weights blindly.
+ """
+ try:
+ from routes.inference import get_llama_cpp_backend
+ backend = get_llama_cpp_backend()
+ except Exception as exc: # noqa: BLE001 - unavailable is not "in use"
+ logger.debug(f"llama.cpp backend unavailable during the cache-clear guard: {exc}")
+ else:
+ if (backend.is_loaded or backend.is_active) and backend.model_identifier:
+ return "Unload the model before clearing the model cache"
+
+ # is_active above only covers a live llama-server process, which an HF-backed chat load does
+ # not have until its GGUF finished downloading: minutes, per chat_load_active's own docstring.
+ # Those files come down through hf_hub_download_with_xet_fallback rather than the download
+ # registry, so the reservation taken later in the purge does not cover them either.
+ try:
+ from core.inference.llama_cpp import chat_load_active
+ loading_chat = chat_load_active()
+ except Exception as exc: # noqa: BLE001 - unavailable is not "in use", as above
+ logger.debug(f"Chat load state unavailable during the cache-clear guard: {exc}")
+ else:
+ if loading_chat:
+ return "A model load is using the cache; wait for it to finish"
+
+ try:
+ from core.inference.orchestrator import peek_inference_backend
+
+ # Peek, never construct: building one just to learn nothing is loaded imports torch.
+ engine = peek_inference_backend()
+ except Exception as exc: # noqa: BLE001
+ logger.debug(f"Inference backend unavailable during the cache-clear guard: {exc}")
+ else:
+ if engine is not None and engine.active_model_name:
+ return "Unload the model before clearing the model cache"
+
+ for label, load in (
+ ("Images", "core.inference.diffusion_engine_router:get_active_diffusion_engine"),
+ ("Video", "core.inference.video:get_video_backend"),
+ ):
+ module_name, _, attr = load.partition(":")
+ try:
+ module = __import__(module_name, fromlist = [attr])
+ held = getattr(module, attr)()
+ except Exception as exc: # noqa: BLE001
+ logger.debug(f"{label} backend unavailable during the cache-clear guard: {exc}")
+ continue
+ if held is None:
+ continue
+ if held.status().get("loaded"):
+ return "Unload the model before clearing the model cache"
+ if any(getattr(held, "loaded_repo_ids", tuple)()):
+ return "Unload the model before clearing the model cache"
+ if any(getattr(held, "loading_repo_ids", tuple)()):
+ return f"An {label} model load is using the cache; wait for it to finish"
+ # A cancelled load leaves loading_repo_ids() at once but keeps its repos in
+ # draining_repo_ids() while the worker thread reads on inside _prefetch_files,
+ # holding no lock. _diffusion_blocks_delete already refuses on that; emptying the
+ # whole cache is every repo at once, so it cannot ask less than the per-repo path.
+ if any(getattr(held, "draining_repo_ids", tuple)()):
+ return f"An {label} model load is still unwinding; wait for it to finish"
+
+ # Dictation is the fifth backend and the one none of the four above reports. Its sidecars are
+ # managed by stt_registry, and stt_sidecar resolves their checkpoints under the SAME hub cache
+ # this clear empties (_find_complete_cached_snapshot -> _repo_cache_dir -> hub_cache), so a
+ # resident Whisper / Parakeet worker re-reading its snapshot is exactly the case the docstring
+ # above says is enough on its own.
+ try:
+ from core.inference import stt_registry
+ dictation = stt_registry.resident()
+ except Exception as exc: # noqa: BLE001 - unavailable is not "in use", as above
+ logger.debug(f"Dictation unavailable during the cache-clear guard: {exc}")
+ else:
+ if dictation.get("model"):
+ return "Unload the dictation model before clearing the model cache"
+ if dictation.get("loading"):
+ return "A dictation model load is using the cache; wait for it to finish"
+ return None
+
+
def _video_blocks_delete(repo_id: str) -> Optional[str]:
"""The 400 detail if the Video backend holds or is fetching *repo_id*, else None. Video repos share the On Device delete action, so a live Wan / LTX / Hunyuan pipeline could otherwise lose its snapshot. Mirrors :func:`_diffusion_blocks_delete`."""
try:
diff --git a/studio/backend/hub/utils/download_registry.py b/studio/backend/hub/utils/download_registry.py
index 9fdccc153c0..5489d474d37 100644
--- a/studio/backend/hub/utils/download_registry.py
+++ b/studio/backend/hub/utils/download_registry.py
@@ -1220,6 +1220,9 @@ class DownloadRegistry:
# Monotonic across keys so an evicted then re-claimed key never reuses a prior generation, which would let a stale cancel match a new run.
self._generation_seq = 0
self._deleting: dict[str, set[Optional[str]]] = {}
+ # A whole-cache purge, which begin_delete cannot express: it reserves one
+ # repository, and emptying the root has to hold every one of them.
+ self._purging = 0
# Publish external cache owners under the same lock as Model Hub jobs.
self._repository_owners: dict[str, object] = {}
self._lock = threading.Lock()
@@ -1465,6 +1468,8 @@ class DownloadRegistry:
# Run the final admission check under the registry lock: the GGUF load path establishes its marker before its active-job probe, so either this claim sees that marker or the load sees this claim.
if admission_check is not None and not admission_check():
return False, "admission_blocked"
+ if self._purging:
+ return False, "deleting"
deleting_scopes = self._deleting.get(repo)
if deleting_scopes is not None and (
None in deleting_scopes or variant_from_key(key) in deleting_scopes
@@ -1548,7 +1553,7 @@ class DownloadRegistry:
with self._lock:
if repo in self._repository_owners:
return False, "repository_owned"
- if repo in self._deleting:
+ if self._purging or repo in self._deleting:
return False, "deleting"
for key, job in self._jobs.items():
if _repo_of_key(key) != repo or job.state not in _ACTIVE_STATES:
@@ -1688,13 +1693,38 @@ class DownloadRegistry:
repo_id = normalize_repo_key(repo_id)
variant_key = (variant or "").strip().lower() or None
with self._lock:
- if repo_id in self._repository_owners:
+ if repo_id in self._repository_owners or self._purging:
return False
if self._delete_blocked_by_active_locked(repo_id, variant_key):
return False
self._deleting.setdefault(repo_id, set()).add(variant_key)
return True
+ def begin_cache_purge(self) -> bool:
+ """Reserve the WHOLE cache for a purge. False while anything is active.
+
+ ``begin_delete`` closes the check-then-delete race for one repository by
+ making :func:`claim` reject it until the delete finishes. A purge empties
+ the root instead, so it needs the same promise over every repository, or
+ a worker that claims just after the check writes into a tree already
+ being removed. The two exclude each other in both directions, since a
+ scoped delete is removing files from the same root. Counted, so
+ overlapping purges of two caches that share this registry nest.
+ """
+ with self._lock:
+ if not self._purging:
+ if self._repository_owners or self._deleting:
+ return False
+ if any(job.state in _ACTIVE_STATES for job in self._jobs.values()):
+ return False
+ self._purging += 1
+ return True
+
+ def end_cache_purge(self) -> None:
+ with self._lock:
+ if self._purging:
+ self._purging -= 1
+
def end_delete(
self,
repo_id: str,
diff --git a/studio/backend/routes/settings.py b/studio/backend/routes/settings.py
index 3e9c5f4e9be..2973eb6b043 100644
--- a/studio/backend/routes/settings.py
+++ b/studio/backend/routes/settings.py
@@ -4,6 +4,7 @@
"""Settings policy: the account, shared and owner routers decide who may reach each
/api/settings path."""
+import asyncio
import functools
import hashlib
import re
@@ -61,6 +62,7 @@ from utils.upload_limits import (
upload_limit_bytes,
upload_limit_label,
)
+from utils.cache_inventory import CACHE_KEYS, cache_inventory, purge_caches
from utils.xet_notice_settings import reserve_xet_notice
from utils.chat_preferences_settings import (
get_show_model_disclaimer,
@@ -732,6 +734,47 @@ class HuggingFaceCacheResponse(BaseModel):
environment_variable: Optional[str] = None
+class CacheEntryResponse(BaseModel):
+ key: str
+ group: str
+ # Clearing this costs a re-download, so the UI never folds it into a
+ # "clear everything" action.
+ opt_in: bool
+ paths: list[str]
+ size_bytes: int
+ entry_count: int
+ present: bool
+ purgeable: bool
+ blocked_reason: Optional[str] = None
+
+
+class CacheInventoryResponse(BaseModel):
+ caches: list[CacheEntryResponse]
+ total_bytes: int
+ reclaimable_bytes: int
+ free_bytes: Optional[int] = None
+ total_disk_bytes: Optional[int] = None
+
+
+class CachePurgePayload(BaseModel):
+ # Cache identifiers, never paths: the backend owns the mapping from a key to
+ # a directory, so a caller cannot name one of its own.
+ keys: list[str] = Field(min_length = 1, max_length = len(CACHE_KEYS))
+
+
+class CachePurgeResultResponse(BaseModel):
+ key: str
+ freed_bytes: int
+ removed_entries: int
+ errors: list[str]
+
+
+class CachePurgeResponse(BaseModel):
+ results: list[CachePurgeResultResponse]
+ freed_bytes: int
+ inventory: CacheInventoryResponse
+
+
class LlamaCppPathPayload(BaseModel):
path: Optional[str] = Field(default = None, max_length = MAX_CUSTOM_LLAMA_CPP_PATH_LENGTH)
@@ -1134,6 +1177,49 @@ def update_hugging_face_cache(
return _hugging_face_cache_response()
+@_owner_settings_router.get("/caches", response_model = CacheInventoryResponse)
+async def get_caches(
+ refresh: bool = False,
+ current_subject: str = Depends(get_current_subject),
+ via_api_key: bool = Depends(authenticated_via_api_key),
+) -> CacheInventoryResponse:
+ """Size every cache this install writes to, plus the free space around them.
+
+ ``refresh`` re-walks every cache instead of reusing a size measured in the
+ last minute, for the Recheck the UI offers after something big was written.
+ It is the interactive button, and a walk of a large hub or triton cache is
+ seconds of stat calls in the shared executor with no memo in front of it, so
+ only a UI session may ask for one. A plain read stays open to an API key.
+ """
+ if refresh:
+ require_ui_session(via_api_key)
+ # A cold walk of a large hub or triton cache is seconds of stat calls, so it
+ # stays off the event loop.
+ inventory = await asyncio.to_thread(cache_inventory, refresh = refresh)
+ return CacheInventoryResponse(**inventory)
+
+
+@_owner_settings_router.post("/caches/purge", response_model = CachePurgeResponse)
+async def purge_caches_endpoint(
+ payload: CachePurgePayload,
+ current_subject: str = Depends(get_current_subject),
+ via_api_key: bool = Depends(authenticated_via_api_key),
+) -> CachePurgeResponse:
+ """Empty the named caches. Only the interactive UI may delete anything."""
+ require_ui_session(via_api_key)
+ try:
+ result = await asyncio.to_thread(purge_caches, payload.keys)
+ except ValueError as exc:
+ raise log_and_http_error(
+ exc,
+ 400,
+ str(exc),
+ event = "settings.purge_caches_failed",
+ log = logger,
+ ) from exc
+ return CachePurgeResponse(**result)
+
+
@_owner_settings_router.get("/llama-cpp-path", response_model = LlamaCppPathResponse)
def get_llama_cpp_path(current_subject: str = Depends(get_current_subject)) -> LlamaCppPathResponse:
return _llama_cpp_path_response()
diff --git a/studio/backend/routes/training.py b/studio/backend/routes/training.py
index e61a107c956..a2774bcebe1 100644
--- a/studio/backend/routes/training.py
+++ b/studio/backend/routes/training.py
@@ -4603,6 +4603,35 @@ async def import_diffusion_dataset_example(
# Best effort: one unrestorable entry must not mask the original failure.
pass
+ # Hold the datasets registry for this repo across the fetch.
+ #
+ # Both loaders call load_dataset / snapshot_download directly rather than going
+ # through a managed download, so nothing here claimed the registry and a Clear of
+ # hf_hub, hf_xet or hf_datasets passed every guard: begin_cache_purge asks about
+ # jobs, owners and deletes, and this import was none of the three. The snapshot then
+ # went out from under the copy and the import failed in front of the user.
+ #
+ # claim_repository_owner is the same reservation a managed download takes, and it
+ # excludes a purge in both directions: it refuses while one is running, and
+ # begin_cache_purge refuses while an owner is held.
+ _import_registry = None
+ _import_owner = object()
+ try:
+ from hub.utils.download_registry import get_datasets_registry
+ _import_registry = get_datasets_registry()
+ except Exception as exc: # noqa: BLE001 - a broken registry must not kill an import
+ logger.debug(f"Could not reach the datasets registry for the import: {exc}")
+ if _import_registry is not None:
+ granted, reason = _import_registry.claim_repository_owner(
+ entry["repo"], _import_owner
+ )
+ if not granted:
+ if reason == "deleting":
+ raise HTTPException(
+ status_code = 409,
+ detail = "A cache clear is running. Try the import again in a moment.",
+ )
+ _import_registry = None # already busy with this repo; do not release it
try:
try:
if entry["loader"] == "imagefolder_jsonl":
@@ -4646,6 +4675,11 @@ async def import_diffusion_dataset_example(
),
)
finally:
+ if _import_registry is not None:
+ try:
+ _import_registry.release_repository_owner(entry["repo"], _import_owner)
+ except Exception as exc: # noqa: BLE001 - a held claim must not mask the error
+ logger.debug(f"Could not release the import claim: {exc}")
shutil.rmtree(staging, ignore_errors = True)
shutil.rmtree(rescue, ignore_errors = True)
return _import_response(entry, folder, imported = imported)
diff --git a/studio/backend/tests/test_api_cache_routes.py b/studio/backend/tests/test_api_cache_routes.py
new file mode 100644
index 00000000000..121d6852b90
--- /dev/null
+++ b/studio/backend/tests/test_api_cache_routes.py
@@ -0,0 +1,159 @@
+# 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 settings endpoints: keys in, sizes out, and no path ever accepted."""
+
+import pytest
+from fastapi import FastAPI
+from fastapi.testclient import TestClient
+
+from auth.authentication import authenticated_via_api_key, get_current_subject
+import routes.settings as settings_route
+
+
+def client(monkeypatch):
+ app = FastAPI()
+ app.include_router(settings_route.router, prefix = "/api/settings")
+ app.dependency_overrides[get_current_subject] = lambda: "alice"
+ app.dependency_overrides[authenticated_via_api_key] = lambda: False
+ return TestClient(app)
+
+
+def test_the_inventory_reports_a_size_per_cache(monkeypatch, client):
+ monkeypatch.setattr(
+ settings_route,
+ "cache_inventory",
+ lambda refresh = False: {
+ "caches": [
+ {
+ "key": "uv",
+ "group": "packages",
+ "opt_in": False,
+ "paths": ["/cache/uv"],
+ "size_bytes": 2048,
+ "entry_count": 3,
+ "present": True,
+ "purgeable": True,
+ "blocked_reason": None,
+ }
+ ],
+ "total_bytes": 2048,
+ "reclaimable_bytes": 2048,
+ "free_bytes": 100,
+ "total_disk_bytes": 200,
+ },
+ )
+ body = client.get("/api/settings/caches").json()
+ assert body["total_bytes"] == 2048
+ assert body["caches"][0]["key"] == "uv"
+ assert body["caches"][0]["size_bytes"] == 2048
+
+
+def test_a_purge_names_caches_by_key(monkeypatch, client):
+ asked: list = []
+
+ def fake_purge(keys):
+ asked.append(list(keys))
+ return {
+ "results": [{"key": "uv", "freed_bytes": 10, "removed_entries": 1, "errors": []}],
+ "freed_bytes": 10,
+ "inventory": {
+ "caches": [],
+ "total_bytes": 0,
+ "reclaimable_bytes": 0,
+ "free_bytes": None,
+ "total_disk_bytes": None,
+ },
+ }
+
+ monkeypatch.setattr(settings_route, "purge_caches", fake_purge)
+ body = client.post("/api/settings/caches/purge", json = {"keys": ["uv"]}).json()
+ assert asked == [["uv"]]
+ assert body["freed_bytes"] == 10
+
+
+def test_a_purge_that_names_a_path_is_rejected(monkeypatch, client):
+ called = []
+ monkeypatch.setattr(
+ settings_route,
+ "purge_caches",
+ lambda keys: called.append(keys) or (_ for _ in ()).throw(ValueError("boom")),
+ )
+ # No path field exists to send one through, and a path in the key list is
+ # simply not a key.
+ response = client.post("/api/settings/caches/purge", json = {"paths": ["/"]})
+ assert response.status_code == 422
+ assert called == []
+
+ response = client.post("/api/settings/caches/purge", json = {"keys": []})
+ assert response.status_code == 422
+
+
+def test_an_unknown_key_is_a_bad_request(client):
+ response = client.post("/api/settings/caches/purge", json = {"keys": ["/"]})
+ assert response.status_code == 400
+ assert "Unknown cache key" in response.json()["detail"]
+
+
+def test_an_api_key_caller_cannot_delete_anything(monkeypatch):
+ app = FastAPI()
+ app.include_router(settings_route.router, prefix = "/api/settings")
+ app.dependency_overrides[get_current_subject] = lambda: "alice"
+ app.dependency_overrides[authenticated_via_api_key] = lambda: True
+ called = []
+ monkeypatch.setattr(settings_route, "purge_caches", lambda keys: called.append(keys))
+ remote = TestClient(app)
+ response = remote.post("/api/settings/caches/purge", json = {"keys": ["uv"]})
+ assert response.status_code == 403
+ assert called == []
+
+
+def test_recheck_asks_for_a_fresh_walk(monkeypatch, client):
+ asked: list = []
+
+ def fake_inventory(refresh = False):
+ asked.append(refresh)
+ return {
+ "caches": [],
+ "total_bytes": 0,
+ "reclaimable_bytes": 0,
+ "free_bytes": None,
+ "total_disk_bytes": None,
+ }
+
+ monkeypatch.setattr(settings_route, "cache_inventory", fake_inventory)
+ client.get("/api/settings/caches")
+ client.get("/api/settings/caches?refresh=true")
+ assert asked == [False, True]
+
+
+def test_an_api_key_caller_cannot_force_a_rescan(monkeypatch):
+ """A forced walk has no memo in front of it and takes seconds per cache.
+
+ It is the interactive Recheck button, so an API key gets the memoised read
+ and not the one that occupies an executor thread on demand.
+ """
+ app = FastAPI()
+ app.include_router(settings_route.router, prefix = "/api/settings")
+ app.dependency_overrides[get_current_subject] = lambda: "alice"
+ app.dependency_overrides[authenticated_via_api_key] = lambda: True
+ asked: list = []
+
+ def fake_inventory(refresh = False):
+ asked.append(refresh)
+ return {
+ "caches": [],
+ "total_bytes": 0,
+ "reclaimable_bytes": 0,
+ "free_bytes": None,
+ "total_disk_bytes": None,
+ }
+
+ monkeypatch.setattr(settings_route, "cache_inventory", fake_inventory)
+ remote = TestClient(app)
+ assert remote.get("/api/settings/caches?refresh=true").status_code == 403
+ assert asked == []
+ # ...and the ordinary read still answers it.
+ assert remote.get("/api/settings/caches").status_code == 200
+ assert asked == [False]
diff --git a/studio/backend/tests/test_cache_inventory.py b/studio/backend/tests/test_cache_inventory.py
new file mode 100644
index 00000000000..fbf503734cb
--- /dev/null
+++ b/studio/backend/tests/test_cache_inventory.py
@@ -0,0 +1,1829 @@
+# 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 may be deleted, and only ones this backend resolved itself.
+
+The purge takes a cache KEY and turns it into a directory here, so these tests
+cover the two halves that keep that honest: the sizing that decides what the UI
+offers, and every refusal that stands between a key and an rmtree.
+"""
+
+import os
+import sys
+from pathlib import Path
+
+import pytest
+
+from utils import cache_inventory
+from utils.cache_inventory import (
+ CACHE_KEYS,
+ CachePurgeRefused,
+ assert_purgeable_root,
+ cache_inventory as build_inventory,
+ definition_for,
+ describe_cache,
+ empty_cache_root,
+ purge_caches,
+)
+
+
+def _write(path: Path, text: str = "x") -> Path:
+ path.parent.mkdir(parents = True, exist_ok = True)
+ path.write_text(text, encoding = "utf-8")
+ return path
+
+
+def isolated_caches(tmp_path, monkeypatch):
+ """Point every resolver at tmp_path, so no test can reach a real cache.
+
+ The host running these tests has real HF_HOME / XDG_CACHE_HOME values, and
+ the resolvers are supposed to honour exactly those, so the isolation has to
+ be as complete as it is here.
+ """
+ from utils import cache_cleanup, hf_cache_settings
+
+ hf_home = tmp_path / "hf"
+ (hf_home / "hub").mkdir(parents = True)
+ (hf_home / "xet").mkdir()
+ paths = hf_cache_settings.HuggingFaceCachePaths(
+ hf_home, hf_home / "hub", hf_home / "xet", "studio"
+ )
+ monkeypatch.setattr(hf_cache_settings, "get_hf_cache_paths", lambda: paths)
+ monkeypatch.setattr(hf_cache_settings, "known_hf_cache_homes", lambda: [hf_home])
+ monkeypatch.setattr(hf_cache_settings, "known_hf_hub_caches", lambda: [hf_home / "hub"])
+ # The compiled cache is cleared through cache_cleanup's own ownership model,
+ # which test_cache_cleanup covers; here it must simply not reach a real one.
+ monkeypatch.setattr(cache_cleanup, "_cleanable_cache_dirs", lambda: [])
+ monkeypatch.setenv("HOME", str(tmp_path))
+ monkeypatch.setenv("XDG_CACHE_HOME", str(tmp_path / "xdg"))
+ for key in ("HF_HOME", "HF_HUB_CACHE", "HUGGINGFACE_HUB_CACHE"):
+ monkeypatch.delenv(key, raising = False)
+ for key, name in (
+ ("HF_DATASETS_CACHE", "hf/datasets"),
+ ("HF_ASSETS_CACHE", "hf/assets"),
+ ("HF_XET_CACHE", "hf/xet"),
+ ("UV_CACHE_DIR", "uv"),
+ ("PIP_CACHE_DIR", "pip"),
+ ("TORCHINDUCTOR_CACHE_DIR", "inductor"),
+ ("TORCH_EXTENSIONS_DIR", "torchext"),
+ ("TRITON_CACHE_DIR", "triton"),
+ ("CUDA_CACHE_PATH", "cuda"),
+ ("NUMBA_CACHE_DIR", "numba"),
+ ("VLLM_CACHE_ROOT", "vllm"),
+ ("npm_config_cache", "npm"),
+ ("BUN_INSTALL_CACHE_DIR", "bun"),
+ ):
+ monkeypatch.setenv(key, str(tmp_path / name))
+ monkeypatch.delenv("MPLCONFIGDIR", raising = False)
+ # Sizes are memoized for a minute in production; a test must never read one
+ # another test measured.
+ monkeypatch.setattr(cache_inventory, "_size_cache", {})
+ monkeypatch.setattr(cache_inventory, "_size_epochs", {})
+ return hf_home
+
+
+# --- sizing ---------------------------------------------------------------
+
+
+def test_a_cache_is_sized_from_its_own_bytes(tmp_path, monkeypatch, isolated_caches):
+ root = tmp_path / "uv"
+ _write(root / "a.bin", "a" * 100)
+ _write(root / "nested" / "b.bin", "b" * 50)
+ entry = describe_cache(definition_for("uv"))
+ assert entry["present"] is True
+ assert entry["size_bytes"] == 150
+ # Top-level entries: the file and the directory, not every leaf below it.
+ assert entry["entry_count"] == 2
+ assert entry["purgeable"] is True
+
+
+def test_sizing_does_not_follow_a_symlink_out_of_the_cache(tmp_path, isolated_caches):
+ outside = tmp_path / "outside"
+ _write(outside / "big.bin", "z" * 4096)
+ root = tmp_path / "uv"
+ root.mkdir()
+ (root / "escape").symlink_to(outside, target_is_directory = True)
+ _write(root / "real.bin", "r" * 10)
+ entry = describe_cache(definition_for("uv"))
+ assert entry["size_bytes"] == 10
+
+
+def test_hardlinked_blobs_are_counted_once(tmp_path, isolated_caches):
+ root = tmp_path / "uv"
+ blob = _write(root / "blobs" / "sha", "q" * 500)
+ (root / "snapshots").mkdir()
+ os.link(blob, root / "snapshots" / "model.bin")
+ entry = describe_cache(definition_for("uv"))
+ assert entry["size_bytes"] == 500
+
+
+def test_an_absent_cache_reports_no_paths(tmp_path, isolated_caches):
+ entry = describe_cache(definition_for("bun"))
+ assert entry["present"] is False
+ assert entry["paths"] == []
+ assert entry["size_bytes"] == 0
+
+
+def test_the_inventory_totals_exclude_the_opt_in_caches(tmp_path, isolated_caches):
+ _write(tmp_path / "uv" / "a.bin", "a" * 100)
+ _write(isolated_caches / "hub" / "models--x" / "w.bin", "m" * 900)
+ inventory = build_inventory(refresh = True)
+ by_key = {entry["key"]: entry for entry in inventory["caches"]}
+ assert by_key["hf_hub"]["opt_in"] is True
+ assert by_key["hf_hub"]["size_bytes"] == 900
+ assert inventory["total_bytes"] == 1000
+ # Reclaimable is what a bulk purge would actually free, so the cache whose
+ # deletion re-downloads models is not in it.
+ assert inventory["reclaimable_bytes"] == 100
+
+
+def test_every_key_the_api_exposes_has_a_definition():
+ assert len(CACHE_KEYS) == len(set(CACHE_KEYS))
+ for key in CACHE_KEYS:
+ assert definition_for(key).key == key
+
+
+# --- refusals -------------------------------------------------------------
+
+
[email protected]("raw", ["/", "/home", os.path.expanduser("~")])
+def test_a_root_at_or_near_the_filesystem_root_is_refused(raw):
+ with pytest.raises(CachePurgeRefused):
+ assert_purgeable_root(Path(raw))
+
+
+def test_a_shallow_root_is_refused_even_when_nothing_protects_it(tmp_path):
+ # One component below the anchor ("/mnt", "C:\\Users"): not a protected
+ # location, a real directory, and never a cache. The depth rule is the only
+ # thing between a variable pointed there and an rmtree of the 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})")
+ with pytest.raises(CachePurgeRefused) as excinfo:
+ assert_purgeable_root(shallow, protected = set(), trees = set())
+ assert "too close to the filesystem root" in str(excinfo.value)
+
+
+def test_a_relative_root_is_refused():
+ with pytest.raises(CachePurgeRefused):
+ assert_purgeable_root(Path("relative/cache"))
+
+
+def test_a_root_holding_studio_data_is_refused(tmp_path, monkeypatch):
+ from utils.paths.storage_roots import studio_root
+
+ home = studio_root()
+ home.mkdir(parents = True, exist_ok = True)
+ _write(home / "studio.db", "sqlite")
+ with pytest.raises(CachePurgeRefused) as excinfo:
+ assert_purgeable_root(home)
+ assert "protected" in str(excinfo.value)
+
+
+def test_a_root_inside_the_projects_folder_is_refused(tmp_path, monkeypatch):
+ projects = tmp_path / "Projects"
+ (projects / "my-run" / "cache").mkdir(parents = True)
+ monkeypatch.setenv("UNSLOTH_STUDIO_PROJECTS_HOME", str(projects))
+ with pytest.raises(CachePurgeRefused) as excinfo:
+ assert_purgeable_root(projects / "my-run" / "cache")
+ assert "protected folder" in str(excinfo.value)
+
+
+def test_a_symlinked_cache_root_is_refused(tmp_path):
+ target = tmp_path / "somewhere" / "deep"
+ target.mkdir(parents = True)
+ link = tmp_path / "link"
+ link.symlink_to(target, target_is_directory = True)
+ with pytest.raises(CachePurgeRefused) as excinfo:
+ assert_purgeable_root(link)
+ assert "symlink" in str(excinfo.value)
+
+
+def test_the_purge_api_takes_keys_and_never_a_path():
+ from routes.settings import CachePurgePayload
+
+ assert set(CachePurgePayload.model_fields) == {"keys"}
+ with pytest.raises(ValueError) as excinfo:
+ purge_caches(["/"])
+ assert "Unknown cache key" in str(excinfo.value)
+ with pytest.raises(ValueError):
+ purge_caches([os.path.expanduser("~")])
+ with pytest.raises(ValueError):
+ purge_caches(["../../etc"])
+
+
+def test_an_unknown_key_deletes_nothing_from_the_valid_ones(tmp_path, isolated_caches):
+ kept = _write(tmp_path / "uv" / "a.bin", "a" * 100)
+ with pytest.raises(ValueError):
+ purge_caches(["uv", "not_a_cache"])
+ assert kept.exists()
+
+
+# --- deletion behaviour ---------------------------------------------------
+
+
+def test_a_purge_empties_the_root_without_removing_it(tmp_path, isolated_caches):
+ root = tmp_path / "uv"
+ _write(root / "a.bin", "a" * 100)
+ _write(root / "sub" / "b.bin", "b" * 20)
+ result = purge_caches(["uv"])
+ assert root.is_dir()
+ assert list(root.iterdir()) == []
+ assert result["freed_bytes"] == 120
+ assert result["results"][0]["errors"] == []
+
+
+def test_a_symlink_inside_the_cache_is_unlinked_and_never_followed(tmp_path, isolated_caches):
+ outside = tmp_path / "precious"
+ kept_file = _write(outside / "model.safetensors", "weights")
+ root = tmp_path / "uv"
+ root.mkdir()
+ (root / "escape").symlink_to(outside, target_is_directory = True)
+ (root / "escape-file").symlink_to(kept_file)
+ purge_caches(["uv"])
+ assert kept_file.exists()
+ assert outside.is_dir()
+ assert not (root / "escape").exists()
+ assert not (root / "escape").is_symlink()
+ assert not (root / "escape-file").is_symlink()
+
+
+def test_a_purge_leaves_the_database_models_projects_and_token_alone(
+ tmp_path, monkeypatch, isolated_caches
+):
+ from utils.paths.storage_roots import studio_root
+
+ home = studio_root()
+ home.mkdir(parents = True, exist_ok = True)
+ database = _write(home / "studio.db", "sqlite")
+ chat_history = _write(home / "chat" / "thread.json", "hello")
+ token = _write(isolated_caches / "token", "hf_secret")
+ model = _write(isolated_caches / "hub" / "models--unsloth--x" / "blobs" / "abc", "weights" * 10)
+ projects = tmp_path / "Projects"
+ monkeypatch.setenv("UNSLOTH_STUDIO_PROJECTS_HOME", str(projects))
+ project_file = _write(projects / "run" / "adapter.safetensors", "lora")
+ dataset = _write(tmp_path / "hf" / "datasets" / "ds" / "data.arrow", "rows")
+ cache_file = _write(tmp_path / "uv" / "wheel.whl", "cached")
+
+ bulk = [key for key in CACHE_KEYS if not definition_for(key).opt_in]
+ purge_caches(bulk)
+
+ assert not cache_file.exists()
+ for survivor in (database, chat_history, token, model, project_file, dataset):
+ assert survivor.exists(), f"{survivor} was deleted by a cache purge"
+
+
+def test_clearing_the_hub_cache_is_asked_for_by_itself(tmp_path, isolated_caches):
+ token = _write(isolated_caches / "token", "hf_secret")
+ blob = _write(isolated_caches / "hub" / "models--x" / "blobs" / "abc", "weights")
+ purge_caches(["hf_hub"])
+ assert not blob.exists()
+ assert (isolated_caches / "hub").is_dir()
+ # The token lives in the cache HOME, one level above the hub cache.
+ assert token.exists()
+
+
+def test_a_refused_root_reports_itself_and_deletes_nothing(tmp_path, monkeypatch, isolated_caches):
+ outputs = tmp_path / "outputs"
+ monkeypatch.setattr(
+ cache_inventory,
+ "protected_trees",
+ lambda: {Path(os.path.realpath(outputs))},
+ )
+ kept = _write(outputs / "triton" / "kernel.cubin", "compiled")
+ monkeypatch.setenv("TRITON_CACHE_DIR", str(outputs / "triton"))
+ entry = describe_cache(definition_for("triton"))
+ assert entry["purgeable"] is False
+ assert "protected folder" in entry["blocked_reason"]
+ result = purge_caches(["triton"])
+ assert kept.exists()
+ assert result["freed_bytes"] == 0
+ assert result["results"][0]["errors"]
+
+
+def only_the_configured_compiled_cache(monkeypatch, tmp_path):
+ """Keep the compiled-cache clear off any install-tree cache of this checkout.
+
+ cache_cleanup's own ownership model stays in force: that is the thing under
+ test here, and re-deriving it in cache_inventory is exactly what this
+ feature must not do.
+
+ _configured_cache_dirs also offers the CWD, and importing unsloth creates a
+ compiled cache there, so these run from a directory that has none. Skipping
+ on one instead meant they never ran at all.
+ """
+ from utils import cache_cleanup
+
+ monkeypatch.setattr(cache_cleanup, "_CACHE_DIRS", [])
+ monkeypatch.chdir(tmp_path)
+
+
+def test_the_compiled_cache_is_cleared_through_the_module_that_owns_it(
+ tmp_path, monkeypatch, only_the_configured_compiled_cache
+):
+ from utils import cache_cleanup
+
+ compiled = tmp_path / "compiled_cache"
+ compiled.mkdir()
+ (compiled / cache_cleanup.CACHE_MARKER).touch()
+ generated = _write(compiled / "unsloth_compiled_module_llama.py", "compiled" * 10)
+ monkeypatch.setenv("UNSLOTH_COMPILE_LOCATION", str(compiled))
+
+ entry = describe_cache(definition_for("unsloth_compiled"))
+ assert entry["present"] is True
+ assert entry["size_bytes"] >= 80
+
+ result = purge_caches(["unsloth_compiled"])
+ assert result["results"][0]["errors"] == []
+ assert not generated.exists()
+ # The marker is rewritten, so the next cleanup still knows the directory is ours.
+ assert (compiled / cache_cleanup.CACHE_MARKER).is_file()
+
+
+def test_a_shared_compiled_cache_only_loses_the_generated_modules(
+ tmp_path, monkeypatch, only_the_configured_compiled_cache
+):
+ shared = tmp_path / "somebody-elses-folder"
+ shared.mkdir()
+ generated = _write(shared / "unsloth_compiled_module_llama.py", "compiled")
+ mine = _write(shared / "my_notes.py", "print('hello')")
+ monkeypatch.setenv("UNSLOTH_COMPILE_LOCATION", str(shared))
+
+ purge_caches(["unsloth_compiled"])
+ assert not generated.exists()
+ assert mine.exists()
+
+
+def test_a_pattern_limited_root_keeps_the_files_that_are_not_cache(tmp_path, monkeypatch):
+ config_dir = tmp_path / "mplconfig"
+ monkeypatch.setenv("MPLCONFIGDIR", str(config_dir))
+ style = _write(config_dir / "matplotlibrc", "font.size: 12")
+ fontlist = _write(config_dir / "fontlist-v390.json", "{}")
+ empty_cache_root(config_dir, patterns = cache_inventory.MATPLOTLIB_PATTERNS)
+ assert style.exists()
+ assert not fontlist.exists()
+
+
+def test_the_root_of_a_purged_cache_is_never_the_deletion_target(tmp_path, isolated_caches):
+ root = tmp_path / "uv"
+ _write(root / "a.bin", "a")
+ before = root.stat().st_ino
+ purge_caches(["uv"])
+ assert root.is_dir()
+ # Same directory, not a recreated one: nothing recreates it with different
+ # ownership or permissions.
+ assert root.stat().st_ino == before
+
+
+def test_a_purge_forgets_the_size_it_measured_before_it(tmp_path, isolated_caches):
+ _write(tmp_path / "uv" / "a.bin", "a" * 100)
+ assert build_inventory()["total_bytes"] == 100
+ result = purge_caches(["uv"])
+ # The inventory the purge returns cannot still offer the 100 bytes it just
+ # deleted, even though the memo was warm.
+ assert result["inventory"]["total_bytes"] == 0
+ assert build_inventory()["total_bytes"] == 0
+
+
+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
+
+ inventory = build_inventory()
+ bulk = {
+ entry["key"]
+ for entry in inventory["caches"]
+ if entry["present"] and entry["purgeable"] and not entry["opt_in"]
+ }
+ assert "unsloth_compiled" not in bulk
+
+ # ...and it is still individually purgeable, or the row would be dead.
+ entry = next(e for e in inventory["caches"] if e["key"] == "unsloth_compiled")
+ assert entry["opt_in"] is True
+
+
+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")
+ junction = tmp_path / "cache"
+ junction.mkdir()
+
+ # os.path.isjunction is the 3.12+ answer and is always False on POSIX, so
+ # the platform test is what a Windows host would report here.
+ monkeypatch.setattr(os.path, "isjunction", lambda path: Path(path) == junction, raising = False)
+ assert not junction.is_symlink()
+
+ with pytest.raises(CachePurgeRefused) as excinfo:
+ assert_purgeable_root(junction)
+ assert "junction" in str(excinfo.value)
+ assert kept.exists()
+
+
+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)
+ dataset_file = _write(datasets / "squad" / "data.arrow", "d" * 10)
+ monkeypatch.setenv("HF_DATASETS_CACHE", str(datasets))
+
+ described = describe_cache(definition_for("uv"))
+ assert described["purgeable"] is False
+ assert "opt-in cache" in (described["blocked_reason"] or "")
+
+ result = purge_caches(["uv"])
+ assert dataset_file.exists()
+ assert result["freed_bytes"] == 0
+
+ # ...and the nested cache is still clearable when it is the one asked for.
+ purge_caches(["hf_datasets"])
+ assert not dataset_file.exists()
+
+
+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"
+ _write(hub / "models--org--model" / "blob", "m" * 10)
+ paths = hf_cache_settings.HuggingFaceCachePaths(
+ hub, hub, tmp_path / "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: [hub])
+
+ described = describe_cache(definition_for("hf_hub"))
+ assert described["purgeable"] is True, described["blocked_reason"]
+
+ # ...and the HF home that holds the token is still refused.
+ with pytest.raises(CachePurgeRefused):
+ assert_purgeable_root(isolated_caches)
+
+
+# --- resolvers ------------------------------------------------------------
+
+
+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)
+ monkeypatch.delenv("USER", raising = False)
+ monkeypatch.delenv("USERNAME", raising = False)
+ monkeypatch.setenv("LOGNAME", "root")
+ monkeypatch.setattr(tempfile, "gettempdir", lambda: str(tmp_path))
+ root = tmp_path / "torchinductor_root"
+ _write(root / "fxgraph" / "entry.bin", "c" * 20)
+
+ entry = describe_cache(definition_for("torch_inductor"))
+ assert entry["paths"] == [str(root)]
+ assert entry["size_bytes"] == 20
+
+
[email protected]("platform", ["linux", "darwin", "win32"])
+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)
+ monkeypatch.delenv("XDG_CACHE_HOME", raising = False)
+ monkeypatch.setattr(_sys, "platform", platform)
+ assert cache_inventory._vllm_dirs() == [tmp_path / ".cache" / "vllm"]
+
+
+def test_the_vllm_cache_honours_xdg_because_vllm_does(tmp_path, monkeypatch, isolated_caches):
+ monkeypatch.delenv("VLLM_CACHE_ROOT", raising = False)
+ monkeypatch.setenv("XDG_CACHE_HOME", str(tmp_path / "xdg"))
+ assert cache_inventory._vllm_dirs() == [tmp_path / "xdg" / "vllm"]
+
+
+# --- what a refusal costs -------------------------------------------------
+
+
+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))}
+ )
+ _write(outputs / "triton" / "kernel.cubin", "compiled" * 100)
+ monkeypatch.setenv("TRITON_CACHE_DIR", str(outputs / "triton"))
+
+ walked = []
+ measure = cache_inventory._measure_root
+ monkeypatch.setattr(
+ cache_inventory,
+ "_measure_root",
+ lambda root, **kwargs: (walked.append(root), measure(root, **kwargs))[1],
+ )
+
+ entry = describe_cache(definition_for("triton"))
+ assert entry["purgeable"] is False
+ assert walked == []
+ assert entry["size_bytes"] == 0
+
+
+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"
+ kept = _write(documents / "archive" / "taxes.pdf", "mine")
+ monkeypatch.setattr(storage_roots, "documents_root", lambda: documents)
+ monkeypatch.setenv("UV_CACHE_DIR", str(documents / "archive"))
+
+ entry = describe_cache(definition_for("uv"))
+ assert entry["purgeable"] is False
+ assert "protected folder" in (entry["blocked_reason"] or "")
+ purge_caches(["uv"])
+ assert kept.exists()
+
+
+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)
+ monkeypatch.setattr(cache_inventory, "_is_junction", lambda path: Path(path).name == "junction")
+
+ entry = describe_cache(definition_for("uv"))
+ assert entry["size_bytes"] == 10
+
+
+# --- reporting ------------------------------------------------------------
+
+
+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"
+ compiled.mkdir()
+ (compiled / cache_cleanup.CACHE_MARKER).touch()
+ survivor = _write(compiled / "unsloth_compiled_module_llama.py", "compiled" * 10)
+ monkeypatch.setenv("UNSLOTH_COMPILE_LOCATION", str(compiled))
+ monkeypatch.setattr(cache_cleanup, "clear_unsloth_compiled_cache", lambda *a, **k: None)
+
+ result = purge_caches(["unsloth_compiled"])["results"][0]
+ assert survivor.exists()
+ assert result["removed_entries"] == 0
+ assert result["errors"]
+
+
+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)
+ before = inventory_scan.hf_cache_scans_epoch()
+ purge_caches(["hf_hub"])
+ assert inventory_scan.hf_cache_scans_epoch() > before
+
+ # ...and a cache that holds no repository does not disturb it.
+ steady = inventory_scan.hf_cache_scans_epoch()
+ _write(tmp_path / "uv" / "wheel.whl", "w" * 10)
+ purge_caches(["uv"])
+ assert inventory_scan.hf_cache_scans_epoch() == steady
+
+
+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)
+ kept = _write(config / "matplotlibrc", "backend: Agg")
+ fonts = _write(config / "fontlist-v390.json", "[]" * 10)
+ monkeypatch.setenv("MPLCONFIGDIR", str(config))
+
+ described = describe_cache(definition_for("uv"))
+ assert described["purgeable"] is False
+ assert "matplotlib cache" in (described["blocked_reason"] or "")
+ result = purge_caches(["uv"])
+ assert kept.exists()
+ assert result["freed_bytes"] == 0
+
+ # ...and its own clear still takes the cache files and leaves the config.
+ purge_caches(["matplotlib"])
+ assert kept.exists()
+ assert not fonts.exists()
+
+
+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"
+ theirs = _write(previous / "assets" / "someone-elses.bin", "d" * 10)
+ _write(previous / "hub" / "models--org--model" / "blob", "m" * 10)
+ mine = _write(isolated_caches / "assets" / "asset.bin", "a" * 10)
+ monkeypatch.setattr(
+ hf_cache_settings, "known_hf_cache_homes", lambda: [isolated_caches, previous]
+ )
+ monkeypatch.setattr(
+ hf_cache_settings,
+ "known_hf_hub_caches",
+ lambda: [isolated_caches / "hub", previous / "hub"],
+ )
+ monkeypatch.delenv("HF_ASSETS_CACHE", raising = False)
+ # What initialize_hf_cache_environment leaves behind at startup.
+ monkeypatch.setenv("HF_HOME", str(isolated_caches))
+
+ assets = describe_cache(definition_for("hf_assets"))
+ assert assets["paths"] == [str(isolated_caches / "assets")]
+ hub = describe_cache(definition_for("hf_hub"))
+ assert hub["paths"] == [str(isolated_caches / "hub")]
+
+ purge_caches(["hf_assets", "hf_hub"])
+ assert not mine.exists()
+ assert theirs.exists()
+
+ # ...and a home that was left behind is still refused outright.
+ with pytest.raises(CachePurgeRefused):
+ assert_purgeable_root(previous)
+
+
+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
+
+ configured = tmp_path / "corp-pip-cache"
+ _write(configured / "wheels" / "cached.whl", "p" * 40)
+ monkeypatch.delenv("PIP_CACHE_DIR", raising = False)
+ monkeypatch.setattr(module, "_probed_cache_dirs", {})
+ monkeypatch.setattr(
+ module.subprocess,
+ "run",
+ lambda *a, **k: real_subprocess.CompletedProcess(a[0], 0, f"{configured}\n", ""),
+ )
+
+ entry = describe_cache(definition_for("pip"))
+ assert entry["paths"] == [str(configured)]
+ assert entry["size_bytes"] == 40
+
+
+def test_the_pip_probe_runs_once_and_survives_a_failure(tmp_path, monkeypatch, isolated_caches):
+ from utils import cache_inventory as module
+
+ calls = []
+ monkeypatch.delenv("PIP_CACHE_DIR", raising = False)
+ monkeypatch.setattr(module, "_probed_cache_dirs", {})
+
+ def explode(*args, **kwargs):
+ calls.append(args)
+ raise OSError("no pip here")
+
+ monkeypatch.setattr(module.subprocess, "run", explode)
+ probe = ["python", "-m", "pip", "cache", "dir"]
+ assert module._probe_tool_cache_dir("pip", probe) is None
+ assert module._probe_tool_cache_dir("pip", probe) is None
+ assert len(calls) == 1
+ # ...and the platform default still answers, so the row does not vanish.
+ assert module._pip_dirs() == [tmp_path / "xdg" / "pip"]
+
+
+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"
+ hub = project / "hub"
+ hub.mkdir(parents = True)
+ theirs = _write(project / "assets" / "not-a-cache.bin", "d" * 10)
+ real_home = tmp_path / "xdg" / "huggingface"
+ mine = _write(real_home / "assets" / "asset.bin", "a" * 10)
+
+ paths = hf_cache_settings.HuggingFaceCachePaths(
+ project, hub, real_home / "xet", "environment", "HF_HUB_CACHE"
+ )
+ monkeypatch.setattr(hf_cache_settings, "get_hf_cache_paths", lambda: paths)
+ monkeypatch.setattr(hf_cache_settings, "_EXPLICIT_CACHE_ENV", {"HF_HUB_CACHE": str(hub)})
+ monkeypatch.delenv("HF_ASSETS_CACHE", raising = False)
+ monkeypatch.setenv("HF_HOME", str(real_home))
+
+ entry = describe_cache(definition_for("hf_assets"))
+ assert entry["paths"] == [str(real_home / "assets")]
+ purge_caches(["hf_assets"])
+ assert theirs.exists()
+ assert not mine.exists()
+
+
+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")
+ real_describe = cache_inventory.describe_cache
+ before_the_purge = real_describe(definition)
+ assert before_the_purge["size_bytes"] == 100
+
+ def measure_then_purge(_definition):
+ # The purge lands while this walk is still running.
+ for child in root.iterdir():
+ child.unlink()
+ cache_inventory.invalidate_cache_size("uv")
+ return before_the_purge
+
+ monkeypatch.setattr(cache_inventory, "describe_cache", measure_then_purge)
+ assert cache_inventory._described(definition, refresh = True)["size_bytes"] == 100
+ monkeypatch.setattr(cache_inventory, "describe_cache", real_describe)
+ assert cache_inventory._described(definition, refresh = False)["size_bytes"] == 0
+
+
+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
+
+ seen = {}
+ configured = tmp_path / "caché-pip"
+ _write(configured / "wheels" / "cached.whl", "p" * 40)
+ monkeypatch.delenv("PIP_CACHE_DIR", raising = False)
+ monkeypatch.setattr(module, "_probed_cache_dirs", {})
+
+ def record(*args, **kwargs):
+ seen.update(kwargs)
+ return real_subprocess.CompletedProcess(args[0], 0, f"{configured}\n", "")
+
+ monkeypatch.setattr(module.subprocess, "run", record)
+ entry = describe_cache(definition_for("pip"))
+
+ assert entry["paths"] == [str(configured)]
+ assert seen["encoding"] == "utf-8"
+ assert seen["env"]["PYTHONIOENCODING"] == "utf-8"
+
+
+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"
+ fallback = studio_cache / "hf-datasets"
+ in_flight = _write(fallback / "squad" / "data.arrow", "d" * 10)
+ stable = _write(isolated_caches / "datasets" / "cached.arrow", "s" * 10)
+ monkeypatch.setattr(storage_roots, "cache_root", lambda: studio_cache)
+ monkeypatch.setenv("HF_HOME", str(isolated_caches))
+ # The override is live, exactly as it is while the fallback load runs.
+ monkeypatch.setenv("HF_DATASETS_CACHE", str(fallback))
+
+ entry = describe_cache(definition_for("hf_datasets"))
+ assert entry["paths"] == [str(isolated_caches / "datasets")]
+ purge_caches(["hf_datasets"])
+ assert in_flight.exists()
+ assert not stable.exists()
+
+
+ "platform,name,expected,patterned",
+ [
+ ("linux", "posix", ".cache/matplotlib", False),
+ ("darwin", "posix", ".matplotlib", True),
+ ("win32", "nt", ".matplotlib", True),
+ ],
+)
+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
+
+ monkeypatch.delenv("MPLCONFIGDIR", raising = False)
+ monkeypatch.delenv("XDG_CACHE_HOME", raising = False)
+ monkeypatch.setattr(_sys, "platform", platform)
+ monkeypatch.setattr(module, "_is_windows", lambda: name == "nt")
+ (tmp_path / ".matplotlib").mkdir(exist_ok = True)
+
+ assert module._matplotlib_dirs() == [tmp_path / expected]
+ assert (module._matplotlib_patterns() is not None) is patterned
+
+
+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
+
+ monkeypatch.delenv("CUDA_CACHE_PATH", raising = False)
+ monkeypatch.setattr(module, "_is_windows", lambda: True)
+ monkeypatch.setenv("APPDATA", str(tmp_path / "AppData" / "Roaming"))
+ monkeypatch.setenv("LOCALAPPDATA", str(tmp_path / "AppData" / "Local"))
+ assert module._cuda_dirs() == [tmp_path / "AppData" / "Roaming" / "NVIDIA" / "ComputeCache"]
+
+ monkeypatch.setattr(module, "_is_windows", lambda: False)
+ monkeypatch.setattr(_sys, "platform", "darwin")
+ assert module._cuda_dirs() == [
+ tmp_path / "Library" / "Application Support" / "NVIDIA" / "ComputeCache"
+ ]
+
+
+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)
+
+ entry = describe_cache(definition_for("numba"))
+ assert entry["paths"] == [str(root)]
+ assert entry["size_bytes"] == 30
+
+
+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"
+ binaries = studio / "bin"
+ shim = _write(binaries / "unsloth", "#!/bin/sh")
+ monkeypatch.setattr(storage_roots, "studio_bin_root", lambda: binaries)
+ monkeypatch.setenv("UV_CACHE_DIR", str(binaries))
+
+ entry = describe_cache(definition_for("uv"))
+ assert entry["purgeable"] is False
+ purge_caches(["uv"])
+ assert shim.exists()
+
+ # ...and nothing below it either.
+ monkeypatch.setenv("UV_CACHE_DIR", str(binaries / "vendor"))
+ (binaries / "vendor").mkdir()
+ with pytest.raises(CachePurgeRefused):
+ assert_purgeable_root(binaries / "vendor")
+
+
+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
+
+ from utils import cache_inventory as module
+
+ configured = tmp_path / "corp-npm"
+ _write(configured / "_cacache" / "index-v5" / "entry", "n" * 25)
+ for key in ("npm_config_cache", "NPM_CONFIG_CACHE"):
+ monkeypatch.delenv(key, raising = False)
+ monkeypatch.setattr(module, "_probed_cache_dirs", {})
+ monkeypatch.setattr(real_shutil, "which", lambda name, **kw: "/usr/bin/npm")
+ monkeypatch.setattr(
+ module.subprocess,
+ "run",
+ lambda *a, **k: real_subprocess.CompletedProcess(a[0], 0, f"{configured}\n", ""),
+ )
+
+ entry = describe_cache(definition_for("npm"))
+ assert entry["paths"] == [str(configured / "_cacache")]
+ assert entry["size_bytes"] == 25
+
+
+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
+
+ monkeypatch.setattr(module, "_probed_cache_dirs", {})
+ monkeypatch.setattr(
+ module.subprocess,
+ "run",
+ lambda *a, **k: real_subprocess.CompletedProcess(a[0], 0, "undefined\n", ""),
+ )
+ assert module._probe_tool_cache_dir("npm", ["npm", "config", "get", "cache"]) is None
+
+
+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"
+ seeded = studio_cache / "uv"
+ warm = tmp_path / "warm-uv"
+ _write(seeded / "seeded.whl", "s" * 10)
+ _write(warm / "archive-v0" / "big.whl", "w" * 900)
+ monkeypatch.setattr(storage_roots, "cache_root", lambda: studio_cache)
+ (studio_cache / "uv-cache-dir").write_text(f"{warm}\n", encoding = "utf-8")
+ monkeypatch.setenv("UV_CACHE_DIR", str(seeded))
+
+ entry = describe_cache(definition_for("uv"))
+ assert entry["paths"] == [str(seeded), str(warm)]
+ assert entry["size_bytes"] == 910
+ purge_caches(["uv"])
+ assert not (warm / "archive-v0").exists()
+ assert seeded.is_dir()
+
+
+def test_a_blank_or_missing_uv_marker_adds_nothing(tmp_path, monkeypatch, isolated_caches):
+ from utils import cache_inventory as module
+ from utils.paths import storage_roots
+
+ studio_cache = tmp_path / "studio-cache"
+ studio_cache.mkdir()
+ monkeypatch.setattr(storage_roots, "cache_root", lambda: studio_cache)
+ assert module._recorded_uv_cache() is None
+ (studio_cache / "uv-cache-dir").write_text(" \n", encoding = "utf-8")
+ assert module._recorded_uv_cache() is None
+
+
+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"
+ in_use = _write(workspace / "decode" / "clip.wav", "a" * 10)
+ monkeypatch.setattr(storage_roots, "tmp_root", lambda: workspace)
+ monkeypatch.setenv("UV_CACHE_DIR", str(workspace / "decode"))
+
+ entry = describe_cache(definition_for("uv"))
+ assert entry["purgeable"] is False
+ purge_caches(["uv"])
+ assert in_use.exists()
+ with pytest.raises(CachePurgeRefused):
+ assert_purgeable_root(workspace)
+
+
+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
+
+ from utils import cache_inventory as module
+
+ configured = tmp_path / "corp-pip"
+ configured.mkdir()
+ monkeypatch.delenv("PIP_CACHE_DIR", raising = False)
+ monkeypatch.setattr(module, "_probed_cache_dirs", {})
+ started = threading.Event()
+ release = threading.Event()
+
+ def slow(*args, **kwargs):
+ started.set()
+ release.wait(5)
+ return real_subprocess.CompletedProcess(args[0], 0, f"{configured}\n", "")
+
+ monkeypatch.setattr(module.subprocess, "run", slow)
+ answers: list = []
+ first = threading.Thread(target = lambda: answers.append(module._pip_dirs()))
+ first.start()
+ assert started.wait(5)
+ second = threading.Thread(target = lambda: answers.append(module._pip_dirs()))
+ second.start()
+ release.set()
+ first.join(10)
+ second.join(10)
+
+ assert answers == [[configured], [configured]]
+
+
+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
+
+ from utils import cache_inventory as module
+
+ diffusion = tmp_path / "diffusion_compile_cache"
+ per_model = diffusion / "abc123" / "inductor"
+ transient = _write(per_model / "graph.bin", "d" * 50)
+ monkeypatch.setattr(tempfile, "gettempdir", lambda: str(tmp_path))
+ stable = tmp_path / f"torchinductor_{getpass.getuser()}"
+ _write(stable / "fx.bin", "s" * 10)
+ monkeypatch.setattr(
+ module, "_diffusion_compile_root", lambda: Path(os.path.realpath(diffusion))
+ )
+ monkeypatch.setenv("TORCHINDUCTOR_CACHE_DIR", str(per_model))
+
+ entry = describe_cache(definition_for("torch_inductor"))
+ assert entry["paths"] == [str(stable)]
+ purge_caches(["torch_inductor"])
+ assert transient.exists()
+
+ # ...and an ordinary override is still followed.
+ elsewhere = tmp_path / "my-inductor"
+ _write(elsewhere / "fx.bin", "e" * 10)
+ monkeypatch.setenv("TORCHINDUCTOR_CACHE_DIR", str(elsewhere))
+ assert describe_cache(definition_for("torch_inductor"))["paths"] == [str(elsewhere)]
+
+
+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)
+ monkeypatch.setenv("HF_ASSETS_CACHE", str(assets))
+ monkeypatch.setenv("HF_TOKEN_PATH", str(token))
+
+ entry = describe_cache(definition_for("hf_assets"))
+ assert entry["purgeable"] is False
+ purge_caches(["hf_assets"])
+ assert token.read_text(encoding = "utf-8") == "hf_secret"
+
+
+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)
+ monkeypatch.setattr(
+ module,
+ "_reserve_downloads",
+ lambda key: ([], "Cancel it.") if key == "hf_hub" else ([], None),
+ )
+ result = purge_caches(["hf_hub"])["results"][0]
+ assert blob.exists()
+ assert result["freed_bytes"] == 0
+ assert result["errors"] == ["Cancel it."]
+
+
+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
+
+ class _Registry:
+ def __init__(self, free = True):
+ self.free = free
+ self.held = 0
+
+ def begin_cache_purge(self):
+ if not self.free:
+ return False
+ self.held += 1
+ return True
+
+ def end_cache_purge(self):
+ self.held -= 1
+
+ models, datasets = _Registry(), _Registry()
+ monkeypatch.setattr(download_registry, "get_models_registry", lambda: models)
+ # The purge reserves datasets through the SERVICE, not the singleton, so that a
+ # managed-account install holds every per-account registry and not just the owner's.
+ # Same stub, attached at the seam the code actually uses.
+ monkeypatch.setattr(download_registry, "get_datasets_registry", lambda: datasets)
+ from hub.services.datasets import downloads as dataset_downloads
+
+ monkeypatch.setattr(dataset_downloads, "begin_cache_purge", datasets.begin_cache_purge)
+ monkeypatch.setattr(dataset_downloads, "end_cache_purge", datasets.end_cache_purge)
+
+ reserved, busy = module._reserve_downloads("hf_hub")
+ assert busy is None
+ assert (models.held, datasets.held) == (1, 1)
+ module._release_downloads(reserved)
+ assert (models.held, datasets.held) == (0, 0)
+
+ # A dataset job alone still holds off the hub clear...
+ datasets.free = False
+ reserved, busy = module._reserve_downloads("hf_hub")
+ assert busy is not None
+ # ...and the models reservation it had already taken is handed back.
+ assert (models.held, datasets.held) == (0, 0)
+
+ # A cache no download writes into is not gated on one.
+ assert module._reserve_downloads("uv") == ([], None)
+
+
+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"
+ good = studio_cache / "uv"
+ documents = tmp_path / "Documents"
+ blocked = documents / "uv-cache"
+ wheel = _write(good / "wheel.whl", "w" * 40)
+ theirs = _write(blocked / "taxes.pdf", "mine")
+ monkeypatch.setattr(storage_roots, "cache_root", lambda: studio_cache)
+ monkeypatch.setattr(storage_roots, "documents_root", lambda: documents)
+ (studio_cache / "uv-cache-dir").write_text(f"{blocked}\n", encoding = "utf-8")
+ monkeypatch.setenv("UV_CACHE_DIR", str(good))
+
+ entry = describe_cache(definition_for("uv"))
+ assert entry["purgeable"] is True
+ assert "protected folder" in (entry["blocked_reason"] or "")
+ assert entry["size_bytes"] == 40
+ purge_caches(["uv"])
+ assert not wheel.exists()
+ assert theirs.exists()
+
+
+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
+
+ _write(tmp_path / "uv" / "wheel.whl", "w" * 10)
+ definition = definition_for("uv")
+ walks: list = []
+ started = threading.Event()
+ release = threading.Event()
+ real_describe = cache_inventory.describe_cache
+
+ def slow(target):
+ walks.append(target.key)
+ started.set()
+ release.wait(5)
+ return real_describe(target)
+
+ monkeypatch.setattr(cache_inventory, "describe_cache", slow)
+ answers: list = []
+ first = threading.Thread(
+ target = lambda: answers.append(module._described(definition, refresh = False))
+ )
+ first.start()
+ assert started.wait(5)
+ second = threading.Thread(
+ target = lambda: answers.append(module._described(definition, refresh = False))
+ )
+ second.start()
+ release.set()
+ first.join(10)
+ second.join(10)
+
+ assert walks == ["uv"]
+ assert [answer["size_bytes"] for answer in answers] == [10, 10]
+
+
+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
+
+ root = tmp_path / "uv"
+ _write(root / "wheel.whl", "w" * 100)
+ definition = definition_for("uv")
+ walks: list = []
+ started = threading.Event()
+ release = threading.Event()
+ real_describe = cache_inventory.describe_cache
+
+ def slow(target):
+ walks.append(len(walks))
+ if not walks[-1]:
+ started.set()
+ release.wait(5)
+ return real_describe(target)
+
+ monkeypatch.setattr(cache_inventory, "describe_cache", slow)
+ sizes: list = []
+ first = threading.Thread(
+ target = lambda: sizes.append(module._described(definition, refresh = False))
+ )
+ first.start()
+ assert started.wait(5)
+ # The cache changes under the walk that is already running.
+ for child in root.iterdir():
+ child.unlink()
+ forced = threading.Thread(
+ target = lambda: sizes.append(module._described(definition, refresh = True))
+ )
+ forced.start()
+ release.set()
+ first.join(10)
+ forced.join(10)
+
+ assert len(walks) == 2
+ assert sizes[-1]["size_bytes"] == 0
+
+
+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"
+ (chosen / "hub").mkdir(parents = True)
+ theirs = _write(chosen / "assets" / "not-a-cache.bin", "d" * 10)
+ real_home = tmp_path / "default-hf"
+ mine = _write(real_home / "assets" / "asset.bin", "a" * 10)
+
+ paths = hf_cache_settings.HuggingFaceCachePaths(
+ chosen, chosen / "hub", real_home / "xet", "studio"
+ )
+ monkeypatch.setattr(hf_cache_settings, "get_hf_cache_paths", lambda: paths)
+ monkeypatch.delenv("HF_ASSETS_CACHE", raising = False)
+ monkeypatch.setenv("HF_HOME", str(real_home))
+
+ entry = describe_cache(definition_for("hf_assets"))
+ assert entry["paths"] == [str(real_home / "assets")]
+ purge_caches(["hf_assets"])
+ assert theirs.exists()
+ assert not mine.exists()
+
+
+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)
+ logs = _write(npm / "_logs" / "debug.log", "l" * 5)
+ monkeypatch.setenv("npm_config_cache", str(npm))
+
+ entry = describe_cache(definition_for("npm"))
+ assert entry["paths"] == [str(npm / "_cacache"), str(npm / "_npx")]
+ assert entry["size_bytes"] == 50
+ purge_caches(["npm"])
+ assert not package.exists()
+ assert not executable.exists()
+ assert logs.exists()
+
+
+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()
+ assert registry.begin_cache_purge() is True
+ claimed, state = registry.claim_repository_owner("org/model", object())
+ assert claimed is False
+ assert state == "deleting"
+
+ # Counted, so two caches sharing this registry nest rather than releasing early.
+ assert registry.begin_cache_purge() is True
+ registry.end_cache_purge()
+ assert registry.claim_repository_owner("org/model", object())[0] is False
+ registry.end_cache_purge()
+ assert registry.claim_repository_owner("org/model", object())[0] is True
+
+ # ...and a purge is refused while that owner holds the repository.
+ assert registry.begin_cache_purge() is False
+
+
+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
+
+ class _Registry:
+ def __init__(self):
+ self.held = 0
+
+ def begin_cache_purge(self):
+ self.held += 1
+ return True
+
+ def end_cache_purge(self):
+ self.held -= 1
+
+ models, datasets = _Registry(), _Registry()
+ monkeypatch.setattr(download_registry, "get_models_registry", lambda: models)
+ # The purge reserves datasets through the SERVICE, not the singleton, so that a
+ # managed-account install holds every per-account registry and not just the owner's.
+ # Same stub, attached at the seam the code actually uses.
+ monkeypatch.setattr(download_registry, "get_datasets_registry", lambda: datasets)
+ from hub.services.datasets import downloads as dataset_downloads
+
+ monkeypatch.setattr(dataset_downloads, "begin_cache_purge", datasets.begin_cache_purge)
+ monkeypatch.setattr(dataset_downloads, "end_cache_purge", datasets.end_cache_purge)
+
+ reserved, busy = module._reserve_downloads("hf_xet")
+ assert busy is None
+ assert (models.held, datasets.held) == (1, 1)
+ module._release_downloads(reserved)
+
+
+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()
+ assert registry.begin_delete("org/model") is True
+ assert registry.begin_cache_purge() is False
+ registry.end_delete("org/model")
+
+ assert registry.begin_cache_purge() is True
+ assert registry.begin_delete("org/model") is False
+ registry.end_cache_purge()
+ assert registry.begin_delete("org/model") is True
+
+
+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
+
+ blob = _write(isolated_caches / "hub" / "models--org--model" / "blob", "m" * 10)
+ wheel = _write(tmp_path / "uv" / "wheel.whl", "w" * 10)
+
+ class _Backend:
+ active = True
+
+ def is_training_active(self):
+ return self.active
+
+ backend = _Backend()
+ monkeypatch.setattr(training_module, "get_training_backend", lambda: backend, raising = False)
+
+ result = purge_caches(["hf_hub"])["results"][0]
+ assert blob.exists()
+ assert result["errors"] == ["Stop the training run before clearing this cache."]
+ for key in ("hf_xet", "hf_datasets"):
+ assert module._training_refusal(key) is not None
+ # A cache no worker of ours writes into is not gated on a run.
+ assert module._training_refusal("uv") is None
+ purge_caches(["uv"])
+ assert not wheel.exists()
+
+ backend.active = False
+ purge_caches(["hf_hub"])
+ assert not blob.exists()
+
+
+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)
+ monkeypatch.setattr(module, "_is_windows", lambda: True)
+ monkeypatch.setenv("LOCALAPPDATA", str(tmp_path / "Local"))
+ assert module._torch_extensions_dirs() == [
+ tmp_path / "Local" / "torch_extensions" / "torch_extensions" / "Cache"
+ ]
+
+ monkeypatch.setattr(module, "_is_windows", lambda: False)
+ monkeypatch.setenv("XDG_CACHE_HOME", str(tmp_path / "xdg"))
+ assert module._torch_extensions_dirs() == [tmp_path / "xdg" / "torch_extensions"]
+
+
+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
+
+ class _Idle:
+ def is_training_active(self):
+ return False
+
+ class _Busy:
+ def is_active(self):
+ return True
+
+ monkeypatch.setattr(training_module, "get_training_backend", lambda: _Idle(), raising = False)
+ monkeypatch.setattr(
+ diffusion_training_service, "get_diffusion_training_service", lambda: _Busy()
+ )
+ for key in ("hf_hub", "hf_xet", "hf_datasets"):
+ assert module._training_refusal(key) is not None
+ assert module._training_refusal("uv") is None
+
+
+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
+
+ documents = tmp_path / "Documents"
+ compiled = documents / "checkout" / "unsloth_compiled_cache"
+ compiled.mkdir(parents = True)
+ (compiled / cache_cleanup.CACHE_MARKER).touch()
+ generated = _write(compiled / "unsloth_compiled_module_llama.py", "compiled" * 10)
+ monkeypatch.setattr(storage_roots, "documents_root", lambda: documents)
+ monkeypatch.setenv("UNSLOTH_COMPILE_LOCATION", str(compiled))
+
+ entry = describe_cache(definition_for("unsloth_compiled"))
+ assert entry["purgeable"] is False
+ assert "protected folder" in (entry["blocked_reason"] or "")
+ assert entry["size_bytes"] == 0
+ result = purge_caches(["unsloth_compiled"])["results"][0]
+ assert generated.exists()
+ assert result["errors"]
+
+
+def test_moving_the_models_folder_forgets_the_old_roots_sizes(
+ tmp_path, monkeypatch, isolated_caches
+):
+ """The memo is keyed by cache, not by path, so nothing about a new root evicts it.
+
+ A browser hides this by forcing a refresh off the inventory-version event. An API-key
+ caller may change the folder and read the inventory but may not pass refresh=true, so
+ without this it reads the previous volume's figures for the rest of the TTL.
+ """
+ from utils import cache_inventory as module
+
+ _write(tmp_path / "hub" / "blob", "b" * 40)
+ definition = definition_for("hf_hub")
+ monkeypatch.setattr(
+ cache_inventory, "describe_cache", lambda target: {"key": target.key, "size_bytes": 40}
+ )
+ assert module._described(definition, refresh = False)["size_bytes"] == 40
+
+ # The folder moves. Same key, different directory, and the walk would now answer 7.
+ monkeypatch.setattr(
+ cache_inventory, "describe_cache", lambda target: {"key": target.key, "size_bytes": 7}
+ )
+ assert module._described(definition, refresh = False)["size_bytes"] == 40, "memo not warm"
+
+ module.invalidate_hf_rooted_sizes()
+ assert module._described(definition, refresh = False)["size_bytes"] == 7
+
+
+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
+ from utils import cache_inventory as module
+ from utils import hf_cache_settings
+
+ called: list = []
+ monkeypatch.setattr(module, "invalidate_hf_rooted_sizes", lambda: called.append("sizes"))
+ monkeypatch.setattr(hf_cache_settings, "_environment_paths", lambda: None)
+ monkeypatch.setattr(hf_cache_settings, "_stored_cache_home", lambda: None)
+ monkeypatch.setattr(hf_cache_settings, "_stored_history", lambda: [])
+ monkeypatch.setattr(studio_db, "upsert_app_settings", lambda _values: None)
+ monkeypatch.setattr(inventory_scan, "invalidate_hf_cache_scans", lambda: None)
+ monkeypatch.setattr(hf_cache_state, "invalidate_partial_resumability", lambda: None)
+
+ hf_cache_settings.set_hf_cache_home(None)
+ assert called == ["sizes"]
+
+
+def test_bytes_still_linked_from_outside_are_not_called_reclaimable(tmp_path, isolated_caches):
+ """uv's default link mode on Windows is hardlink: an installed environment's files ARE
+ links into this cache, so unlinking the cache copy frees nothing.
+
+ Counting them anyway is how a reclaimable total, and the freed_bytes a purge reports,
+ came to overstate by the size of the installed packages.
+ """
+ root = tmp_path / "uv"
+ shared = _write(root / "archive" / "wheel.so", "w" * 800)
+ venv = tmp_path / "venv" / "lib"
+ venv.mkdir(parents = True)
+ os.link(shared, venv / "wheel.so") # the installed environment, outside the cache
+ _write(root / "archive" / "own.bin", "o" * 20)
+
+ entry = describe_cache(definition_for("uv"))
+
+ assert entry["size_bytes"] == 20
+
+
+def test_a_purge_reports_only_the_bytes_it_actually_freed(tmp_path, isolated_caches):
+ root = tmp_path / "uv"
+ shared = _write(root / "archive" / "wheel.so", "w" * 800)
+ venv = tmp_path / "venv" / "lib"
+ venv.mkdir(parents = True)
+ os.link(shared, venv / "wheel.so")
+ _write(root / "archive" / "own.bin", "o" * 20)
+
+ outcome = empty_cache_root(root)
+
+ assert outcome.errors == []
+ assert outcome.freed_bytes == 20
+ assert (venv / "wheel.so").read_text(encoding = "utf-8") == "w" * 800
+
+
+def test_a_whole_hub_clear_waits_for_a_loaded_model(monkeypatch, isolated_caches):
+ """Deleting ONE repo already runs the inference load-state guards.
+
+ Emptying the whole cache is every repo at once, so skipping them was the wider action with
+ the weaker check. sd.cpp re-reads its companion VAE and text-encoder files for every
+ generation, so this breaks a model loaded long before the clear, not only one mid-load.
+ """
+ import hub.services.models.deletion as deletion
+
+ monkeypatch.setattr(
+ deletion, "any_model_load_blocks_cache_clear", lambda: "Unload the model before clearing"
+ )
+ result = cache_inventory.purge_cache("hf_hub")
+
+ assert result["errors"] == ["Unload the model before clearing"]
+ assert result["freed_bytes"] == 0
+
+
+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}
+ resident.update(state)
+ monkeypatch.setattr(stt_registry, "resident", lambda: resident)
+
+
+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() == (
+ "Unload the dictation model before clearing the model cache"
+ )
+
+
+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() == (
+ "A dictation model load is using the cache; wait for it to finish"
+ )
+
+
+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."""
+ from hub.services.models.deletion import any_model_load_blocks_cache_clear
+
+ _idle_dictation(monkeypatch)
+
+ assert any_model_load_blocks_cache_clear() is None
+
+
+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
+
+ def _raise():
+ raise RuntimeError("sidecar wedged")
+
+ monkeypatch.setattr(stt_registry, "resident", _raise)
+
+ assert any_model_load_blocks_cache_clear() is None
+
+
+def test_a_whole_hub_clear_waits_for_a_chat_load_that_has_not_spawned_yet(monkeypatch):
+ """chat_load_active's own docstring: is_active covers a live llama-server process, which an
+ HF-backed load does not have until its GGUF finished downloading. Those minutes are exactly
+ when the bytes are arriving, and they come through hf_hub_download_with_xet_fallback rather
+ than the download registry, so the purge's own reservation does not cover them either."""
+ from core.inference import llama_cpp
+ from hub.services.models.deletion import any_model_load_blocks_cache_clear
+
+ _idle_dictation(monkeypatch)
+ monkeypatch.setattr(llama_cpp, "chat_load_active", lambda: True)
+
+ assert any_model_load_blocks_cache_clear() == (
+ "A model load is using the cache; wait for it to finish"
+ )
+
+
+def test_a_whole_hub_clear_waits_for_a_draining_image_load(monkeypatch):
+ """A cancelled diffusers load leaves loading_repo_ids() immediately but keeps its repos in
+ draining_repo_ids() while the worker thread reads on inside _prefetch_files, holding no lock.
+ _diffusion_blocks_delete already refuses on that, and emptying the whole cache is every repo
+ at once, so it cannot ask less than the per-repository path does."""
+ import types
+
+ from hub.services.models.deletion import any_model_load_blocks_cache_clear
+
+ _idle_dictation(monkeypatch)
+ draining = types.SimpleNamespace(
+ status = lambda: {"loaded": False},
+ loaded_repo_ids = tuple,
+ loading_repo_ids = tuple,
+ draining_repo_ids = lambda: ("black-forest-labs/FLUX.2-klein-4B",),
+ )
+ router = types.ModuleType("core.inference.diffusion_engine_router")
+ router.get_active_diffusion_engine = lambda: draining
+ monkeypatch.setitem(sys.modules, "core.inference.diffusion_engine_router", router)
+
+ assert any_model_load_blocks_cache_clear() == (
+ "An Images model load is still unwinding; wait for it to finish"
+ )
+
+
+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():
+ raise RuntimeError("backend wedged")
+
+ monkeypatch.setattr(deletion, "any_model_load_blocks_cache_clear", _raise)
+ result = cache_inventory.purge_cache("hf_hub")
+
+ assert result["errors"] and "Could not verify" in result["errors"][0]
+
+
+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()
+ (site / "pkg").symlink_to(tmp_path / "uv" / "archive" / "pkg", target_is_directory = True)
+ import sysconfig
+
+ monkeypatch.setattr(sysconfig, "get_paths", lambda *a, **k: {"purelib": str(site)})
+
+ entry = describe_cache(definition_for("uv"))
+ assert entry["purgeable"] is False
+ assert "symlinked" in (entry["blocked_reason"] or "")
+
+ result = cache_inventory.purge_cache("uv")
+ assert result["errors"] and "symlinked" in result["errors"][0]
+ assert (tmp_path / "uv" / "archive" / "pkg" / "__init__.py").exists()
+
+
+def test_the_declared_link_mode_alone_is_enough_to_refuse(tmp_path, monkeypatch, isolated_caches):
+ _write(tmp_path / "uv" / "a.bin", "a" * 10)
+ monkeypatch.setenv("UV_LINK_MODE", "symlink")
+
+ entry = describe_cache(definition_for("uv"))
+
+ assert entry["purgeable"] is False
+ assert "link packages" in (entry["blocked_reason"] or "")
+
+
+def test_an_ordinary_uv_cache_is_still_offered(tmp_path, isolated_caches):
+ _write(tmp_path / "uv" / "a.bin", "a" * 10)
+
+ entry = describe_cache(definition_for("uv"))
+
+ assert entry["purgeable"] is True
+ assert entry["blocked_reason"] is None
+
+
+def test_a_partial_purge_reports_only_what_it_actually_removed(tmp_path, isolated_caches):
+ """rmtree can delete some children and then hit a permission error or a file that moved.
+
+ The whole subtree is measured before the removal, so without subtracting the survivors the
+ toast claimed bytes that are still on disk, which is the one thing a "freed" figure must
+ not do.
+ """
+ root = tmp_path / "uv"
+ _write(root / "tree" / "gone.bin", "g" * 100)
+ stubborn = root / "tree" / "stays"
+ _write(stubborn / "kept.bin", "k" * 40)
+ stubborn.chmod(0o500) # the delete of its child fails, the directory survives
+ try:
+ outcome = empty_cache_root(root)
+ finally:
+ stubborn.chmod(0o700)
+
+ assert outcome.errors, "the removal was expected to fail partway"
+ assert (stubborn / "kept.bin").exists()
+ assert outcome.freed_bytes == 100
+
+
+def test_a_curated_dataset_import_holds_off_a_model_cache_clear():
+ """The curated import calls load_dataset and snapshot_download directly.
+
+ It is not a managed download and not a training run, so it claimed nothing and a Clear of
+ hf_hub, hf_xet or hf_datasets passed every guard: begin_cache_purge asks about jobs, owners
+ and deletes, and this was none of the three. The snapshot then went out from under the copy
+ and the import failed in front of the user.
+ """
+ from hub.utils.download_registry import get_datasets_registry
+
+ registry = get_datasets_registry()
+ owner = object()
+ granted, _ = registry.claim_repository_owner("some/curated-set", owner)
+ assert granted
+ try:
+ assert registry.begin_cache_purge() is False
+ finally:
+ registry.release_repository_owner("some/curated-set", owner)
+ # And once it is done, the clear is allowed again.
+ assert registry.begin_cache_purge() is True
+ registry.end_cache_purge()
+
+
+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."""
+ import ast
+ import inspect
+
+ import routes.training as training
+
+ source = inspect.getsource(training)
+ tree = ast.parse(source)
+ calls = {
+ node.func.attr
+ for node in ast.walk(tree)
+ if isinstance(node, ast.Call) and isinstance(node.func, ast.Attribute)
+ }
+ assert "claim_repository_owner" in calls
+ assert "release_repository_owner" in calls
+ # Released in a finally, or a failed import leaves the cache reserved for the process's life.
+ start = source.index("claim_repository_owner")
+ tail = source[start:]
+ assert "finally:" in tail[: tail.index("release_repository_owner")]
+
+
+def test_every_account_dataset_registry_is_reserved_by_a_purge(monkeypatch):
+ """A managed-account install has one dataset registry PER ACCOUNT, not one in total.
+
+ _account_registry() builds a fresh DownloadRegistry the first time each account downloads,
+ so reserving only the singleton left every other account's download invisible to the purge,
+ which would then remove files under its worker.
+ """
+ from hub.services.datasets import downloads as dataset_downloads
+ from hub.utils import download_registry
+
+ other = download_registry.DownloadRegistry()
+ monkeypatch.setitem(dataset_downloads._account_registries, "account-2", other)
+
+ # A download running for that OTHER account.
+ granted, _ = other.claim_repository_owner("some/set", object())
+ assert granted
+
+ assert (
+ dataset_downloads.begin_cache_purge() is False
+ ), "the purge was granted while another account's dataset download held its own registry"
+
+
+def test_a_registry_created_during_a_purge_is_born_reserved(monkeypatch):
+ """The other half: an account whose first download starts AFTER the purge began.
+
+ Reserving the registries that exist at the moment the purge starts is not enough, because
+ _account_registry() mints new ones on demand. The existing code already carries _deleting
+ into a new registry for exactly this reason; the purge count rides along the same way.
+ """
+ from hub.services.datasets import downloads as dataset_downloads
+ from hub.utils import download_registry
+
+ monkeypatch.setattr(dataset_downloads, "_account_registries", {})
+ assert dataset_downloads.begin_cache_purge() is True
+ try:
+ fresh = download_registry.DownloadRegistry()
+ for _ in range(dataset_downloads._purging):
+ fresh.begin_cache_purge()
+ # Born reserved: it must refuse to hand work out while the purge is still running.
+ assert fresh.claim_repository_owner("late/set", object()) == (False, "deleting")
+ finally:
+ dataset_downloads.end_cache_purge()
diff --git a/studio/backend/utils/cache_inventory.py b/studio/backend/utils/cache_inventory.py
new file mode 100644
index 00000000000..854fadc0e6e
--- /dev/null
+++ b/studio/backend/utils/cache_inventory.py
@@ -0,0 +1,1412 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""Size and empty the caches this install fills up, and nothing else.
+
+The API takes a KEY, never a path, and this module is the only thing that turns
+one into a directory, so "may this be deleted" is answered from the resolved
+directory rather than from what was asked for. The rules, in order:
+
+* The key is one of ``CACHE_DEFINITIONS``.
+* Its root is an absolute existing directory, at least two components below the
+ filesystem anchor, and neither a symlink nor a Windows junction.
+* It is not, and does not contain, anything in ``protected_paths()``.
+* It does not sit inside anything in ``protected_trees()``.
+* It does not contain another key's root whose own clear is narrower than
+ emptying it (``sheltered_roots``).
+* It is emptied, never removed, so nothing recreates it with the wrong
+ permissions.
+* A symlink inside it is unlinked rather than followed, and a directory whose
+ real path leaves it is skipped.
+"""
+
+from __future__ import annotations
+
+import fnmatch
+import os
+import shutil
+import stat
+import subprocess
+import sys
+import threading
+import time
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Callable, Iterable, Optional
+
+from loggers import get_logger
+
+logger = get_logger(__name__)
+
+GROUP_PACKAGES = "packages"
+GROUP_COMPILE = "compile"
+GROUP_MODELS = "models"
+
+
+class CachePurgeRefused(RuntimeError):
+ """A cache root failed a safety check, so nothing was deleted from it."""
+
+
+@dataclass(frozen = True)
+class CacheDefinition:
+ key: str
+ group: str
+ # True when emptying this costs a re-download of something the user chose to
+ # fetch. Never part of a bulk purge; the UI asks for it on its own.
+ opt_in: bool
+ resolve: Callable[[], list[Path]]
+ # When set, only top-level entries matching one of these globs are measured
+ # or deleted. For roots that hold configuration next to cache files.
+ 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
+
+
+@dataclass
+class PurgeOutcome:
+ freed_bytes: int = 0
+ removed_entries: int = 0
+ errors: Optional[list[str]] = None
+
+ def __post_init__(self) -> None:
+ if self.errors is None:
+ self.errors = []
+
+
+def _home() -> Path:
+ return Path.home()
+
+
+def _env_dir(name: str) -> Optional[Path]:
+ value = (os.environ.get(name) or "").strip()
+ if not value:
+ return None
+ try:
+ return Path(value).expanduser()
+ except (OSError, RuntimeError, ValueError):
+ return None
+
+
+def _is_windows() -> bool:
+ # A seam the path-layout branches can be tested on: patching os.name is not
+ # one, because pathlib reads it and Path would build a WindowsPath on POSIX.
+ return os.name == "nt"
+
+
+def _local_app_data() -> Path:
+ value = (os.environ.get("LOCALAPPDATA") or "").strip()
+ if value:
+ return Path(value)
+ return _home() / "AppData" / "Local"
+
+
+def _platform_cache_dir(name: str, *, windows_tail: str = "Cache") -> Path:
+ if _is_windows():
+ return _local_app_data() / name / windows_tail
+ if sys.platform == "darwin":
+ return _home() / "Library" / "Caches" / name
+ xdg = (os.environ.get("XDG_CACHE_HOME") or "").strip()
+ base = Path(xdg).expanduser() if xdg else _home() / ".cache"
+ return base / name
+
+
+def _first(*candidates: Optional[Path]) -> list[Path]:
+ for candidate in candidates:
+ if candidate is not None:
+ return [candidate]
+ return []
+
+
+_UV_CACHE_MARKER = "uv-cache-dir"
+
+
+def _recorded_uv_cache() -> Optional[Path]:
+ """The uv cache the installer recorded, which updates keep filling.
+
+ Parsed as unsloth_cli's _with_studio_uv_cache parses it: one record, one
+ trailing delimiter, and no expanduser, since uv makes a literal "~" dir.
+ """
+ try:
+ from utils.paths.storage_roots import cache_root
+ recorded = (cache_root() / _UV_CACHE_MARKER).read_text(
+ encoding = "utf-8-sig", errors = "surrogateescape"
+ )
+ except (OSError, ValueError, RuntimeError):
+ return None
+ recorded = recorded.removesuffix("\n").removesuffix("\r")
+ if not recorded.strip():
+ return None
+ try:
+ return Path(os.path.abspath(recorded))
+ except (OSError, ValueError):
+ return None
+
+
+def _uv_dirs() -> list[Path]:
+ # Both: _setup_cache_env seeds one, the installer may have recorded another,
+ # and either can be the multi-gigabyte one.
+ roots = _first(_env_dir("UV_CACHE_DIR"), _platform_cache_dir("uv"))
+ recorded = _recorded_uv_cache()
+ if recorded is not None:
+ roots.append(recorded)
+ return roots
+
+
+# One answer per tool per process. The lock spans the PROBE, not just the store: recording the
+# miss first let a second cold request read it as a finished failure and show the fallback path.
+_probed_cache_dirs: dict[str, Optional[Path]] = {}
+_probe_lock = threading.Lock()
+
+
+def _probe_tool_cache_dir(name: str, command: list[str]) -> Optional[Path]:
+ """Ask a package manager where its own cache is.
+
+ ``cache-dir`` in pip.conf and ``cache`` in .npmrc move it, no environment
+ variable carries either, and Studio's invocations of both honour them.
+ Reimplementing pip's five config kinds or npm's chain would drift.
+ """
+ from utils.child_stdio import utf8_child_env
+ with _probe_lock:
+ if name in _probed_cache_dirs:
+ return _probed_cache_dirs[name]
+ answer: Optional[Path] = None
+ try:
+ done = subprocess.run(
+ command,
+ capture_output = True,
+ text = True,
+ # The child would otherwise pick the locale encoding, the ANSI
+ # codepage on Windows, and mangle a non-ASCII path.
+ encoding = "utf-8",
+ errors = "replace",
+ env = utf8_child_env(),
+ timeout = 20,
+ )
+ except (OSError, ValueError, subprocess.SubprocessError) as exc:
+ logger.debug(f"Could not ask {name} for its cache directory: {exc}")
+ else:
+ 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
+ return answer
+
+
+def _pip_dirs() -> list[Path]:
+ return _first(
+ _env_dir("PIP_CACHE_DIR"),
+ _probe_tool_cache_dir("pip", [sys.executable, "-m", "pip", "cache", "dir"]),
+ _platform_cache_dir("pip"),
+ )
+
+
+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"])
+
+
+# The package cache and the one npx installs into, which Studio fills whenever
+# it launches an MCP server. Not the rest of ~/.npm: _logs is the user's.
+_NPM_CACHE_CHILDREN = ("_cacache", "_npx")
+
+
+def _npm_dirs() -> list[Path]:
+ configured = _env_dir("npm_config_cache") or _env_dir("NPM_CONFIG_CACHE")
+ if configured is None:
+ configured = _npm_configured_dir()
+ if configured is None:
+ configured = _local_app_data() / "npm-cache" if _is_windows() else _home() / ".npm"
+ return [configured / child for child in _NPM_CACHE_CHILDREN]
+
+
+def _bun_dirs() -> list[Path]:
+ return _first(_env_dir("BUN_INSTALL_CACHE_DIR"), _home() / ".bun" / "install" / "cache")
+
+
+def _hf_paths():
+ from utils.hf_cache_settings import get_hf_cache_paths
+ return get_hf_cache_paths()
+
+
+def _hf_homes() -> list[Path]:
+ """Every cache home this install has been pointed at, for PROTECTION only.
+
+ Never for deletion: an API key may append to that history through
+ ``PUT /api/settings/hugging-face-cache`` while the purge route refuses one,
+ so resolving a purge root through it would let a caller that cannot delete
+ choose what a later clear takes. Protecting extra locations is safe.
+ """
+ from utils.hf_cache_settings import known_hf_cache_homes
+ return list(known_hf_cache_homes())
+
+
+def _hf_hub_dirs() -> list[Path]:
+ return [_hf_paths().hub_cache]
+
+
+def _hf_child_dirs(name: str, configured: Optional[Path]) -> list[Path]:
+ # HF reads the variable INSTEAD of <home>/<name>, so these are alternatives,
+ # and the home is the effective one rather than 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")
+ except Exception as exc: # noqa: BLE001 - a broken root must not widen the list
+ logger.debug(f"Could not resolve the Studio dataset fallback cache: {exc}")
+ return None
+
+
+def _hf_datasets_dirs() -> list[Path]:
+ configured = _env_dir("HF_DATASETS_CACHE")
+ fallback = _studio_datasets_fallback()
+ if configured is not None and fallback is not None and _safe_resolve(configured) == fallback:
+ # cache_safe._retry_in_studio_cache points the variable there for the
+ # length of one load, in THIS process, while load_dataset writes Arrow
+ # files and lock state into it. Not a cache this inventory offers.
+ configured = None
+ return _hf_child_dirs("datasets", configured)
+
+
+def _hf_assets_dirs() -> list[Path]:
+ return _hf_child_dirs("assets", _env_dir("HF_ASSETS_CACHE"))
+
+
+def _hf_xet_dirs() -> list[Path]:
+ return [_hf_paths().xet_cache]
+
+
+def _diffusion_compile_root() -> Optional[Path]:
+ try:
+ from core.inference.diffusion_compile_cache import cache_root
+ return _safe_resolve(cache_root())
+ except Exception as exc: # noqa: BLE001 - a broken import must not widen the list
+ logger.debug(f"Could not resolve the diffusion compile cache: {exc}")
+ return None
+
+
+def _torch_inductor_dirs() -> list[Path]:
+ configured = _env_dir("TORCHINDUCTOR_CACHE_DIR")
+ diffusion = _diffusion_compile_root()
+ resolved = None if configured is None else _safe_resolve(configured)
+ if configured is not None and diffusion is not None and resolved is not None:
+ if _is_within(resolved, diffusion):
+ # diffusion_compile_cache.begin() repoints this at <key>/inductor
+ # while a model is resident and restores it on unload, so a row that
+ # followed it would name one directory and the clear take another.
+ configured = None
+ if configured is not None:
+ return [configured]
+ import getpass
+ import re
+ import tempfile
+
+ # torch/_inductor/runtime/cache_dir_utils.py, followed exactly. getpass also
+ # reads LOGNAME and the pwd name, so a container with no USER puts the cache
+ # at torchinductor_root while a bare uid would look at torchinductor_0.
+ try:
+ user = getpass.getuser()
+ except (KeyError, ModuleNotFoundError, OSError):
+ try:
+ user = f"uid_{os.getuid()}"
+ except AttributeError:
+ user = "unknown_user"
+ sanitized = re.sub(r'[\\/:*?"<>|]', "_", user)
+ return [Path(tempfile.gettempdir()) / f"torchinductor_{sanitized}"]
+
+
+def _torch_extensions_dirs() -> list[Path]:
+ configured = _env_dir("TORCH_EXTENSIONS_DIR")
+ if configured is not None:
+ return [configured]
+ if _is_windows():
+ # get_default_build_root() is user_cache_dir(appname = "torch_extensions")
+ # with no appauthor, and torch/_appdirs defaults the author to the app
+ # name, so Windows gets the name twice before the Cache tail.
+ return [_local_app_data() / "torch_extensions" / "torch_extensions" / "Cache"]
+ return [_platform_cache_dir("torch_extensions")]
+
+
+def _triton_dirs() -> list[Path]:
+ return _first(_env_dir("TRITON_CACHE_DIR"), _home() / ".triton" / "cache")
+
+
+def _cuda_dirs() -> list[Path]:
+ configured = _env_dir("CUDA_CACHE_PATH")
+ if configured is not None:
+ return [configured]
+ # The CUDA guide's defaults, which follow no shared convention: ROAMING
+ # AppData on Windows, Application Support on macOS, ~/.nv elsewhere.
+ if _is_windows():
+ roaming = (os.environ.get("APPDATA") or "").strip()
+ base = Path(roaming) if roaming else _home() / "AppData" / "Roaming"
+ return [base / "NVIDIA" / "ComputeCache"]
+ if sys.platform == "darwin":
+ return [_home() / "Library" / "Application Support" / "NVIDIA" / "ComputeCache"]
+ return [_home() / ".nv" / "ComputeCache"]
+
+
+def _numba_dirs() -> list[Path]:
+ # __pycache__ next to the source is not ours to empty, but when it is not
+ # writable numba's UserWideCacheLocator falls back to
+ # AppDirs("numba", appauthor = False).user_cache_dir, which is numba's alone.
+ return _first(_env_dir("NUMBA_CACHE_DIR"), _platform_cache_dir("numba"))
+
+
+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]
+ legacy = _home() / ".matplotlib"
+ if _is_windows():
+ if legacy.is_dir():
+ return [legacy]
+ local = (os.environ.get("LOCALAPPDATA") or "").strip()
+ return [Path(local) / "matplotlib"] if local else [legacy]
+ if sys.platform == "darwin":
+ return [legacy]
+ xdg = (os.environ.get("XDG_CACHE_HOME") or "").strip()
+ base = Path(xdg).expanduser() if xdg else _home() / ".cache"
+ return [base / "matplotlib"]
+
+
+MATPLOTLIB_PATTERNS = ("fontlist-*.json", "tex.cache", "ttfcache")
+
+
+def _matplotlib_patterns() -> Optional[tuple[str, ...]]:
+ # Only the XDG branch is a cache dir of its own. MPLCONFIGDIR and the
+ # ~/.matplotlib default are get_configdir() too, so matplotlibrc sits beside
+ # the font list and only the cache entries may go.
+ merged = _env_dir("MPLCONFIGDIR") is not None or _is_windows() or sys.platform == "darwin"
+ return MATPLOTLIB_PATTERNS if merged else None
+
+
+def _vllm_dirs() -> list[Path]:
+ # vllm/envs.py: XDG_CACHE_HOME or ~/.cache, then "vllm", on every platform,
+ # which the platform helper matches on Linux only.
+ 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")
+
+
+def _unsloth_compiled_dirs() -> list[Path]:
+ from utils.cache_cleanup import _cleanable_cache_dirs
+ return [directory for directory, _dedicated in _cleanable_cache_dirs()]
+
+
+def _measure_unsloth_compiled() -> tuple[int, int]:
+ """Size only what a clear would actually remove.
+
+ A directory Unsloth created goes whole; one it merely wrote into keeps
+ everything but the generated modules, so counting all of it would promise
+ space the clear cannot free.
+ """
+ from utils.cache_cleanup import _cleanable_cache_dirs
+
+ total = 0
+ entries = 0
+ for directory, dedicated in _cleanable_cache_dirs():
+ size, count = _measure_root(
+ directory, patterns = None if dedicated else _GENERATED_MODULE_PATTERNS
+ )
+ total += size
+ entries += count
+ return total, entries
+
+
+def _compiled_cache_refusal() -> Optional[str]:
+ """Why the compiled cache cannot be emptied, or None.
+
+ Its own gate, because the clear runs through cache_cleanup rather than by
+ emptying a root, and it is all-or-nothing across the directories it owns, so
+ one of them failing stops the whole clear. describe_cache asks too: a row
+ that offers a button this will refuse is worse than one that says why.
+ """
+ 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:
+ assert_purgeable_root(directory, protected = protected, trees = trees, keep = keep)
+ except CachePurgeRefused as exc:
+ return str(exc)
+ return None
+
+
+def _purge_unsloth_compiled() -> PurgeOutcome:
+ """Clear the compiled cache through the module that owns it.
+
+ cache_cleanup already knows which of these directories Unsloth created and
+ which merely hold files it generated, and it serializes against a sibling
+ backend that may be compiling right now. Re-deriving either here would give
+ this install a second, weaker answer.
+ """
+ from utils.cache_cleanup import (
+ LOCK_BUSY,
+ _cleanable_cache_dirs,
+ clear_unsloth_compiled_cache,
+ compiled_cache_lock,
+ )
+
+ outcome = PurgeOutcome()
+ with compiled_cache_lock() as lock_state:
+ if lock_state == LOCK_BUSY:
+ outcome.errors.append(
+ "Another Unsloth backend is using the compiled cache, so it was left in place."
+ )
+ return outcome
+ refusal = _compiled_cache_refusal()
+ if refusal is not None:
+ outcome.errors.append(refusal)
+ return outcome
+ before, entries = _measure_unsloth_compiled()
+ clear_unsloth_compiled_cache()
+ after, remaining = _measure_unsloth_compiled()
+ outcome.freed_bytes = max(0, before - after)
+ outcome.removed_entries = max(0, entries - remaining)
+ if after > 0:
+ # clear_unsloth_compiled_cache swallows every failure, so a read-only
+ # directory looks identical to a clean clear. Bytes and not entries: a
+ # dedicated cache is recreated holding an empty marker file.
+ outcome.errors.append(
+ "Part of the compiled cache could not be removed and is still in place."
+ )
+ return outcome
+
+
+_GENERATED_MODULE_PATTERNS = ("unsloth_compiled_module_*.py",)
+
+
+CACHE_DEFINITIONS: tuple[CacheDefinition, ...] = (
+ CacheDefinition("uv", GROUP_PACKAGES, False, _uv_dirs),
+ CacheDefinition("pip", GROUP_PACKAGES, False, _pip_dirs),
+ CacheDefinition("npm", GROUP_PACKAGES, False, _npm_dirs),
+ CacheDefinition("bun", GROUP_PACKAGES, False, _bun_dirs),
+ CacheDefinition("torch_inductor", GROUP_COMPILE, False, _torch_inductor_dirs),
+ CacheDefinition("torch_extensions", GROUP_COMPILE, False, _torch_extensions_dirs),
+ CacheDefinition("triton", GROUP_COMPILE, False, _triton_dirs),
+ CacheDefinition("cuda", GROUP_COMPILE, False, _cuda_dirs),
+ CacheDefinition("numba", GROUP_COMPILE, False, _numba_dirs),
+ CacheDefinition("matplotlib", GROUP_COMPILE, False, _matplotlib_dirs),
+ CacheDefinition("vllm", GROUP_COMPILE, False, _vllm_dirs),
+ # Opt-in. The others cost a recompile or a re-download; this one can break a
+ # job running RIGHT NOW, because a worker imports generated modules from here
+ # lazily and compiled_cache_lock only serialises against a sibling BACKEND.
+ CacheDefinition(
+ "unsloth_compiled",
+ GROUP_COMPILE,
+ True,
+ _unsloth_compiled_dirs,
+ custom_purge = _purge_unsloth_compiled,
+ custom_measure = _measure_unsloth_compiled,
+ custom_block = _compiled_cache_refusal,
+ ),
+ CacheDefinition("hf_xet", GROUP_MODELS, False, _hf_xet_dirs),
+ CacheDefinition("hf_assets", GROUP_MODELS, False, _hf_assets_dirs),
+ CacheDefinition("hf_datasets", GROUP_MODELS, True, _hf_datasets_dirs),
+ CacheDefinition("hf_hub", GROUP_MODELS, True, _hf_hub_dirs),
+)
+
+CACHE_KEYS: tuple[str, ...] = tuple(definition.key for definition in CACHE_DEFINITIONS)
+
+_DEFINITIONS_BY_KEY = {definition.key: definition for definition in CACHE_DEFINITIONS}
+
+# One purge at a time per process: two concurrent sweeps of one root race each
+# other into "file disappeared" errors that look like failures.
+_purge_lock = threading.Lock()
+
+
+def definition_for(key: str) -> CacheDefinition:
+ try:
+ return _DEFINITIONS_BY_KEY[key]
+ except KeyError:
+ raise ValueError(f"Unknown cache key: {key!r}") from None
+
+
+def _safe_resolve(path: Path) -> Optional[Path]:
+ try:
+ return Path(os.path.realpath(str(Path(path).expanduser())))
+ except (OSError, RuntimeError, ValueError):
+ return None
+
+
+def _is_junction(path: Path | str) -> bool:
+ """True for a Windows directory junction or volume mount point.
+
+ The same hazard as a symlink and not the same test: since 3.8 only
+ IO_REPARSE_TAG_SYMLINK sets S_IFLNK, so is_symlink() is False for a junction
+ while realpath() follows it, and UV_CACHE_DIR pointed at one would have the
+ TARGET emptied. os.path.isjunction is 3.12+ and this package supports 3.9.
+ """
+ isjunction = getattr(os.path, "isjunction", None)
+ if isjunction is not None:
+ try:
+ return bool(isjunction(path))
+ except (OSError, ValueError):
+ return False
+ if os.name != "nt":
+ return False
+ try:
+ tag = getattr(os.lstat(path), "st_reparse_tag", 0)
+ except (OSError, ValueError, AttributeError):
+ return False
+ return tag == getattr(stat, "IO_REPARSE_TAG_MOUNT_POINT", 0xA0000003)
+
+
+def protected_paths() -> set[Path]:
+ """Locations a purge must never delete, nor delete anything containing them.
+
+ User data, not caches: the databases, the token, projects, datasets,
+ outputs, exports, and the managed asset homes. The Hugging Face cache HOME
+ is here while its ``hub`` child is purgeable, because the home also holds
+ the access token.
+ """
+ from utils.paths.storage_roots import (
+ assets_root,
+ auth_db_path,
+ auth_root,
+ cache_root,
+ datasets_root,
+ documents_root,
+ exports_root,
+ outputs_root,
+ project_workspaces_root,
+ rag_root,
+ studio_bin_root,
+ studio_db_path,
+ studio_root,
+ tensorboard_root,
+ tmp_root,
+ )
+
+ candidates: list[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(),
+ assets_root(),
+ datasets_root(),
+ outputs_root(),
+ 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: it is the parent the per-tool
+ # cache directories sit under, plus llama.cpp slot state.
+ cache_root(),
+ ]
+ for name in ("DATA_DESIGNER_HOME", "UNSLOTH_STUDIO_PROJECTS_HOME", "UNSLOTH_STUDIO_HOME"):
+ configured = _env_dir(name)
+ if configured is not None:
+ candidates.append(configured)
+ try:
+ for home in _hf_homes():
+ candidates.append(home)
+ candidates.append(home / "token")
+ paths = _hf_paths()
+ # cache_home is what Settings DISPLAYS, and HF_HUB_CACHE=/mnt/hf-cache
+ # makes it the hub directory itself. Protecting it there would make the
+ # model cache permanently unclearable and no credential safer.
+ if _safe_resolve(paths.cache_home) != _safe_resolve(paths.hub_cache):
+ candidates.append(paths.cache_home)
+ except Exception as exc: # noqa: BLE001 - a broken HF setting must not widen the allow-list
+ logger.debug(f"Could not resolve the Hugging Face cache homes: {exc}")
+ candidates.append(Path.home() / ".cache" / "huggingface")
+ hf_home = _env_dir("HF_HOME")
+ if hf_home is not None:
+ candidates.append(hf_home)
+ candidates.append(hf_home / "token")
+ # Read INSTEAD of <home>/token, and it can name a file inside a cache.
+ token_path = _env_dir("HF_TOKEN_PATH")
+ if token_path is not None:
+ candidates.append(token_path)
+
+ return _resolved_set(candidates)
+
+
+def protected_trees() -> set[Path]:
+ """Directories nothing inside may be deleted, however a variable is pointed.
+
+ ``protected_paths`` stops a root that IS or CONTAINS user data; this stops a
+ root BENEATH it, which is what an inherited ``TRITON_CACHE_DIR`` pointing
+ into the projects folder would be. The studio home and the Hugging Face
+ cache home are deliberately absent: real caches live inside both.
+ """
+ from utils.paths.storage_roots import (
+ assets_root,
+ auth_root,
+ datasets_root,
+ documents_root,
+ exports_root,
+ outputs_root,
+ project_workspaces_root,
+ rag_root,
+ studio_bin_root,
+ tensorboard_root,
+ tmp_root,
+ )
+
+ candidates: list[Path] = [
+ assets_root(),
+ datasets_root(),
+ outputs_root(),
+ exports_root(),
+ auth_root(),
+ rag_root(),
+ tensorboard_root(),
+ project_workspaces_root(),
+ # Descendants of the studio home and of the temp dir are deliberately
+ # allowed, since the caches live there, so these need naming on their own.
+ documents_root(),
+ studio_bin_root(),
+ tmp_root(),
+ ]
+ configured = _env_dir("DATA_DESIGNER_HOME")
+ if configured is not None:
+ candidates.append(configured)
+ return _resolved_set(candidates)
+
+
+def _resolved_set(candidates: Iterable[Path]) -> set[Path]:
+ resolved_paths: set[Path] = set()
+ for candidate in candidates:
+ resolved = _safe_resolve(candidate)
+ if resolved is not None:
+ resolved_paths.add(resolved)
+ return resolved_paths
+
+
+def _is_within(child: Path, parent: Path) -> bool:
+ try:
+ child.relative_to(parent)
+ return True
+ except ValueError:
+ return False
+
+
+def sheltered_roots(exclude_key: Optional[str] = None) -> dict[Path, str]:
+ """Resolved roots another key's clear must not empty, mapped to why.
+
+ An opt-in cache and a pattern-limited one for the same reason: their own
+ clear is narrower than emptying the directory, so swallowing them whole
+ takes what that clear was written to keep. Nothing stops a variable from
+ putting either inside another cache (``MPLCONFIGDIR=/cache/uv/matplotlib``
+ under ``UV_CACHE_DIR=/cache/uv``). The key being cleared is excluded.
+ """
+ roots: dict[Path, str] = {}
+ for definition in CACHE_DEFINITIONS:
+ if definition.key == exclude_key:
+ continue
+ if definition.opt_in:
+ reason = "the opt-in cache"
+ elif _patterns_for(definition) is not None:
+ reason = f"the {definition.key} cache"
+ else:
+ continue
+ for root in _resolve_roots(definition):
+ resolved = _safe_resolve(root)
+ if resolved is not None:
+ roots.setdefault(resolved, reason)
+ return roots
+
+
+def assert_purgeable_root(
+ root: Path,
+ *,
+ protected: Optional[set[Path]] = None,
+ trees: Optional[set[Path]] = None,
+ keep: Optional[dict[Path, str]] = None,
+) -> Path:
+ """Return the real path of *root*, or raise if emptying it is not allowed.
+
+ The one gate every deletion here goes through, answering from 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)
+ if not raw.is_absolute():
+ raise CachePurgeRefused(f"Cache root is not an absolute path: {raw}")
+ # The link itself, not its target: emptying through one deletes files at a
+ # location nobody named, and unlinking it would take the user's link.
+ if raw.is_symlink():
+ raise CachePurgeRefused(f"Cache root is a symlink: {raw}")
+ if _is_junction(raw):
+ raise CachePurgeRefused(f"Cache root is a junction: {raw}")
+ resolved = _safe_resolve(raw)
+ 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}")
+ for reserved in protected:
+ if resolved == reserved:
+ raise CachePurgeRefused(f"Refusing to delete a protected location: {resolved}")
+ if _is_within(reserved, resolved):
+ raise CachePurgeRefused(
+ f"Refusing to empty {resolved}: it contains the protected location {reserved}"
+ )
+ for tree in trees:
+ if _is_within(resolved, tree):
+ raise CachePurgeRefused(
+ f"Refusing to empty {resolved}: it sits inside the protected folder {tree}"
+ )
+ for reserved, kind in ({} if keep is None else keep).items():
+ if resolved == reserved or _is_within(reserved, resolved):
+ raise CachePurgeRefused(
+ f"Refusing to empty {resolved}: it holds {kind} {reserved}, "
+ "which is only ever cleared when it is asked for by name"
+ )
+ return resolved
+
+
+def _matching(name: str, patterns: Optional[Iterable[str]]) -> bool:
+ if patterns is None:
+ return True
+ return any(fnmatch.fnmatch(name, pattern) for pattern in patterns)
+
+
+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.
+ """
+
+ def __init__(self) -> None:
+ self._single = 0
+ self._multi: dict[tuple[int, int], list[int]] = {}
+
+ def add(self, stat) -> None:
+ if stat.st_nlink <= 1:
+ self._single += int(stat.st_size)
+ return
+ record = self._multi.get((stat.st_dev, stat.st_ino))
+ if record is None:
+ self._multi[(stat.st_dev, stat.st_ino)] = [int(stat.st_size), int(stat.st_nlink), 1]
+ else:
+ record[2] += 1
+
+ def freeable_bytes(self) -> int:
+ return self._single + sum(size for size, links, met in self._multi.values() if met >= links)
+
+
+def _record_entry(entry: os.DirEntry, ledger: LinkLedger) -> None:
+ try:
+ stat = entry.stat(follow_symlinks = False)
+ except OSError:
+ return
+ ledger.add(stat)
+
+
+def _descendable(entry: os.DirEntry) -> bool:
+ # is_dir is True for a junction and is_symlink is not, so descending would
+ # size its target and a junction to an ancestor would never terminate. Free
+ # on POSIX, where isjunction and the fallback answer without a syscall.
+ return not _is_junction(entry.path)
+
+
+def _measure_tree(path: Path, ledger: LinkLedger) -> int:
+ """Record every file below *path* in *ledger* and return the entry count.
+
+ The size is not returned: a multi-link inode's contribution is not known until every root
+ has been walked, so only the ledger can answer that, and only at the end.
+ """
+ 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
+ return count
+
+
+def _measure_root(root: Path, *, patterns: Optional[Iterable[str]] = None) -> tuple[int, int]:
+ ledger = LinkLedger()
+ entries = 0
+ try:
+ if Path(root).is_symlink() or _is_junction(root) or not Path(root).is_dir():
+ return 0, 0
+ except OSError:
+ return 0, 0
+ try:
+ with os.scandir(root) as scan:
+ for entry in scan:
+ if not _matching(entry.name, patterns):
+ continue
+ entries += 1
+ if entry.is_symlink():
+ continue
+ if entry.is_dir(follow_symlinks = False):
+ if _descendable(entry):
+ _measure_tree(Path(entry.path), ledger)
+ continue
+ _record_entry(entry, ledger)
+ except OSError as exc:
+ logger.debug(f"Could not size {root}: {exc}")
+ return ledger.freeable_bytes(), entries
+
+
+def _resolve_roots(definition: CacheDefinition) -> list[Path]:
+ try:
+ candidates = definition.resolve()
+ except Exception as exc: # noqa: BLE001 - one broken resolver must not break the report
+ logger.debug(f"Could not resolve the {definition.key} cache: {exc}")
+ return []
+ roots: list[Path] = []
+ seen: set[str] = set()
+ for candidate in candidates:
+ if candidate is None:
+ continue
+ try:
+ path = Path(candidate).expanduser()
+ if not path.is_dir():
+ continue
+ except OSError:
+ continue
+ resolved = _safe_resolve(path)
+ key = os.path.normcase(str(resolved if resolved is not None else path))
+ if key in seen:
+ continue
+ seen.add(key)
+ roots.append(path)
+ return roots
+
+
+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, then measure: a root the gate refuses would otherwise be walked
+ # recursively on every open of the tab, for bytes nothing can reclaim.
+ measurable = list(roots)
+ if roots and definition.custom_block is not None:
+ blocked_reason = definition.custom_block()
+ purgeable = blocked_reason is None
+ elif roots and definition.custom_purge is None:
+ protected = protected_paths()
+ trees = protected_trees()
+ keep = sheltered_roots(definition.key)
+ measurable = []
+ for root in roots:
+ try:
+ assert_purgeable_root(root, protected = protected, trees = trees, keep = keep)
+ except CachePurgeRefused as exc:
+ if blocked_reason is None:
+ blocked_reason = str(exc)
+ continue
+ measurable.append(root)
+ # What a clear will do: purge_cache skips a refused root and carries on,
+ # so one bad root does not put the others out of reach.
+ purgeable = bool(measurable)
+ # Whatever the roots say, a cache the environment is LINKED into cannot be offered: the row
+ # would advertise bytes whose removal breaks the install rather than costing a re-download.
+ # After the root checks so a genuinely refused root still names its own reason first.
+ if blocked_reason is None:
+ blocked_reason = _link_mode_refusal(definition.key)
+ if blocked_reason is not None:
+ purgeable = False
+ if definition.custom_measure is not None:
+ total, entries = (0, 0) if blocked_reason is not None else definition.custom_measure()
+ else:
+ total = 0
+ entries = 0
+ for root in measurable:
+ size, count = _measure_root(root, patterns = patterns)
+ total += size
+ entries += count
+ return {
+ "key": definition.key,
+ "group": definition.group,
+ "opt_in": definition.opt_in,
+ "paths": [str(root) for root in roots],
+ "size_bytes": total,
+ "entry_count": entries,
+ "present": bool(roots),
+ "purgeable": bool(roots) and purgeable,
+ "blocked_reason": blocked_reason,
+ }
+
+
+def _patterns_for(definition: CacheDefinition) -> Optional[tuple[str, ...]]:
+ if definition.key == "matplotlib":
+ return _matplotlib_patterns()
+ if definition.key == "unsloth_compiled":
+ return None
+ return definition.patterns
+
+
+# A walk is seconds on a large uv or triton cache, so a repeat read inside this
+# window reuses the last answer.
+_INVENTORY_TTL_SECONDS = 60.0
+# (when the walk began, when it was stored, the entry). Both times: the store
+# time is what the TTL is about, and the start time is what tells a forced read
+# whether the walk it waited for saw the cache before the request was made.
+_size_cache: dict[str, tuple[float, float, dict]] = {}
+# Bumped by every invalidation, so a walk that began before one cannot store its
+# answer after it. Dropping the entry is not enough: a scan started in one tab
+# before a purge in another would install the pre-purge size for the window.
+_size_epochs: dict[str, int] = {}
+_size_cache_lock = threading.Lock()
+
+
+def invalidate_cache_size(key: str) -> None:
+ with _size_cache_lock:
+ _size_cache.pop(key, None)
+ _size_epochs[key] = _size_epochs.get(key, 0) + 1
+
+
+_size_flights: dict[str, threading.Lock] = {}
+_size_flights_lock = threading.Lock()
+
+
+def _flight_for(key: str) -> threading.Lock:
+ with _size_flights_lock:
+ return _size_flights.setdefault(key, threading.Lock())
+
+
+def _described(definition: CacheDefinition, *, refresh: bool) -> dict:
+ 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]
+ # One walk per cache at a time: simultaneous misses would each pay a cold
+ # walk for the same answer, and two open tabs are enough to cause it.
+ with _flight_for(definition.key):
+ with _size_cache_lock:
+ epoch = _size_epochs.get(definition.key, 0)
+ remembered = _size_cache.get(definition.key)
+ # A forced read needs a walk that BEGAN after it asked, or it gets the figures it
+ # asked to replace; an ordinary one only needs a fresh enough answer.
+ if remembered is not None:
+ if refresh:
+ if remembered[0] >= started:
+ 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
+
+
+def cache_inventory(*, refresh: bool = False) -> dict:
+ entries = [_described(definition, refresh = refresh) for definition in CACHE_DEFINITIONS]
+ total = sum(entry["size_bytes"] for entry in entries if entry["present"])
+ reclaimable = sum(
+ entry["size_bytes"]
+ for entry in entries
+ if entry["present"] and entry["purgeable"] and not entry["opt_in"]
+ )
+ return {
+ "caches": entries,
+ "total_bytes": total,
+ "reclaimable_bytes": reclaimable,
+ "free_bytes": _free_bytes(),
+ "total_disk_bytes": _total_disk_bytes(),
+ }
+
+
+def _usage():
+ from utils.paths.storage_roots import studio_root
+ for candidate in (studio_root(), Path.home(), Path(os.path.abspath(os.sep))):
+ try:
+ return shutil.disk_usage(candidate)
+ except OSError:
+ continue
+ return None
+
+
+def _free_bytes() -> Optional[int]:
+ usage = _usage()
+ return int(usage.free) if usage is not None else None
+
+
+def _total_disk_bytes() -> Optional[int]:
+ usage = _usage()
+ return int(usage.total) if usage is not None else None
+
+
+def _remove_entry(
+ entry: os.DirEntry, root: Path, outcome: PurgeOutcome, ledger: LinkLedger, survivors: LinkLedger
+) -> None:
+ """Remove one top-level entry, recording what it would free rather than adding it up here.
+
+ The freed total is read off the ledger once the whole root is done: an inode still linked
+ from outside frees nothing, and whether that is so cannot be decided one entry at a time.
+ """
+ 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)
+ if real is None or not _is_within(real, root):
+ outcome.errors.append(f"Skipped {path}: it resolves outside the cache root")
+ return
+ _measure_tree(path, ledger)
+ # rmtree refuses a symlinked directory and does not follow links it
+ # finds inside, so the walk cannot leave *root*.
+ try:
+ shutil.rmtree(path)
+ except OSError:
+ # Partial removal: the whole subtree is already in the ledger, so survivors are
+ # recorded and subtracted. A "freed" figure must never count bytes still on disk.
+ _measure_tree(path, survivors)
+ raise
+ else:
+ _record_entry(entry, ledger)
+ os.unlink(path)
+ except OSError as exc:
+ outcome.errors.append(f"Could not remove {path}: {exc}")
+ return
+ outcome.removed_entries += 1
+
+
+def empty_cache_root(
+ root: Path,
+ *,
+ patterns: Optional[Iterable[str]] = None,
+ protected: Optional[set[Path]] = None,
+ trees: Optional[set[Path]] = None,
+ keep: Optional[set[Path]] = None,
+) -> PurgeOutcome:
+ 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:
+ entries = list(scan)
+ except OSError as exc:
+ outcome.errors.append(f"Could not read {resolved}: {exc}")
+ return outcome
+ for entry in entries:
+ if not _matching(entry.name, patterns):
+ continue
+ _remove_entry(entry, resolved, outcome, ledger, survivors)
+ # Never negative: the survivor walk sees the tree after the failure, so it cannot record
+ # more than the pre-removal walk did, but a file that grew in between should not turn a
+ # partial purge into a negative report.
+ outcome.freed_bytes += max(0, ledger.freeable_bytes() - survivors.freeable_bytes())
+ return outcome
+
+
+# Which registries write into each cache. Both for the hub and xet roots: a
+# dataset download snapshot_downloads its datasets-- entries into the same hub
+# tree, and each claim of either kind carries the xet cache it fetches chunks to.
+_DOWNLOAD_REGISTRIES = {
+ "hf_hub": ("models", "datasets"),
+ "hf_xet": ("models", "datasets"),
+ "hf_datasets": ("datasets",),
+}
+
+_PURGE_BUSY = "Cancel the active downloads before clearing this cache."
+
+
+def _reserve_downloads(key: str) -> tuple[list, Optional[str]]:
+ """Hold every download registry that writes into this cache, or say why not.
+
+ A reservation and not a look, for the reason the per-repository deletes call
+ begin_delete: a worker can claim between a check and the rmtree. A registry
+ this cannot reach does not block the purge, or an import would kill the button.
+ """
+ kinds = _DOWNLOAD_REGISTRIES.get(key)
+ if not kinds:
+ return [], None
+ try:
+ from hub.services.datasets import downloads as dataset_downloads
+ from hub.utils.download_registry import get_models_registry
+
+ # The SERVICE, not get_datasets_registry(): a managed install has one dataset registry
+ # per account, and the singleton is only the owner's. The service holds them all and
+ # keeps a new one from being born free mid-purge.
+ registries = [
+ get_models_registry() if kind == "models" else dataset_downloads for kind in kinds
+ ]
+ except Exception as exc: # noqa: BLE001 - a broken registry must not block a purge
+ logger.debug(f"Could not reach the download registries for {key}: {exc}")
+ return [], None
+ reserved: list = []
+ for registry in registries:
+ try:
+ granted = registry.begin_cache_purge()
+ except Exception as exc: # noqa: BLE001
+ logger.debug(f"Could not reserve a download registry for {key}: {exc}")
+ continue
+ if not granted:
+ _release_downloads(reserved)
+ return [], _PURGE_BUSY
+ reserved.append(registry)
+ return reserved, None
+
+
+def _release_downloads(reserved: Iterable) -> None:
+ for registry in reserved:
+ try:
+ registry.end_cache_purge()
+ except Exception as exc: # noqa: BLE001 - never leave a purge holding one
+ logger.warning(f"Could not release a download registry: {exc}")
+
+
+# A spawned trainer reads these outside every registry here: it gets the same HF_HUB_CACHE and
+# HF_XET_CACHE and calls snapshot_download and load_dataset itself, so a clear could cost a run.
+_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
+ active = bool(get_training_backend().is_training_active())
+ except Exception as exc: # noqa: BLE001 - a broken import must not block a purge
+ logger.debug(f"Could not read the training state: {exc}")
+ if active:
+ return True
+ try:
+ from core.training.diffusion_training_service import get_diffusion_training_service
+ return bool(get_diffusion_training_service().is_active())
+ except Exception as exc: # noqa: BLE001
+ logger.debug(f"Could not read the diffusion training state: {exc}")
+ return False
+
+
+def _uv_symlink_refusal() -> Optional[str]:
+ """Refuse the uv cache when an installed environment is linked into it, not copied from it.
+
+ uv's own `uv help sync` warns that clearing the cache under UV_LINK_MODE=symlink "will break
+ all installed packages": the environment's files are not copies, they are links into this
+ cache. That turns a bulk clear, which is meant to cost a re-download at worst, into a broken
+ install, so the cache is refused rather than offered.
+
+ Two cheap answers, no walk. The mode this process would use, and the evidence on disk: a
+ top-level entry in the running interpreter's site-packages that is a symlink into one of the
+ uv cache roots. uv links at that level, so the directory's own entries are enough.
+ """
+ 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:
+ import sysconfig
+ site_packages = sysconfig.get_paths().get("purelib")
+ except Exception as exc: # noqa: BLE001 - no site-packages means nothing linked from here
+ logger.debug(f"Could not locate site-packages for the uv link check: {exc}")
+ return None
+ if not site_packages:
+ return None
+ roots = [root for root in _uv_dirs() if root is not None]
+ if not roots:
+ return None
+ try:
+ with os.scandir(site_packages) as entries:
+ for entry in entries:
+ if not entry.is_symlink():
+ continue
+ target = _safe_resolve(Path(entry.path))
+ if target is None:
+ continue
+ if any(_is_within(target, _safe_resolve(root) or root) for root in roots):
+ return (
+ "The installed packages are symlinked into this cache; "
+ "clearing it would break them."
+ )
+ except OSError as exc:
+ logger.debug(f"Could not read site-packages for the uv link check: {exc}")
+ return None
+
+
+def _link_mode_refusal(key: str) -> Optional[str]:
+ return _uv_symlink_refusal() if key == "uv" else None
+
+
+def _training_refusal(key: str) -> Optional[str]:
+ if key not in _WORKER_SENSITIVE_KEYS:
+ return None
+ return "Stop the training run before clearing this cache." if _any_training_active() else None
+
+
+def _inference_refusal(key: str) -> Optional[str]:
+ """Refuse a model-cache clear while an inference backend is holding cached weights.
+
+ Deleting ONE repo already runs these guards (hub/services/models/deletion.py), and emptying
+ the whole cache is every repo at once, so skipping them here was the wider action with the
+ weaker check. sd.cpp re-reads its companion VAE and text-encoder files for every generation,
+ so this breaks a model that was loaded long before the clear, not only one mid-load.
+
+ Fails CLOSED on a query that raises, as the per-repo path does: not being able to tell
+ whether weights are in use is not permission to unlink them.
+ """
+ if key not in _WORKER_SENSITIVE_KEYS:
+ return None
+ try:
+ from hub.services.models.deletion import any_model_load_blocks_cache_clear
+ except Exception as exc: # noqa: BLE001 - no guard module means no backend to hold anything
+ logger.debug(f"Could not import the inference load-state guard: {exc}")
+ return None
+ try:
+ return any_model_load_blocks_cache_clear()
+ except Exception as exc: # noqa: BLE001
+ logger.warning(f"Could not verify the inference load state; refusing the clear: {exc}")
+ return "Could not verify whether a model is loaded. Try again in a moment."
+
+
+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:
+ logger.warning(f"Refusing to purge the {key} cache: {training}")
+ return _purge_result(definition, PurgeOutcome(errors = [training]))
+ inference = _inference_refusal(key)
+ if inference is not None:
+ logger.warning(f"Refusing to purge the {key} cache: {inference}")
+ return _purge_result(definition, PurgeOutcome(errors = [inference]))
+ linked = _link_mode_refusal(key)
+ if linked is not None:
+ logger.warning(f"Refusing to purge the {key} cache: {linked}")
+ return _purge_result(definition, PurgeOutcome(errors = [linked]))
+ reserved, busy = _reserve_downloads(key)
+ if busy is not None:
+ logger.warning(f"Refusing to purge the {key} cache: {busy}")
+ return _purge_result(definition, PurgeOutcome(errors = [busy]))
+ try:
+ if definition.custom_purge is not None:
+ outcome = definition.custom_purge()
+ return _purge_result(definition, outcome)
+ outcome = PurgeOutcome()
+ patterns = _patterns_for(definition)
+ protected = protected_paths()
+ trees = protected_trees()
+ keep = sheltered_roots(definition.key)
+ for root in _resolve_roots(definition):
+ try:
+ root_outcome = empty_cache_root(
+ root, patterns = patterns, protected = protected, trees = trees, keep = keep
+ )
+ except CachePurgeRefused as exc:
+ logger.warning(f"Refusing to purge the {key} cache at {root}: {exc}")
+ outcome.errors.append(str(exc))
+ continue
+ outcome.freed_bytes += root_outcome.freed_bytes
+ outcome.removed_entries += root_outcome.removed_entries
+ outcome.errors.extend(root_outcome.errors)
+ return _purge_result(definition, outcome)
+ finally:
+ _release_downloads(reserved)
+
+
+def _purge_result(definition: CacheDefinition, outcome: PurgeOutcome) -> dict:
+ return {
+ "key": definition.key,
+ "freed_bytes": outcome.freed_bytes,
+ "removed_entries": outcome.removed_entries,
+ "errors": list(outcome.errors),
+ }
+
+
+# Emptying either removes the repositories the Hub inventory reports, so it is
+# one of the app-driven mutations inventory_scan says it is invalidated on.
+_HF_SCANNED_KEYS = frozenset({"hf_hub", "hf_datasets"})
+# The caches that live under the configured Hugging Face root, and therefore describe a
+# different directory the moment that root changes.
+_HF_ROOTED_KEYS = frozenset({"hf_hub", "hf_xet", "hf_datasets"})
+
+
+def _invalidate_hf_scans() -> None:
+ try:
+ from hub.utils.inventory_scan import invalidate_hf_cache_scans
+ except ImportError as exc:
+ logger.debug(f"Could not invalidate the Hugging Face scans: {exc}")
+ return
+ invalidate_hf_cache_scans()
+
+
+def invalidate_hf_rooted_sizes() -> None:
+ """Forget the sizes measured under the previous Hugging Face root.
+
+ The memo above is keyed by cache key, not by path, so moving the Models Folder leaves
+ three entries describing directories nobody reads any more. A browser hides that by
+ forcing a refresh off the inventory-version event, but an API-key caller is allowed to
+ change the folder and read the inventory while being forbidden refresh=true, and would
+ see the old root's figures for the rest of the TTL with no way to ask again.
+ """
+ for key in _HF_ROOTED_KEYS:
+ invalidate_cache_size(key)
+
+
+def purge_caches(keys: Iterable[str]) -> dict:
+ """Empty each named cache, then report what the inventory looks like after.
+
+ Unknown keys raise before anything is deleted, so a request that names one
+ cache this build does not have changes nothing at all.
+ """
+ requested = [str(key) for key in keys]
+ if not requested:
+ raise ValueError("Choose at least one cache to clear.")
+ definitions = [definition_for(key) for key in dict.fromkeys(requested)]
+ results = []
+ with _purge_lock:
+ for definition in definitions:
+ logger.info(f"Clearing the {definition.key} cache")
+ results.append(purge_cache(definition.key))
+ invalidate_cache_size(definition.key)
+ if any(definition.key in _HF_SCANNED_KEYS for definition in definitions):
+ _invalidate_hf_scans()
+ return {
+ "results": results,
+ "freed_bytes": sum(result["freed_bytes"] for result in results),
+ "inventory": cache_inventory(),
+ }
diff --git a/studio/backend/utils/hf_cache_settings.py b/studio/backend/utils/hf_cache_settings.py
index 73a72e00846..1a8b953642f 100644
--- a/studio/backend/utils/hf_cache_settings.py
+++ b/studio/backend/utils/hf_cache_settings.py
@@ -416,9 +416,28 @@ def set_hf_cache_home(cache_home: Optional[str]) -> HuggingFaceCachePaths:
from hub.utils.hf_cache_state import invalidate_partial_resumability
invalidate_partial_resumability()
+ # And the inventory's remembered sizes, which are keyed by cache rather than by path.
+ from utils.cache_inventory import invalidate_hf_rooted_sizes
+
+ invalidate_hf_rooted_sizes()
return get_hf_cache_paths()
+def effective_cache_home() -> Path:
+ """The directory Hugging Face itself treats as HF_HOME.
+
+ Never ``HuggingFaceCachePaths.cache_home``, which is the DISPLAY home and is
+ not it in either direction: an explicit ``HF_HUB_CACHE=/mnt/project/hub``
+ makes it the hub's parent, and a Studio-selected models folder makes it that
+ folder, while ``initialize_hf_cache_environment`` deliberately leaves HF_HOME
+ at the platform default and redirects only the hub and xet caches. The token,
+ ``assets`` and ``datasets`` stay under the real home, so anything resolving
+ one of those has to ask here.
+ """
+ live = (os.environ.get("HF_HOME") or "").strip()
+ return _canonical(live) if live else _default_cache_home()
+
+
def known_hf_cache_homes() -> list[Path]:
paths = get_hf_cache_paths()
stored = _stored_cache_home()
diff --git a/studio/frontend/src/features/settings/api/caches.ts b/studio/frontend/src/features/settings/api/caches.ts
new file mode 100644
index 00000000000..8c423099d51
--- /dev/null
+++ b/studio/frontend/src/features/settings/api/caches.ts
@@ -0,0 +1,200 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import { authFetch } from "@/features/auth";
+import { readFastApiError } from "@/lib/format-fastapi-error";
+
+/**
+ * Caches are named by key, never by path: the backend owns the mapping from a
+ * key to a directory, so nothing the browser sends can widen what a purge
+ * reaches.
+ */
+export const CACHE_KEYS = [
+ "uv",
+ "pip",
+ "npm",
+ "bun",
+ "torch_inductor",
+ "torch_extensions",
+ "triton",
+ "cuda",
+ "numba",
+ "matplotlib",
+ "vllm",
+ "unsloth_compiled",
+ "hf_xet",
+ "hf_assets",
+ "hf_datasets",
+ "hf_hub",
+] as const;
+
+export type CacheKey = (typeof CACHE_KEYS)[number];
+export type CacheGroup = "packages" | "compile" | "models";
+
+export type CacheEntry = {
+ key: CacheKey;
+ group: CacheGroup;
+ /** Clearing this costs a re-download, so it is never part of a bulk purge. */
+ optIn: boolean;
+ paths: string[];
+ sizeBytes: number;
+ entryCount: number;
+ present: boolean;
+ purgeable: boolean;
+ blockedReason: string | null;
+};
+
+export type CacheInventory = {
+ caches: CacheEntry[];
+ totalBytes: number;
+ reclaimableBytes: number;
+ freeBytes: number | null;
+ totalDiskBytes: number | null;
+};
+
+export type CachePurgeResult = {
+ key: CacheKey;
+ freedBytes: number;
+ removedEntries: number;
+ errors: string[];
+};
+
+export type CachePurgeOutcome = {
+ results: CachePurgeResult[];
+ freedBytes: number;
+ inventory: CacheInventory;
+};
+
+type ApiCacheEntry = {
+ key: CacheKey;
+ group: CacheGroup;
+ // biome-ignore lint/style/useNamingConvention: API schema
+ opt_in: boolean;
+ paths: string[];
+ // biome-ignore lint/style/useNamingConvention: API schema
+ size_bytes: number;
+ // biome-ignore lint/style/useNamingConvention: API schema
+ entry_count: number;
+ present: boolean;
+ purgeable: boolean;
+ // biome-ignore lint/style/useNamingConvention: API schema
+ blocked_reason: string | null;
+};
+
+type ApiCacheInventory = {
+ caches: ApiCacheEntry[];
+ // biome-ignore lint/style/useNamingConvention: API schema
+ total_bytes: number;
+ // biome-ignore lint/style/useNamingConvention: API schema
+ reclaimable_bytes: number;
+ // biome-ignore lint/style/useNamingConvention: API schema
+ free_bytes: number | null;
+ // biome-ignore lint/style/useNamingConvention: API schema
+ total_disk_bytes: number | null;
+};
+
+type ApiCachePurgeResult = {
+ key: CacheKey;
+ // biome-ignore lint/style/useNamingConvention: API schema
+ freed_bytes: number;
+ // biome-ignore lint/style/useNamingConvention: API schema
+ removed_entries: number;
+ errors: string[];
+};
+
+type ApiCachePurgeOutcome = {
+ results: ApiCachePurgeResult[];
+ // biome-ignore lint/style/useNamingConvention: API schema
+ freed_bytes: number;
+ inventory: ApiCacheInventory;
+};
+
+function entryFromApi(value: ApiCacheEntry): CacheEntry {
+ return {
+ key: value.key,
+ group: value.group,
+ optIn: value.opt_in,
+ paths: value.paths,
+ sizeBytes: value.size_bytes,
+ entryCount: value.entry_count,
+ present: value.present,
+ purgeable: value.purgeable,
+ blockedReason: value.blocked_reason,
+ };
+}
+
+export function inventoryFromApi(value: ApiCacheInventory): CacheInventory {
+ return {
+ caches: value.caches.map(entryFromApi),
+ totalBytes: value.total_bytes,
+ reclaimableBytes: value.reclaimable_bytes,
+ freeBytes: value.free_bytes,
+ totalDiskBytes: value.total_disk_bytes,
+ };
+}
+
+export function purgeOutcomeFromApi(
+ value: ApiCachePurgeOutcome,
+): CachePurgeOutcome {
+ return {
+ results: value.results.map((result) => ({
+ key: result.key,
+ freedBytes: result.freed_bytes,
+ removedEntries: result.removed_entries,
+ errors: result.errors,
+ })),
+ freedBytes: value.freed_bytes,
+ inventory: inventoryFromApi(value.inventory),
+ };
+}
+
+export async function loadCacheInventory(
+ options: { refresh?: boolean } = {},
+): Promise<CacheInventory> {
+ // refresh re-walks instead of reusing a size measured a moment ago, which is
+ // what Recheck is for. UI sessions only; see the route.
+ const response = await authFetch(
+ options.refresh
+ ? "/api/settings/caches?refresh=true"
+ : "/api/settings/caches",
+ );
+ if (!response.ok) {
+ throw new Error(
+ await readFastApiError(response, "Failed to measure the caches"),
+ );
+ }
+ return inventoryFromApi(await response.json());
+}
+
+export async function purgeCaches(
+ keys: readonly CacheKey[],
+): Promise<CachePurgeOutcome> {
+ const response = await authFetch("/api/settings/caches/purge", {
+ method: "POST",
+ headers: { "Content-Type": "application/json" },
+ body: JSON.stringify({ keys }),
+ });
+ if (!response.ok) {
+ throw new Error(
+ await readFastApiError(response, "Failed to clear the caches"),
+ );
+ }
+ return purgeOutcomeFromApi(await response.json());
+}
+
+/** The caches a bulk clear covers: present, allowed, and free to rebuild.
+ *
+ * Entries and not bytes: a tree of empty directories measures zero, still
+ * costs inodes, and the backend can empty it.
+ */
+export function bulkPurgeKeys(inventory: CacheInventory): CacheKey[] {
+ return inventory.caches
+ .filter(
+ (entry) =>
+ entry.present &&
+ entry.purgeable &&
+ !entry.optIn &&
+ entry.entryCount > 0,
+ )
+ .map((entry) => entry.key);
+}
diff --git a/studio/frontend/src/features/settings/components/cache-storage-rows.tsx b/studio/frontend/src/features/settings/components/cache-storage-rows.tsx
new file mode 100644
index 00000000000..e34571e62b8
--- /dev/null
+++ b/studio/frontend/src/features/settings/components/cache-storage-rows.tsx
@@ -0,0 +1,363 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import { Button } from "@/components/ui/button";
+import {
+ Dialog,
+ DialogContent,
+ DialogDescription,
+ DialogFooter,
+ DialogHeader,
+ DialogTitle,
+} from "@/components/ui/dialog";
+import {
+ bumpInventoryVersion,
+ getInventoryVersion,
+ useInventoryVersion,
+} from "@/features/hub/stores/inventory-events";
+import { type TranslationKey, useT } from "@/i18n";
+import { toast } from "@/lib/toast";
+import { useCallback, useEffect, useRef, useState } from "react";
+import {
+ type CacheEntry,
+ type CacheInventory,
+ type CacheKey,
+ bulkPurgeKeys,
+ loadCacheInventory,
+ purgeCaches,
+} from "../api/caches";
+import { SettingsRow } from "./settings-row";
+
+/** Decimal units, matching the disk readings the Storage section already shows. */
+export function formatCacheSize(bytes: number): string {
+ const safe = Number.isFinite(bytes) && bytes > 0 ? bytes : 0;
+ if (safe >= 1e9) {
+ const gb = safe / 1e9;
+ return `${gb >= 10 ? gb.toFixed(1) : gb.toFixed(2)} GB`;
+ }
+ if (safe >= 1e6) return `${Math.round(safe / 1e6)} MB`;
+ if (safe >= 1e3) return `${Math.round(safe / 1e3)} KB`;
+ return `${Math.round(safe)} B`;
+}
+
+const CACHE_NAME_KEYS: Record<CacheKey, TranslationKey> = {
+ uv: "settings.resources.storage.caches.names.uv",
+ pip: "settings.resources.storage.caches.names.pip",
+ npm: "settings.resources.storage.caches.names.npm",
+ bun: "settings.resources.storage.caches.names.bun",
+ // biome-ignore lint/style/useNamingConvention: API schema
+ torch_inductor: "settings.resources.storage.caches.names.torchInductor",
+ // biome-ignore lint/style/useNamingConvention: API schema
+ torch_extensions: "settings.resources.storage.caches.names.torchExtensions",
+ triton: "settings.resources.storage.caches.names.triton",
+ cuda: "settings.resources.storage.caches.names.cuda",
+ numba: "settings.resources.storage.caches.names.numba",
+ matplotlib: "settings.resources.storage.caches.names.matplotlib",
+ vllm: "settings.resources.storage.caches.names.vllm",
+ // biome-ignore lint/style/useNamingConvention: API schema
+ unsloth_compiled: "settings.resources.storage.caches.names.unslothCompiled",
+ // biome-ignore lint/style/useNamingConvention: API schema
+ hf_xet: "settings.resources.storage.caches.names.hfXet",
+ // biome-ignore lint/style/useNamingConvention: API schema
+ hf_assets: "settings.resources.storage.caches.names.hfAssets",
+ // biome-ignore lint/style/useNamingConvention: API schema
+ hf_datasets: "settings.resources.storage.caches.names.hfDatasets",
+ // biome-ignore lint/style/useNamingConvention: API schema
+ hf_hub: "settings.resources.storage.caches.names.hfHub",
+};
+
+const OPT_IN_COST_KEYS: Partial<Record<CacheKey, TranslationKey>> = {
+ // biome-ignore lint/style/useNamingConvention: API schema
+ hf_hub: "settings.resources.storage.caches.hubCost",
+ // biome-ignore lint/style/useNamingConvention: API schema
+ hf_datasets: "settings.resources.storage.caches.datasetsCost",
+};
+
+/** Caches whose contents are the repositories the Hub inventory reports. */
+const HUB_INVENTORY_KEYS: ReadonlySet<CacheKey> = new Set<CacheKey>([
+ "hf_hub",
+ "hf_datasets",
+]);
+
+/** What a confirmation is about: everything reclaimable, or one opt-in cache. */
+type PurgeTarget = { kind: "bulk" } | { kind: "single"; key: CacheKey };
+
+/**
+ * The body of the confirmation for clearing one cache, as translation keys.
+ *
+ * The generic assurance ends with "downloaded models ... are not touched",
+ * which is true of a bulk clear and the opposite of the truth for the model
+ * cache itself, so the hub clear says only what it costs.
+ */
+export function singleClearDescriptionKeys(key: CacheKey): TranslationKey[] {
+ const cost = OPT_IN_COST_KEYS[key];
+ const spared: TranslationKey[] =
+ key === "hf_hub" ? [] : ["settings.resources.storage.caches.safety"];
+ return cost ? [cost, ...spared] : spared;
+}
+
+function presentCaches(inventory: CacheInventory | null): CacheEntry[] {
+ if (!inventory) return [];
+ return inventory.caches.filter((entry) => entry.present);
+}
+
+export function CacheStorageRows() {
+ const t = useT();
+ const [inventory, setInventory] = useState<CacheInventory | null>(null);
+ const [loading, setLoading] = useState(true);
+ const [loadError, setLoadError] = useState<string | null>(null);
+ const [expanded, setExpanded] = useState(false);
+ const [target, setTarget] = useState<PurgeTarget | null>(null);
+ const [clearing, setClearing] = useState(false);
+
+ // A measurement installs itself only while it is the newest one asked for.
+ // Two can overlap and finish in either order, so without this the rows can
+ // settle on the folder the user moved off. A purge claims a number too.
+ const latestRequest = useRef(0);
+
+ const refresh = useCallback(
+ async (options: { refresh?: boolean } = {}) => {
+ const request = ++latestRequest.current;
+ setLoading(true);
+ try {
+ const next = await loadCacheInventory(options);
+ if (request !== latestRequest.current) return;
+ setInventory(next);
+ setLoadError(null);
+ } catch (error) {
+ if (request !== latestRequest.current) return;
+ setLoadError(
+ error instanceof Error
+ ? error.message
+ : t("settings.resources.storage.caches.measureFailed"),
+ );
+ } finally {
+ if (request === latestRequest.current) setLoading(false);
+ }
+ },
+ [t],
+ );
+
+ // Models Folder sits above these rows in the same section and saving it bumps
+ // the inventory version. Without this the Hugging Face rows keep the old
+ // folder's path and size beside a Clear that acts on the new one.
+ const inventoryVersion = useInventoryVersion();
+ const measuredVersion = useRef(inventoryVersion);
+
+ useEffect(() => {
+ // A move must force the re-measure, since the memoised reading is the one
+ // being replaced. The first load is not forced: a cold walk costs seconds.
+ const moved = measuredVersion.current !== inventoryVersion;
+ measuredVersion.current = inventoryVersion;
+ void refresh(moved ? { refresh: true } : {});
+ }, [refresh, inventoryVersion]);
+
+ const entries = presentCaches(inventory);
+ const bulkKeys = inventory ? bulkPurgeKeys(inventory) : [];
+ const reclaimable = inventory?.reclaimableBytes ?? 0;
+
+ const runPurge = async (keys: readonly CacheKey[]) => {
+ setClearing(true);
+ const request = ++latestRequest.current;
+ try {
+ const outcome = await purgeCaches(keys);
+ if (request === latestRequest.current) setInventory(outcome.inventory);
+ if (keys.some((key) => HUB_INVENTORY_KEYS.has(key))) {
+ // Every cached model or dataset just went, so the Hub and the picker
+ // hear about it the way they do for a delete. The mark takes our own
+ // bump, or the rows would pay a cold walk for what they already hold.
+ bumpInventoryVersion();
+ measuredVersion.current = getInventoryVersion();
+ }
+ setTarget(null);
+ const failures = outcome.results.flatMap((result) => result.errors);
+ if (failures.length > 0) {
+ toast.warning(t("settings.resources.storage.caches.partial"), {
+ description: failures[0],
+ });
+ return;
+ }
+ toast.success(
+ t("settings.resources.storage.caches.cleared", {
+ size: formatCacheSize(outcome.freedBytes),
+ }),
+ );
+ } catch (error) {
+ toast.error(t("settings.resources.storage.caches.clearFailed"), {
+ description: error instanceof Error ? error.message : undefined,
+ });
+ } finally {
+ setClearing(false);
+ // Whatever measurement this superseded will not clear it.
+ if (request === latestRequest.current) setLoading(false);
+ }
+ };
+
+ const confirmTitle =
+ target?.kind === "single"
+ ? t("settings.resources.storage.caches.confirmOneTitle", {
+ name: t(CACHE_NAME_KEYS[target.key]),
+ })
+ : t("settings.resources.storage.caches.confirmTitle");
+ const confirmDescription =
+ target?.kind === "single"
+ ? singleClearDescriptionKeys(target.key)
+ .map((key) => t(key))
+ .join(" ")
+ : `${t("settings.resources.storage.caches.confirmDescription", {
+ size: formatCacheSize(reclaimable),
+ })} ${t("settings.resources.storage.caches.safety")}`;
+
+ return (
+ <>
+ <SettingsRow
+ label={t("settings.resources.storage.caches.label")}
+ description={
+ loadError
+ ? loadError
+ : loading && !inventory
+ ? t("settings.resources.storage.caches.measuring")
+ : t("settings.resources.storage.caches.description", {
+ size: formatCacheSize(inventory?.totalBytes ?? 0),
+ reclaimable: formatCacheSize(reclaimable),
+ })
+ }
+ hint={t("settings.resources.storage.caches.hint")}
+ >
+ <div className="flex items-center gap-2">
+ <Button
+ variant="ghost"
+ size="sm"
+ className="h-8"
+ disabled={loading || clearing}
+ onClick={() => void refresh({ refresh: true })}
+ >
+ {t("settings.resources.storage.caches.recheckAction")}
+ </Button>
+ <Button
+ variant="ghost"
+ size="sm"
+ className="h-8"
+ disabled={loading || clearing}
+ onClick={() => setExpanded((open) => !open)}
+ >
+ {expanded
+ ? t("settings.resources.storage.caches.hideDetailsAction")
+ : t("settings.resources.storage.caches.detailsAction")}
+ </Button>
+ <Button
+ variant="outline"
+ size="sm"
+ className="h-8"
+ disabled={
+ loading || clearing || loadError !== null || bulkKeys.length === 0
+ }
+ onClick={() => setTarget({ kind: "bulk" })}
+ >
+ {t("settings.resources.storage.caches.clearAction")}
+ </Button>
+ </div>
+ </SettingsRow>
+
+ {expanded ? (
+ <div className="flex flex-col pl-3.5">
+ {entries.length === 0 ? (
+ <p className="py-2 text-xs text-muted-foreground">
+ {t("settings.resources.storage.caches.empty")}
+ </p>
+ ) : (
+ entries.map((entry) => (
+ <div
+ key={entry.key}
+ className="flex flex-wrap items-center justify-between gap-2 border-t border-border/60 py-2"
+ >
+ <div className="flex min-w-0 flex-col gap-0.5">
+ <span className="text-sm text-foreground">
+ {t(CACHE_NAME_KEYS[entry.key])}
+ </span>
+ <span
+ title={entry.paths.join("\n")}
+ className="max-w-lg truncate font-mono text-[11px] text-muted-foreground"
+ >
+ {entry.paths[0] ?? ""}
+ </span>
+ {entry.optIn && OPT_IN_COST_KEYS[entry.key] ? (
+ <span className="text-xs text-amber-600 dark:text-amber-400">
+ {t(OPT_IN_COST_KEYS[entry.key] as TranslationKey)}
+ </span>
+ ) : null}
+ {entry.blockedReason ? (
+ <span className="text-xs text-muted-foreground">
+ {t("settings.resources.storage.caches.blocked", {
+ reason: entry.blockedReason,
+ })}
+ </span>
+ ) : null}
+ </div>
+ <div className="flex items-center gap-3">
+ <span className="text-xs tabular-nums text-muted-foreground">
+ {formatCacheSize(entry.sizeBytes)}
+ </span>
+ <Button
+ variant="ghost"
+ size="xs"
+ // loading and loadError, like the buttons above: the rows
+ // show the last inventory that arrived while a clear
+ // resolves its key against the current folder.
+ disabled={
+ loading ||
+ clearing ||
+ loadError !== null ||
+ !entry.purgeable ||
+ entry.entryCount === 0
+ }
+ onClick={() =>
+ entry.optIn
+ ? setTarget({ kind: "single", key: entry.key })
+ : void runPurge([entry.key])
+ }
+ >
+ {t("settings.resources.storage.caches.clearOneAction")}
+ </Button>
+ </div>
+ </div>
+ ))
+ )}
+ </div>
+ ) : null}
+
+ <Dialog
+ open={target !== null}
+ onOpenChange={(open) => {
+ if (!open) setTarget(null);
+ }}
+ >
+ <DialogContent className="max-w-md">
+ <DialogHeader>
+ <DialogTitle>{confirmTitle}</DialogTitle>
+ <DialogDescription>{confirmDescription}</DialogDescription>
+ </DialogHeader>
+ <DialogFooter>
+ <Button variant="outline" onClick={() => setTarget(null)}>
+ {t("common.cancel")}
+ </Button>
+ <Button
+ // A failed measurement is the same hazard as one still running.
+ disabled={loading || clearing || loadError !== null}
+ className="bg-destructive hover:bg-destructive/90 text-destructive-foreground"
+ onClick={() =>
+ void runPurge(
+ target?.kind === "single" ? [target.key] : bulkKeys,
+ )
+ }
+ >
+ {clearing
+ ? t("settings.resources.storage.caches.clearingAction")
+ : t("settings.resources.storage.caches.clearAction")}
+ </Button>
+ </DialogFooter>
+ </DialogContent>
+ </Dialog>
+ </>
+ );
+}
diff --git a/studio/frontend/src/features/settings/settings-search.ts b/studio/frontend/src/features/settings/settings-search.ts
index 66460bc26bd..289455cb40d 100644
--- a/studio/frontend/src/features/settings/settings-search.ts
+++ b/studio/frontend/src/features/settings/settings-search.ts
@@ -90,6 +90,7 @@ export const SETTINGS_SEARCH_INDEX: Record<SettingsTab, TranslationKey[]> = {
"settings.resources.storage.modelsFolder",
"settings.resources.storage.futureDownloads",
"settings.resources.storage.systemDisk",
+ "settings.resources.storage.caches.label",
"settings.resources.environment.title",
"settings.resources.environment.backend",
"settings.resources.environment.python",
@@ -307,6 +308,10 @@ export const SETTINGS_SEARCH_KEYWORDS: Partial<
> = {
"settings.resources.storage.modelsFolder":
"settings.resources.storage.modelsFolderKeywords",
+ // "purge", "prune" and the tool names are in none of the labels, so the row
+ // the feature is named after was unreachable by search.
+ "settings.resources.storage.caches.label":
+ "settings.resources.storage.caches.keywords",
// mlock, vram, ulimit and pin are in none of these labels, so search
// missed the rows the feature is named after.
"settings.resources.modelMemory.title":
diff --git a/studio/frontend/src/features/settings/tabs/resources-tab.tsx b/studio/frontend/src/features/settings/tabs/resources-tab.tsx
index a12548cff7e..a7f30cab9f7 100644
--- a/studio/frontend/src/features/settings/tabs/resources-tab.tsx
+++ b/studio/frontend/src/features/settings/tabs/resources-tab.tsx
@@ -38,6 +38,7 @@ import {
loadHuggingFaceCacheSettings,
updateHuggingFaceCacheSettings,
} from "../api/hugging-face-cache";
+import { CacheStorageRows } from "../components/cache-storage-rows";
import { LlamaBackendSection } from "../components/llama-backend-section";
import { ModelMemorySection } from "../components/model-memory-section";
import { SettingsRow } from "../components/settings-row";
@@ -880,6 +881,7 @@ export function ResourcesTab() {
) : null}
</div>
</SettingsRow>
+ <CacheStorageRows />
</SettingsSection>
<FolderBrowser
diff --git a/studio/frontend/src/i18n/locales/ar.ts b/studio/frontend/src/i18n/locales/ar.ts
index 54f510e5e74..303cff020b2 100644
--- a/studio/frontend/src/i18n/locales/ar.ts
+++ b/studio/frontend/src/i18n/locales/ar.ts
@@ -1385,6 +1385,54 @@ export const ar = {
copied: "تم نسخ المسار",
openError: "تعذّر فتح المجلد",
copyError: "تعذّر نسخ المسار",
+ caches: {
+ label: "ملفات ذاكرة التخزين المؤقت",
+ description:
+ "{size} في ذاكرات التخزين المؤقت، يمكن مسح {reclaimable} منها الآن.",
+ hint: "تنزيلات الحزم والنوى المُصرَّفة وذاكرات النقل المؤقتة التي تعيد Unsloth بناءها عند الحاجة إليها. لا يتم هنا مسح النماذج المُنزَّلة أو المشاريع أو المحادثات أو الإعدادات أو رمز Hugging Face الخاص بك.",
+ keywords:
+ "ذاكرة مؤقت تخزين كاش مسح تنظيف تفريغ مساحة قرص مؤقتة مُصرَّف cache caches purge prune clear clean free space disk uv pip npm bun triton inductor cuda numba matplotlib vllm compiled xet temporary",
+ measuring: "جارٍ قياس أحجام ذاكرات التخزين المؤقت...",
+ measureFailed: "تعذّر قياس ذاكرات التخزين المؤقت",
+ empty: "لم يتم العثور على ملفات ذاكرة تخزين مؤقت.",
+ detailsAction: "التفاصيل",
+ recheckAction: "إعادة الفحص",
+ hideDetailsAction: "إخفاء التفاصيل",
+ clearAction: "مسح ذاكرات التخزين المؤقت",
+ clearOneAction: "مسح",
+ clearingAction: "جارٍ المسح...",
+ confirmTitle: "هل تريد مسح الملفات المخزّنة مؤقتًا؟",
+ confirmDescription: "سيؤدي ذلك إلى تحرير نحو {size}.",
+ confirmOneTitle: "هل تريد مسح {name}؟",
+ safety:
+ "تعيد Unsloth بناء ذاكرة التخزين المؤقت في المرة التالية التي تحتاج إليها. لن تُمَس النماذج المُنزَّلة أو المشاريع أو المحادثات أو الإعدادات أو رمز Hugging Face الخاص بك.",
+ hubCost:
+ "هذه هي ذاكرة النماذج المؤقتة. مسحها يعني تنزيل تلك النماذج من جديد عند استخدامها في المرة القادمة.",
+ datasetsCost:
+ "مسح هذا يعني تنزيل مجموعات البيانات تلك من جديد عند استخدامها في المرة القادمة.",
+ blocked: "لم يتم المسح: {reason}",
+ cleared: "تم مسح {size}",
+ partial: "تعذّرت إزالة بعض ملفات ذاكرة التخزين المؤقت",
+ clearFailed: "تعذّر مسح ذاكرات التخزين المؤقت",
+ names: {
+ uv: "ذاكرة حزم uv المؤقتة",
+ pip: "ذاكرة تنزيلات pip المؤقتة",
+ npm: "ذاكرة حزم npm المؤقتة",
+ bun: "ذاكرة حزم Bun المؤقتة",
+ torchInductor: "ذاكرة تصريف Torch Inductor المؤقتة",
+ torchExtensions: "بِنى امتدادات Torch",
+ triton: "ذاكرة نوى Triton المؤقتة",
+ cuda: "ذاكرة نوى CUDA المؤقتة",
+ numba: "ذاكرة تصريف Numba المؤقتة",
+ matplotlib: "ذاكرة خطوط Matplotlib المؤقتة",
+ vllm: "ذاكرة vLLM المؤقتة",
+ unslothCompiled: "وحدات Unsloth المُصرَّفة",
+ hfXet: "ذاكرة نقل Hugging Face المؤقتة",
+ hfAssets: "ذاكرة أصول Hugging Face المؤقتة",
+ hfDatasets: "ذاكرة مجموعات بيانات Hugging Face المؤقتة",
+ hfHub: "ذاكرة نماذج Hugging Face المؤقتة",
+ },
+ },
futureDownloads: "التنزيلات الجديدة فقط",
environmentManaged: "يُدار عبر متغيّر البيئة {variable}.",
locationFree: "{free} متاح",
diff --git a/studio/frontend/src/i18n/locales/de.ts b/studio/frontend/src/i18n/locales/de.ts
index 237bd5cbafc..ad5a7895249 100644
--- a/studio/frontend/src/i18n/locales/de.ts
+++ b/studio/frontend/src/i18n/locales/de.ts
@@ -1426,6 +1426,54 @@ export const de = {
copied: "Pfad kopiert",
openError: "Der Ordner konnte nicht geöffnet werden",
copyError: "Der Pfad konnte nicht kopiert werden",
+ caches: {
+ label: "Cache-Dateien",
+ description:
+ "{size} in Caches, davon können {reclaimable} jetzt geleert werden.",
+ hint: "Paket-Downloads, kompilierte Kernel und Übertragungs-Caches, die Unsloth bei Bedarf neu aufbaut. Heruntergeladene Modelle, Projekte, Chats, Einstellungen und Ihr Hugging Face-Token werden hier nie geleert.",
+ keywords:
+ "Cache Caches leeren löschen bereinigen aufräumen Speicherplatz freigeben Festplatte temporär kompiliert cache caches purge prune clear clean free space disk uv pip npm bun triton inductor cuda numba matplotlib vllm compiled xet temporary",
+ measuring: "Cache-Größen werden ermittelt...",
+ measureFailed: "Die Caches konnten nicht gemessen werden",
+ empty: "Keine Cache-Dateien gefunden.",
+ detailsAction: "Details",
+ recheckAction: "Erneut prüfen",
+ hideDetailsAction: "Details ausblenden",
+ clearAction: "Caches leeren",
+ clearOneAction: "Leeren",
+ clearingAction: "Wird geleert...",
+ confirmTitle: "Zwischengespeicherte Dateien leeren?",
+ confirmDescription: "Das gibt etwa {size} frei.",
+ confirmOneTitle: "{name} leeren?",
+ safety:
+ "Unsloth baut einen Cache beim nächsten Bedarf neu auf. Heruntergeladene Modelle, Projekte, Chats, Einstellungen und Ihr Hugging Face-Token bleiben unberührt.",
+ hubCost:
+ "Das ist der Modell-Cache. Wenn Sie ihn leeren, werden diese Modelle beim nächsten Verwenden erneut heruntergeladen.",
+ datasetsCost:
+ "Wenn Sie das leeren, werden diese Datensätze beim nächsten Verwenden erneut heruntergeladen.",
+ blocked: "Nicht geleert: {reason}",
+ cleared: "{size} geleert",
+ partial: "Einige Cache-Dateien konnten nicht entfernt werden",
+ clearFailed: "Die Caches konnten nicht geleert werden",
+ names: {
+ uv: "uv-Paket-Cache",
+ pip: "pip-Download-Cache",
+ npm: "npm-Paket-Cache",
+ bun: "Bun-Paket-Cache",
+ torchInductor: "Torch Inductor-Kompilierungs-Cache",
+ torchExtensions: "Torch-Erweiterungs-Builds",
+ triton: "Triton-Kernel-Cache",
+ cuda: "CUDA-Kernel-Cache",
+ numba: "Numba-Kompilierungs-Cache",
+ matplotlib: "Matplotlib-Schriften-Cache",
+ vllm: "vLLM-Cache",
+ unslothCompiled: "Kompilierte Unsloth-Module",
+ hfXet: "Hugging Face-Übertragungs-Cache",
+ hfAssets: "Hugging Face-Asset-Cache",
+ hfDatasets: "Hugging Face-Datensatz-Cache",
+ hfHub: "Hugging Face-Modell-Cache",
+ },
+ },
},
environment: {
title: "Umgebung",
diff --git a/studio/frontend/src/i18n/locales/en.ts b/studio/frontend/src/i18n/locales/en.ts
index e1bf81a08ef..a3be87924bd 100644
--- a/studio/frontend/src/i18n/locales/en.ts
+++ b/studio/frontend/src/i18n/locales/en.ts
@@ -1395,6 +1395,54 @@ export const en = {
copied: "Path copied",
openError: "Couldn't open the folder",
copyError: "Couldn't copy the path",
+ caches: {
+ label: "Cache files",
+ description: "{size} in caches, of which {reclaimable} can be cleared now.",
+ hint: "Package downloads, compiled kernels and transfer caches that Unsloth rebuilds when it needs them. Downloaded models, projects, chats, settings and your Hugging Face token are never cleared here.",
+ // Not rendered: extra terms the settings search matches this row on.
+ keywords:
+ "cache caches purge prune clear clean free space disk uv pip npm bun triton inductor cuda numba matplotlib vllm compiled xet temporary",
+ measuring: "Measuring cache sizes...",
+ measureFailed: "Couldn't measure the caches",
+ empty: "No cache files found.",
+ detailsAction: "Details",
+ recheckAction: "Recheck",
+ hideDetailsAction: "Hide details",
+ clearAction: "Clear caches",
+ clearOneAction: "Clear",
+ clearingAction: "Clearing...",
+ confirmTitle: "Clear cached files?",
+ confirmDescription: "This frees about {size}.",
+ confirmOneTitle: "Clear {name}?",
+ safety:
+ "Unsloth rebuilds a cache the next time it needs it. Downloaded models, projects, chats, settings and your Hugging Face token are not touched.",
+ hubCost:
+ "This is the model cache. Clearing it downloads those models again the next time you use them.",
+ datasetsCost:
+ "Clearing this downloads those datasets again the next time you use them.",
+ blocked: "Not cleared: {reason}",
+ cleared: "Cleared {size}",
+ partial: "Some cache files could not be removed",
+ clearFailed: "Couldn't clear the caches",
+ names: {
+ uv: "uv package cache",
+ pip: "pip download cache",
+ npm: "npm package cache",
+ bun: "Bun package cache",
+ torchInductor: "Torch Inductor compile cache",
+ torchExtensions: "Torch extension builds",
+ triton: "Triton kernel cache",
+ cuda: "CUDA kernel cache",
+ numba: "Numba compile cache",
+ matplotlib: "Matplotlib font cache",
+ vllm: "vLLM cache",
+ unslothCompiled: "Unsloth compiled modules",
+ hfXet: "Hugging Face transfer cache",
+ hfAssets: "Hugging Face asset cache",
+ hfDatasets: "Hugging Face dataset cache",
+ hfHub: "Hugging Face model cache",
+ },
+ },
},
environment: {
title: "Environment",
diff --git a/studio/frontend/src/i18n/locales/es.ts b/studio/frontend/src/i18n/locales/es.ts
index e6b21bc1dbc..d8c0cbbdc5a 100644
--- a/studio/frontend/src/i18n/locales/es.ts
+++ b/studio/frontend/src/i18n/locales/es.ts
@@ -1409,6 +1409,54 @@ export const es = {
copied: "Ruta copiada",
openError: "No se pudo abrir la carpeta",
copyError: "No se pudo copiar la ruta",
+ caches: {
+ label: "Archivos de caché",
+ description:
+ "{size} en cachés, de los cuales {reclaimable} se pueden borrar ahora.",
+ hint: "Descargas de paquetes, kernels compilados y cachés de transferencia que Unsloth vuelve a crear cuando los necesita. Los modelos descargados, los proyectos, los chats, los ajustes y tu token de Hugging Face nunca se borran aquí.",
+ keywords:
+ "caché cachés borrar limpiar vaciar purgar liberar espacio disco temporal compilado cache caches purge prune clear clean free space disk uv pip npm bun triton inductor cuda numba matplotlib vllm compiled xet temporary",
+ measuring: "Midiendo el tamaño de las cachés...",
+ measureFailed: "No se pudieron medir las cachés",
+ empty: "No se encontraron archivos de caché.",
+ detailsAction: "Detalles",
+ recheckAction: "Volver a comprobar",
+ hideDetailsAction: "Ocultar detalles",
+ clearAction: "Borrar cachés",
+ clearOneAction: "Borrar",
+ clearingAction: "Borrando...",
+ confirmTitle: "¿Borrar los archivos en caché?",
+ confirmDescription: "Esto libera unos {size}.",
+ confirmOneTitle: "¿Borrar {name}?",
+ safety:
+ "Unsloth vuelve a crear una caché la próxima vez que la necesita. Los modelos descargados, los proyectos, los chats, los ajustes y tu token de Hugging Face no se tocan.",
+ hubCost:
+ "Esta es la caché de modelos. Si la borras, esos modelos se descargarán de nuevo la próxima vez que los uses.",
+ datasetsCost:
+ "Si borras esto, esos conjuntos de datos se descargarán de nuevo la próxima vez que los uses.",
+ blocked: "No se borró: {reason}",
+ cleared: "Se borraron {size}",
+ partial: "Algunos archivos de caché no se pudieron eliminar",
+ clearFailed: "No se pudieron borrar las cachés",
+ names: {
+ uv: "Caché de paquetes de uv",
+ pip: "Caché de descargas de pip",
+ npm: "Caché de paquetes de npm",
+ bun: "Caché de paquetes de Bun",
+ torchInductor: "Caché de compilación de Torch Inductor",
+ torchExtensions: "Compilaciones de extensiones de Torch",
+ triton: "Caché de kernels de Triton",
+ cuda: "Caché de kernels de CUDA",
+ numba: "Caché de compilación de Numba",
+ matplotlib: "Caché de fuentes de Matplotlib",
+ vllm: "Caché de vLLM",
+ unslothCompiled: "Módulos compilados de Unsloth",
+ hfXet: "Caché de transferencia de Hugging Face",
+ hfAssets: "Caché de recursos de Hugging Face",
+ hfDatasets: "Caché de conjuntos de datos de Hugging Face",
+ hfHub: "Caché de modelos de Hugging Face",
+ },
+ },
futureDownloads: "Solo las descargas nuevas",
environmentManaged: "Gestionado por la variable de entorno {variable}.",
locationFree: "{free} libres",
diff --git a/studio/frontend/src/i18n/locales/fr.ts b/studio/frontend/src/i18n/locales/fr.ts
index 9f37bdc47a2..10a830dcbb3 100644
--- a/studio/frontend/src/i18n/locales/fr.ts
+++ b/studio/frontend/src/i18n/locales/fr.ts
@@ -1413,6 +1413,54 @@ export const fr = {
copied: "Chemin copié",
openError: "Impossible d'ouvrir le dossier",
copyError: "Impossible de copier le chemin",
+ caches: {
+ label: "Fichiers de cache",
+ description:
+ "{size} dans les caches, dont {reclaimable} peuvent être vidés maintenant.",
+ hint: "Téléchargements de paquets, noyaux compilés et caches de transfert que Unsloth reconstruit quand il en a besoin. Les modèles téléchargés, les projets, les conversations, les paramètres et votre jeton Hugging Face ne sont jamais vidés ici.",
+ keywords:
+ "cache caches vider nettoyer purger supprimer libérer espace disque temporaire compilé cache caches purge prune clear clean free space disk uv pip npm bun triton inductor cuda numba matplotlib vllm compiled xet temporary",
+ measuring: "Mesure de la taille des caches...",
+ measureFailed: "Impossible de mesurer les caches",
+ empty: "Aucun fichier de cache trouvé.",
+ detailsAction: "Détails",
+ recheckAction: "Revérifier",
+ hideDetailsAction: "Masquer les détails",
+ clearAction: "Vider les caches",
+ clearOneAction: "Vider",
+ clearingAction: "Vidage en cours...",
+ confirmTitle: "Vider les fichiers en cache ?",
+ confirmDescription: "Cela libère environ {size}.",
+ confirmOneTitle: "Vider {name} ?",
+ safety:
+ "Unsloth reconstruit un cache la prochaine fois qu'il en a besoin. Les modèles téléchargés, les projets, les conversations, les paramètres et votre jeton Hugging Face ne sont pas touchés.",
+ hubCost:
+ "Il s'agit du cache des modèles. Le vider entraîne un nouveau téléchargement de ces modèles lors de leur prochaine utilisation.",
+ datasetsCost:
+ "Vider ceci entraîne un nouveau téléchargement de ces jeux de données lors de leur prochaine utilisation.",
+ blocked: "Non vidé : {reason}",
+ cleared: "{size} libérés",
+ partial: "Certains fichiers de cache n'ont pas pu être supprimés",
+ clearFailed: "Impossible de vider les caches",
+ names: {
+ uv: "Cache des paquets uv",
+ pip: "Cache des téléchargements pip",
+ npm: "Cache des paquets npm",
+ bun: "Cache des paquets Bun",
+ torchInductor: "Cache de compilation Torch Inductor",
+ torchExtensions: "Compilations d'extensions Torch",
+ triton: "Cache des noyaux Triton",
+ cuda: "Cache des noyaux CUDA",
+ numba: "Cache de compilation Numba",
+ matplotlib: "Cache des polices Matplotlib",
+ vllm: "Cache vLLM",
+ unslothCompiled: "Modules compilés Unsloth",
+ hfXet: "Cache de transfert Hugging Face",
+ hfAssets: "Cache des ressources Hugging Face",
+ hfDatasets: "Cache des jeux de données Hugging Face",
+ hfHub: "Cache des modèles Hugging Face",
+ },
+ },
futureDownloads: "Nouveaux téléchargements uniquement",
environmentManaged: "Géré par la variable d'environnement {variable}.",
locationFree: "Espace libre : {free}",
diff --git a/studio/frontend/src/i18n/locales/hi.ts b/studio/frontend/src/i18n/locales/hi.ts
index bc08db04657..daeacca2e34 100644
--- a/studio/frontend/src/i18n/locales/hi.ts
+++ b/studio/frontend/src/i18n/locales/hi.ts
@@ -1388,6 +1388,54 @@ export const hi = {
copied: "पथ कॉपी किया गया",
openError: "फ़ोल्डर नहीं खोला जा सका",
copyError: "पथ कॉपी नहीं किया जा सका",
+ caches: {
+ label: "कैश फ़ाइलें",
+ description:
+ "कैश में {size}, जिनमें से {reclaimable} अभी साफ़ किया जा सकता है।",
+ hint: "पैकेज डाउनलोड, कंपाइल किए गए कर्नेल और ट्रांसफ़र कैश जिन्हें Unsloth ज़रूरत पड़ने पर दोबारा बना लेता है। डाउनलोड किए गए मॉडल, प्रोजेक्ट, चैट, सेटिंग्स और आपका Hugging Face टोकन यहाँ कभी साफ़ नहीं किए जाते।",
+ keywords:
+ "कैश साफ़ करना हटाना खाली जगह डिस्क अस्थायी कंपाइल cache caches purge prune clear clean free space disk uv pip npm bun triton inductor cuda numba matplotlib vllm compiled xet temporary",
+ measuring: "कैश का आकार मापा जा रहा है...",
+ measureFailed: "कैश मापे नहीं जा सके",
+ empty: "कोई कैश फ़ाइल नहीं मिली।",
+ detailsAction: "विवरण",
+ recheckAction: "फिर से जाँचें",
+ hideDetailsAction: "विवरण छिपाएँ",
+ clearAction: "कैश साफ़ करें",
+ clearOneAction: "साफ़ करें",
+ clearingAction: "साफ़ किया जा रहा है...",
+ confirmTitle: "कैश की गई फ़ाइलें साफ़ करें?",
+ confirmDescription: "इससे लगभग {size} खाली होगा।",
+ confirmOneTitle: "{name} साफ़ करें?",
+ safety:
+ "अगली बार ज़रूरत पड़ने पर Unsloth कैश दोबारा बना लेता है। डाउनलोड किए गए मॉडल, प्रोजेक्ट, चैट, सेटिंग्स और आपके Hugging Face टोकन को छुआ नहीं जाता।",
+ hubCost:
+ "यह मॉडल कैश है। इसे साफ़ करने पर अगली बार उपयोग करते समय वे मॉडल फिर से डाउनलोड होंगे।",
+ datasetsCost:
+ "इसे साफ़ करने पर अगली बार उपयोग करते समय वे डेटासेट फिर से डाउनलोड होंगे।",
+ blocked: "साफ़ नहीं किया गया: {reason}",
+ cleared: "{size} साफ़ किया गया",
+ partial: "कुछ कैश फ़ाइलें हटाई नहीं जा सकीं",
+ clearFailed: "कैश साफ़ नहीं किए जा सके",
+ names: {
+ uv: "uv पैकेज कैश",
+ pip: "pip डाउनलोड कैश",
+ npm: "npm पैकेज कैश",
+ bun: "Bun पैकेज कैश",
+ torchInductor: "Torch Inductor कंपाइल कैश",
+ torchExtensions: "Torch एक्सटेंशन बिल्ड",
+ triton: "Triton कर्नेल कैश",
+ cuda: "CUDA कर्नेल कैश",
+ numba: "Numba कंपाइल कैश",
+ matplotlib: "Matplotlib फ़ॉन्ट कैश",
+ vllm: "vLLM कैश",
+ unslothCompiled: "Unsloth कंपाइल किए गए मॉड्यूल",
+ hfXet: "Hugging Face ट्रांसफ़र कैश",
+ hfAssets: "Hugging Face एसेट कैश",
+ hfDatasets: "Hugging Face डेटासेट कैश",
+ hfHub: "Hugging Face मॉडल कैश",
+ },
+ },
futureDownloads: "केवल नए डाउनलोड",
environmentManaged: "{variable} एनवायरनमेंट वेरिएबल द्वारा प्रबंधित।",
locationFree: "{free} खाली",
diff --git a/studio/frontend/src/i18n/locales/it.ts b/studio/frontend/src/i18n/locales/it.ts
index b5f889852b6..d5869e5b578 100644
--- a/studio/frontend/src/i18n/locales/it.ts
+++ b/studio/frontend/src/i18n/locales/it.ts
@@ -1392,6 +1392,54 @@ export const it = {
copied: "Percorso copiato",
openError: "Impossibile aprire la cartella",
copyError: "Impossibile copiare il percorso",
+ caches: {
+ label: "File di cache",
+ description:
+ "{size} nelle cache, di cui {reclaimable} eliminabili subito.",
+ hint: "Download di pacchetti, kernel compilati e cache di trasferimento che Unsloth ricrea quando servono. I modelli scaricati, i progetti, le chat, le impostazioni e il tuo token Hugging Face non vengono mai eliminati qui.",
+ keywords:
+ "cache svuotare pulire eliminare liberare spazio disco temporaneo compilato cache caches purge prune clear clean free space disk uv pip npm bun triton inductor cuda numba matplotlib vllm compiled xet temporary",
+ measuring: "Misurazione delle dimensioni delle cache...",
+ measureFailed: "Impossibile misurare le cache",
+ empty: "Nessun file di cache trovato.",
+ detailsAction: "Dettagli",
+ recheckAction: "Ricontrolla",
+ hideDetailsAction: "Nascondi dettagli",
+ clearAction: "Svuota le cache",
+ clearOneAction: "Svuota",
+ clearingAction: "Svuotamento in corso...",
+ confirmTitle: "Svuotare i file nella cache?",
+ confirmDescription: "Libera circa {size}.",
+ confirmOneTitle: "Svuotare {name}?",
+ safety:
+ "Unsloth ricrea una cache la volta successiva in cui serve. I modelli scaricati, i progetti, le chat, le impostazioni e il tuo token Hugging Face non vengono toccati.",
+ hubCost:
+ "Questa è la cache dei modelli. Svuotandola, quei modelli verranno scaricati di nuovo al prossimo utilizzo.",
+ datasetsCost:
+ "Svuotandola, quei set di dati verranno scaricati di nuovo al prossimo utilizzo.",
+ blocked: "Non svuotata: {reason}",
+ cleared: "Liberati {size}",
+ partial: "Alcuni file di cache non sono stati rimossi",
+ clearFailed: "Impossibile svuotare le cache",
+ names: {
+ uv: "Cache dei pacchetti uv",
+ pip: "Cache dei download pip",
+ npm: "Cache dei pacchetti npm",
+ bun: "Cache dei pacchetti Bun",
+ torchInductor: "Cache di compilazione Torch Inductor",
+ torchExtensions: "Build delle estensioni Torch",
+ triton: "Cache dei kernel Triton",
+ cuda: "Cache dei kernel CUDA",
+ numba: "Cache di compilazione Numba",
+ matplotlib: "Cache dei font Matplotlib",
+ vllm: "Cache di vLLM",
+ unslothCompiled: "Moduli compilati di Unsloth",
+ hfXet: "Cache di trasferimento Hugging Face",
+ hfAssets: "Cache delle risorse Hugging Face",
+ hfDatasets: "Cache dei set di dati Hugging Face",
+ hfHub: "Cache dei modelli Hugging Face",
+ },
+ },
},
environment: {
title: "Ambiente",
diff --git a/studio/frontend/src/i18n/locales/ja.ts b/studio/frontend/src/i18n/locales/ja.ts
index bd7fc71c3b5..a0e7520fec1 100644
--- a/studio/frontend/src/i18n/locales/ja.ts
+++ b/studio/frontend/src/i18n/locales/ja.ts
@@ -1366,6 +1366,54 @@ export const ja = {
copied: "パスをコピーしました",
openError: "フォルダを開けませんでした",
copyError: "パスをコピーできませんでした",
+ caches: {
+ label: "キャッシュファイル",
+ description:
+ "キャッシュの合計は{size}で、そのうち{reclaimable}を今すぐ削除できます。",
+ hint: "パッケージのダウンロード、コンパイル済みカーネル、転送キャッシュなど、必要になったときにUnslothが再作成するものです。ダウンロード済みのモデル、プロジェクト、チャット、設定、Hugging Faceトークンがここで削除されることはありません。",
+ keywords:
+ "キャッシュ 削除 消去 クリア 掃除 空き容量 ディスク 一時 コンパイル cache caches purge prune clear clean free space disk uv pip npm bun triton inductor cuda numba matplotlib vllm compiled xet temporary",
+ measuring: "キャッシュサイズを計測しています...",
+ measureFailed: "キャッシュを計測できませんでした",
+ empty: "キャッシュファイルは見つかりませんでした。",
+ detailsAction: "詳細",
+ recheckAction: "再確認",
+ hideDetailsAction: "詳細を隠す",
+ clearAction: "キャッシュを削除",
+ clearOneAction: "削除",
+ clearingAction: "削除しています...",
+ confirmTitle: "キャッシュファイルを削除しますか?",
+ confirmDescription: "約{size}の空き容量ができます。",
+ confirmOneTitle: "{name}を削除しますか?",
+ safety:
+ "Unslothは次に必要になったときにキャッシュを再作成します。ダウンロード済みのモデル、プロジェクト、チャット、設定、Hugging Faceトークンは変更されません。",
+ hubCost:
+ "これはモデルキャッシュです。削除すると、次に使うときにそれらのモデルを再ダウンロードします。",
+ datasetsCost:
+ "削除すると、次に使うときにそれらのデータセットを再ダウンロードします。",
+ blocked: "削除されませんでした: {reason}",
+ cleared: "{size}を削除しました",
+ partial: "一部のキャッシュファイルを削除できませんでした",
+ clearFailed: "キャッシュを削除できませんでした",
+ names: {
+ uv: "uvパッケージキャッシュ",
+ pip: "pipダウンロードキャッシュ",
+ npm: "npmパッケージキャッシュ",
+ bun: "Bunパッケージキャッシュ",
+ torchInductor: "Torch Inductorコンパイルキャッシュ",
+ torchExtensions: "Torch拡張機能のビルド",
+ triton: "Tritonカーネルキャッシュ",
+ cuda: "CUDAカーネルキャッシュ",
+ numba: "Numbaコンパイルキャッシュ",
+ matplotlib: "Matplotlibフォントキャッシュ",
+ vllm: "vLLMキャッシュ",
+ unslothCompiled: "Unslothのコンパイル済みモジュール",
+ hfXet: "Hugging Face転送キャッシュ",
+ hfAssets: "Hugging Faceアセットキャッシュ",
+ hfDatasets: "Hugging Faceデータセットキャッシュ",
+ hfHub: "Hugging Faceモデルキャッシュ",
+ },
+ },
futureDownloads: "新規ダウンロードのみ",
environmentManaged: "環境変数 {variable} で管理されています。",
locationFree: "{free} 空き",
diff --git a/studio/frontend/src/i18n/locales/ko.ts b/studio/frontend/src/i18n/locales/ko.ts
index b528019bcc4..1a5084c62c1 100644
--- a/studio/frontend/src/i18n/locales/ko.ts
+++ b/studio/frontend/src/i18n/locales/ko.ts
@@ -1381,6 +1381,54 @@ export const ko = {
copied: "경로가 복사되었습니다",
openError: "폴더를 열지 못했습니다",
copyError: "경로를 복사하지 못했습니다",
+ caches: {
+ label: "캐시 파일",
+ description:
+ "캐시에 {size}이(가) 있으며 그중 {reclaimable}을(를) 지금 정리할 수 있습니다.",
+ hint: "패키지 다운로드, 컴파일된 커널, 전송 캐시로 Unsloth가 필요할 때 다시 만듭니다. 다운로드한 모델, 프로젝트, 채팅, 설정, Hugging Face 토큰은 여기서 절대 삭제되지 않습니다.",
+ keywords:
+ "캐시 정리 삭제 비우기 청소 여유 공간 디스크 임시 컴파일 cache caches purge prune clear clean free space disk uv pip npm bun triton inductor cuda numba matplotlib vllm compiled xet temporary",
+ measuring: "캐시 크기를 측정하는 중...",
+ measureFailed: "캐시를 측정하지 못했습니다",
+ empty: "캐시 파일이 없습니다.",
+ detailsAction: "자세히",
+ recheckAction: "다시 확인",
+ hideDetailsAction: "자세히 숨기기",
+ clearAction: "캐시 정리",
+ clearOneAction: "정리",
+ clearingAction: "정리하는 중...",
+ confirmTitle: "캐시 파일을 정리할까요?",
+ confirmDescription: "약 {size}의 공간이 확보됩니다.",
+ confirmOneTitle: "{name}을(를) 정리할까요?",
+ safety:
+ "Unsloth는 다음에 필요할 때 캐시를 다시 만듭니다. 다운로드한 모델, 프로젝트, 채팅, 설정, Hugging Face 토큰은 그대로 유지됩니다.",
+ hubCost:
+ "모델 캐시입니다. 정리하면 다음에 사용할 때 해당 모델을 다시 다운로드합니다.",
+ datasetsCost:
+ "정리하면 다음에 사용할 때 해당 데이터셋을 다시 다운로드합니다.",
+ blocked: "정리되지 않음: {reason}",
+ cleared: "{size} 정리함",
+ partial: "일부 캐시 파일을 삭제하지 못했습니다",
+ clearFailed: "캐시를 정리하지 못했습니다",
+ names: {
+ uv: "uv 패키지 캐시",
+ pip: "pip 다운로드 캐시",
+ npm: "npm 패키지 캐시",
+ bun: "Bun 패키지 캐시",
+ torchInductor: "Torch Inductor 컴파일 캐시",
+ torchExtensions: "Torch 확장 빌드",
+ triton: "Triton 커널 캐시",
+ cuda: "CUDA 커널 캐시",
+ numba: "Numba 컴파일 캐시",
+ matplotlib: "Matplotlib 폰트 캐시",
+ vllm: "vLLM 캐시",
+ unslothCompiled: "Unsloth 컴파일된 모듈",
+ hfXet: "Hugging Face 전송 캐시",
+ hfAssets: "Hugging Face 에셋 캐시",
+ hfDatasets: "Hugging Face 데이터셋 캐시",
+ hfHub: "Hugging Face 모델 캐시",
+ },
+ },
futureDownloads: "새 다운로드만",
environmentManaged: "{variable} 환경 변수로 관리됩니다.",
locationFree: "{free} 남음",
diff --git a/studio/frontend/src/i18n/locales/pt-br.ts b/studio/frontend/src/i18n/locales/pt-br.ts
index 3b573476beb..c380f226691 100644
--- a/studio/frontend/src/i18n/locales/pt-br.ts
+++ b/studio/frontend/src/i18n/locales/pt-br.ts
@@ -1397,6 +1397,54 @@ export const ptBR = {
copied: "Caminho copiado",
openError: "Não foi possível abrir a pasta",
copyError: "Não foi possível copiar o caminho",
+ caches: {
+ label: "Arquivos de cache",
+ description:
+ "{size} em caches, dos quais {reclaimable} podem ser limpos agora.",
+ hint: "Downloads de pacotes, kernels compilados e caches de transferência que o Unsloth recria quando precisa deles. Modelos baixados, projetos, conversas, configurações e o seu token do Hugging Face nunca são limpos aqui.",
+ keywords:
+ "cache caches limpar apagar esvaziar liberar espaço disco temporário compilado cache caches purge prune clear clean free space disk uv pip npm bun triton inductor cuda numba matplotlib vllm compiled xet temporary",
+ measuring: "Medindo o tamanho dos caches...",
+ measureFailed: "Não foi possível medir os caches",
+ empty: "Nenhum arquivo de cache encontrado.",
+ detailsAction: "Detalhes",
+ recheckAction: "Verificar novamente",
+ hideDetailsAction: "Ocultar detalhes",
+ clearAction: "Limpar caches",
+ clearOneAction: "Limpar",
+ clearingAction: "Limpando...",
+ confirmTitle: "Limpar os arquivos em cache?",
+ confirmDescription: "Isso libera cerca de {size}.",
+ confirmOneTitle: "Limpar {name}?",
+ safety:
+ "O Unsloth recria um cache na próxima vez que precisar dele. Modelos baixados, projetos, conversas, configurações e o seu token do Hugging Face não são afetados.",
+ hubCost:
+ "Este é o cache de modelos. Ao limpá-lo, esses modelos serão baixados novamente na próxima vez que você usá-los.",
+ datasetsCost:
+ "Ao limpar isso, esses conjuntos de dados serão baixados novamente na próxima vez que você usá-los.",
+ blocked: "Não foi limpo: {reason}",
+ cleared: "{size} liberados",
+ partial: "Não foi possível remover alguns arquivos de cache",
+ clearFailed: "Não foi possível limpar os caches",
+ names: {
+ uv: "Cache de pacotes do uv",
+ pip: "Cache de downloads do pip",
+ npm: "Cache de pacotes do npm",
+ bun: "Cache de pacotes do Bun",
+ torchInductor: "Cache de compilação do Torch Inductor",
+ torchExtensions: "Builds de extensões do Torch",
+ triton: "Cache de kernels do Triton",
+ cuda: "Cache de kernels do CUDA",
+ numba: "Cache de compilação do Numba",
+ matplotlib: "Cache de fontes do Matplotlib",
+ vllm: "Cache do vLLM",
+ unslothCompiled: "Módulos compilados do Unsloth",
+ hfXet: "Cache de transferência do Hugging Face",
+ hfAssets: "Cache de recursos do Hugging Face",
+ hfDatasets: "Cache de conjuntos de dados do Hugging Face",
+ hfHub: "Cache de modelos do Hugging Face",
+ },
+ },
futureDownloads: "Apenas novos downloads",
environmentManaged: "Gerenciado pela variável de ambiente {variable}.",
locationFree: "{free} livres",
diff --git a/studio/frontend/src/i18n/locales/ru.ts b/studio/frontend/src/i18n/locales/ru.ts
index 4b767624e60..e8936d00c69 100644
--- a/studio/frontend/src/i18n/locales/ru.ts
+++ b/studio/frontend/src/i18n/locales/ru.ts
@@ -1393,6 +1393,54 @@ export const ru = {
copied: "Путь скопирован",
openError: "Не удалось открыть папку",
copyError: "Не удалось скопировать путь",
+ caches: {
+ label: "Файлы кеша",
+ description:
+ "{size} в кешах, из них {reclaimable} можно очистить сейчас.",
+ hint: "Загрузки пакетов, скомпилированные ядра и кеши передачи, которые Unsloth создаёт заново, когда они нужны. Загруженные модели, проекты, чаты, настройки и ваш токен Hugging Face здесь никогда не очищаются.",
+ keywords:
+ "кеш кэш кеши очистить удалить почистить освободить место диск временные скомпилированные cache caches purge prune clear clean free space disk uv pip npm bun triton inductor cuda numba matplotlib vllm compiled xet temporary",
+ measuring: "Измерение размера кешей...",
+ measureFailed: "Не удалось измерить кеши",
+ empty: "Файлы кеша не найдены.",
+ detailsAction: "Подробности",
+ recheckAction: "Проверить снова",
+ hideDetailsAction: "Скрыть подробности",
+ clearAction: "Очистить кеши",
+ clearOneAction: "Очистить",
+ clearingAction: "Очистка...",
+ confirmTitle: "Очистить кешированные файлы?",
+ confirmDescription: "Это освободит примерно {size}.",
+ confirmOneTitle: "Очистить {name}?",
+ safety:
+ "Unsloth создаст кеш заново, когда он снова понадобится. Загруженные модели, проекты, чаты, настройки и ваш токен Hugging Face не затрагиваются.",
+ hubCost:
+ "Это кеш моделей. После очистки эти модели будут загружены заново при следующем использовании.",
+ datasetsCost:
+ "После очистки эти наборы данных будут загружены заново при следующем использовании.",
+ blocked: "Не очищено: {reason}",
+ cleared: "Очищено {size}",
+ partial: "Некоторые файлы кеша не удалось удалить",
+ clearFailed: "Не удалось очистить кеши",
+ names: {
+ uv: "Кеш пакетов uv",
+ pip: "Кеш загрузок pip",
+ npm: "Кеш пакетов npm",
+ bun: "Кеш пакетов Bun",
+ torchInductor: "Кеш компиляции Torch Inductor",
+ torchExtensions: "Сборки расширений Torch",
+ triton: "Кеш ядер Triton",
+ cuda: "Кеш ядер CUDA",
+ numba: "Кеш компиляции Numba",
+ matplotlib: "Кеш шрифтов Matplotlib",
+ vllm: "Кеш vLLM",
+ unslothCompiled: "Скомпилированные модули Unsloth",
+ hfXet: "Кеш передачи Hugging Face",
+ hfAssets: "Кеш ресурсов Hugging Face",
+ hfDatasets: "Кеш наборов данных Hugging Face",
+ hfHub: "Кеш моделей Hugging Face",
+ },
+ },
futureDownloads: "Только новые загрузки",
environmentManaged: "Управляется переменной окружения {variable}.",
locationFree: "{free} свободно",
diff --git a/studio/frontend/src/i18n/locales/zh-CN.ts b/studio/frontend/src/i18n/locales/zh-CN.ts
index ad1238a34d4..f8e4fb0c5bd 100644
--- a/studio/frontend/src/i18n/locales/zh-CN.ts
+++ b/studio/frontend/src/i18n/locales/zh-CN.ts
@@ -1357,6 +1357,51 @@ export const zhCN = {
copied: "路径已复制",
openError: "无法打开文件夹",
copyError: "无法复制路径",
+ caches: {
+ label: "缓存文件",
+ description: "缓存共占用{size},其中{reclaimable}可立即清理。",
+ hint: "包下载、已编译内核和传输缓存,Unsloth 在需要时会重新生成。已下载的模型、项目、对话、设置以及你的 Hugging Face 令牌不会在此被清理。",
+ keywords:
+ "缓存 清理 清除 清空 删除 释放 空间 磁盘 临时 已编译 cache caches purge prune clear clean free space disk uv pip npm bun triton inductor cuda numba matplotlib vllm compiled xet temporary",
+ measuring: "正在统计缓存大小...",
+ measureFailed: "无法统计缓存大小",
+ empty: "未找到缓存文件。",
+ detailsAction: "详情",
+ recheckAction: "重新检查",
+ hideDetailsAction: "隐藏详情",
+ clearAction: "清理缓存",
+ clearOneAction: "清理",
+ clearingAction: "正在清理...",
+ confirmTitle: "要清理缓存文件吗?",
+ confirmDescription: "这将释放约{size}。",
+ confirmOneTitle: "要清理{name}吗?",
+ safety:
+ "Unsloth 会在下次需要时重新生成缓存。已下载的模型、项目、对话、设置以及你的 Hugging Face 令牌不会受到影响。",
+ hubCost: "这是模型缓存。清理后,下次使用这些模型时会重新下载。",
+ datasetsCost: "清理后,下次使用这些数据集时会重新下载。",
+ blocked: "未清理:{reason}",
+ cleared: "已清理{size}",
+ partial: "部分缓存文件无法删除",
+ clearFailed: "无法清理缓存",
+ names: {
+ uv: "uv 包缓存",
+ pip: "pip 下载缓存",
+ npm: "npm 包缓存",
+ bun: "Bun 包缓存",
+ torchInductor: "Torch Inductor 编译缓存",
+ torchExtensions: "Torch 扩展构建",
+ triton: "Triton 内核缓存",
+ cuda: "CUDA 内核缓存",
+ numba: "Numba 编译缓存",
+ matplotlib: "Matplotlib 字体缓存",
+ vllm: "vLLM 缓存",
+ unslothCompiled: "Unsloth 编译模块",
+ hfXet: "Hugging Face 传输缓存",
+ hfAssets: "Hugging Face 资源缓存",
+ hfDatasets: "Hugging Face 数据集缓存",
+ hfHub: "Hugging Face 模型缓存",
+ },
+ },
futureDownloads: "仅对新下载生效",
environmentManaged: "由环境变量 {variable} 管理。",
locationFree: "{free} 可用",
diff --git a/studio/frontend/tests/cache-rows-model-folder.test.ts b/studio/frontend/tests/cache-rows-model-folder.test.ts
new file mode 100644
index 00000000000..b04ca02e1ed
--- /dev/null
+++ b/studio/frontend/tests/cache-rows-model-folder.test.ts
@@ -0,0 +1,339 @@
+// 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 rows sit directly under Models Folder in one section, and one of them
+// IS the model cache. So the two things this covers are what the rows say when
+// that folder moves, and what the confirmation promises before the models go.
+
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import test from "node:test";
+
+import { en } from "../src/i18n/locales/en.ts";
+import { loadWithStubs, stubJsxRuntime } from "./helpers/module-stubs.ts";
+
+const ROWS_URL = new URL(
+ "../src/features/settings/components/cache-storage-rows.tsx",
+ import.meta.url,
+);
+
+type Rows = {
+ singleClearDescriptionKeys: (key: string) => string[];
+};
+
+function loadRows(): Rows {
+ const noop = () => undefined;
+ return loadWithStubs<Rows>(ROWS_URL, {
+ react: {
+ useCallback: noop,
+ useEffect: noop,
+ useRef: () => ({ current: 0 }),
+ useState: () => [null, noop],
+ },
+ "react/jsx-runtime": stubJsxRuntime(),
+ "@/components/ui/button": { Button: noop },
+ "@/components/ui/dialog": {
+ Dialog: noop,
+ DialogContent: noop,
+ DialogDescription: noop,
+ DialogFooter: noop,
+ DialogHeader: noop,
+ DialogTitle: noop,
+ },
+ "@/features/hub/stores/inventory-events": { useInventoryVersion: () => 0 },
+ "@/i18n": { useT: () => (key: string) => key },
+ "@/lib/toast": { toast: {} },
+ "../api/caches": {
+ bulkPurgeKeys: () => [],
+ loadCacheInventory: async () => null,
+ purgeCaches: async () => null,
+ },
+ "./settings-row": { SettingsRow: noop },
+ });
+}
+
+const SAFETY = "settings.resources.storage.caches.safety";
+
+test("the model cache clear does not promise that models are untouched", () => {
+ // The generic assurance is the contradiction: it names downloaded models,
+ // which is exactly what an hf_hub clear deletes.
+ assert.ok(
+ en.settings.resources.storage.caches.safety.includes("Downloaded models"),
+ );
+ const { singleClearDescriptionKeys } = loadRows();
+
+ assert.deepEqual(singleClearDescriptionKeys("hf_hub"), [
+ "settings.resources.storage.caches.hubCost",
+ ]);
+ // It still holds for the caches that do spare the models.
+ assert.deepEqual(singleClearDescriptionKeys("hf_datasets"), [
+ "settings.resources.storage.caches.datasetsCost",
+ SAFETY,
+ ]);
+ assert.deepEqual(singleClearDescriptionKeys("unsloth_compiled"), [SAFETY]);
+});
+
+test("the bulk clear keeps the assurance, because it excludes the model cache", () => {
+ const source = readFileSync(ROWS_URL, "utf8");
+ // bulkPurgeKeys drops every opt-in cache, so "downloaded models are not
+ // touched" is true of the bulk dialog and only of the bulk dialog.
+ const bulk = source.slice(source.indexOf("confirmDescription"));
+ assert.match(bulk, /caches\.safety/);
+});
+
+test("the cache rows follow the model folder when it moves", () => {
+ const source = readFileSync(ROWS_URL, "utf8");
+ // Saving Models Folder bumps the inventory version, and the field sits in the
+ // same section as these rows: without this they keep showing the path and the
+ // size of the folder the user just moved off, next to a Clear button that
+ // acts on the new one.
+ assert.match(source, /useInventoryVersion\(\)/);
+ assert.match(source, /\}, \[refresh, inventoryVersion\]\);/);
+ // A move has to force the re-measure. The backend memoises a size for a
+ // minute, so an unforced read returns the very figures being replaced.
+ assert.match(source, /refresh\(moved \? \{ refresh: true \} : \{\}\)/);
+
+ const api = readFileSync(
+ new URL(
+ "../src/features/settings/api/hugging-face-cache.ts",
+ import.meta.url,
+ ),
+ "utf8",
+ );
+ assert.match(api, /bumpInventoryVersion\(\)/);
+});
+
+/** Drive the real component with a React the test steps by hand. */
+function driveRows(options: {
+ load: (options: { refresh?: boolean }) => Promise<unknown>;
+ purge?: (keys: readonly string[]) => Promise<unknown>;
+ version: () => number;
+}) {
+ const states: unknown[] = [];
+ const refs: { current: unknown }[] = [];
+ const callbacks: unknown[] = [];
+ let stateCursor = 0;
+ let refCursor = 0;
+ let callbackCursor = 0;
+ let previousDeps: unknown[] | null = null;
+ let pending: (() => void) | null = null;
+
+ const react = {
+ useState: (initial: unknown) => {
+ const index = stateCursor++;
+ if (states.length <= index) states[index] = initial;
+ return [
+ states[index],
+ (next: unknown) => {
+ states[index] =
+ typeof next === "function"
+ ? (next as (value: unknown) => unknown)(states[index])
+ : next;
+ },
+ ];
+ },
+ useRef: (initial: unknown) => (refs[refCursor++] ??= { current: initial }),
+ useCallback: (fn: unknown) => (callbacks[callbackCursor++] ??= fn),
+ useEffect: (effect: () => void, deps: unknown[]) => {
+ if (
+ previousDeps === null ||
+ deps.some((d, i) => d !== previousDeps?.[i])
+ ) {
+ previousDeps = deps;
+ pending = effect;
+ }
+ },
+ };
+
+ const rows = loadWithStubs<{ CacheStorageRows: () => unknown }>(ROWS_URL, {
+ react,
+ "react/jsx-runtime": stubJsxRuntime(),
+ "@/components/ui/button": { Button: "Button" },
+ "@/components/ui/dialog": {
+ Dialog: "Dialog",
+ DialogContent: "DialogContent",
+ DialogDescription: "DialogDescription",
+ DialogFooter: "DialogFooter",
+ DialogHeader: "DialogHeader",
+ DialogTitle: "DialogTitle",
+ },
+ "@/features/hub/stores/inventory-events": {
+ useInventoryVersion: options.version,
+ bumpInventoryVersion: () => undefined,
+ getInventoryVersion: options.version,
+ },
+ "@/i18n": { useT: () => (key: string) => key },
+ "@/lib/toast": {
+ toast: {
+ success: () => undefined,
+ warning: () => undefined,
+ error: () => undefined,
+ },
+ },
+ "../api/caches": {
+ bulkPurgeKeys: () => ["uv"],
+ loadCacheInventory: options.load,
+ purgeCaches: options.purge ?? (async () => ({})),
+ },
+ "./settings-row": { SettingsRow: "SettingsRow" },
+ });
+
+ return () => {
+ stateCursor = 0;
+ refCursor = 0;
+ callbackCursor = 0;
+ const tree = rows.CacheStorageRows();
+ const effect = pending;
+ pending = null;
+ effect?.();
+ return tree;
+ };
+}
+
+type Element = { type: unknown; props?: Record<string, unknown> };
+
+function* walk(node: unknown): Generator<Element> {
+ if (Array.isArray(node)) {
+ for (const child of node) yield* walk(child);
+ return;
+ }
+ if (!node || typeof node !== "object") return;
+ const element = node as Element;
+ yield element;
+ yield* walk(element.props?.children);
+}
+
+const buttons = (tree: unknown, label: string): Element[] =>
+ [...walk(tree)].filter(
+ (element) => element.type === "Button" && element.props?.children === label,
+ );
+
+const click = (element: Element | undefined) =>
+ (element?.props?.onClick as (() => void) | undefined)?.();
+
+const CLEAR_ONE = "settings.resources.storage.caches.clearOneAction";
+const DETAILS = "settings.resources.storage.caches.detailsAction";
+
+const inventory = (path: string) => ({
+ caches: [
+ {
+ key: "hf_hub",
+ group: "models",
+ optIn: true,
+ paths: [path],
+ // Zero bytes with entries in it: a clear is offered on what is there.
+ sizeBytes: 0,
+ entryCount: 3,
+ present: true,
+ purgeable: true,
+ blockedReason: null,
+ },
+ ],
+ totalBytes: 1000,
+ reclaimableBytes: 0,
+ freeBytes: 1,
+ totalDiskBytes: 2,
+});
+
+const settle = async () => {
+ for (let i = 0; i < 8; i++) await Promise.resolve();
+};
+
+test("the newest measurement wins, whatever order the walks finish in", async () => {
+ // Without a generation guard the slower FIRST request installs last, so the
+ // rows settle on the folder the user moved off while a clear resolves the new.
+ const pending: ((value: unknown) => void)[] = [];
+ let version = 0;
+ const render = driveRows({
+ load: () => new Promise((resolve) => pending.push(resolve)),
+ version: () => version,
+ });
+
+ render();
+ version = 1;
+ render();
+ assert.equal(pending.length, 2);
+
+ pending[1](inventory("/new/hub"));
+ await settle();
+ render();
+ pending[0](inventory("/old/hub"));
+ await settle();
+
+ const tree = render();
+ click(buttons(tree, DETAILS)[0]);
+ const paths = [...walk(render())]
+ .map((element) => element.props?.title)
+ .filter((title) => typeof title === "string");
+ assert.deepEqual(paths, ["/new/hub"]);
+});
+
+test("a clear waits for the measurement that is replacing the rows", async () => {
+ // While a re-measure runs the rows still show the PREVIOUS inventory, and
+ // purgeCaches resolves its key against the current folder on the backend.
+ const pending: ((value: unknown) => void)[] = [];
+ let version = 0;
+ const render = driveRows({
+ load: () => new Promise((resolve) => pending.push(resolve)),
+ version: () => version,
+ });
+
+ render();
+ pending[0](inventory("/old/hub"));
+ await settle();
+ click(buttons(render(), DETAILS)[0]);
+
+ const settled = render();
+ assert.equal(buttons(settled, CLEAR_ONE).length, 1);
+ assert.equal(buttons(settled, CLEAR_ONE)[0].props?.disabled, false);
+
+ version = 1;
+ render(); // the version change is seen here; the effect runs after the tree
+ const reloading = render();
+ assert.equal(buttons(reloading, CLEAR_ONE)[0].props?.disabled, true);
+ // ...and so does the confirmation, which is the button that actually deletes.
+ const confirm = [...walk(reloading)].filter(
+ (element) =>
+ element.type === "Button" &&
+ typeof element.props?.className === "string" &&
+ element.props.className.includes("bg-destructive"),
+ );
+ assert.equal(confirm.length, 1);
+ assert.equal(confirm[0].props?.disabled, true);
+});
+
+test("a measurement that failed leaves the clears disabled", async () => {
+ // The same hazard as a walk still running: the rows keep the last inventory
+ // that arrived while purgeCaches resolves each key against the new folder.
+ const pending: {
+ resolve: (value: unknown) => void;
+ reject: (reason: unknown) => void;
+ }[] = [];
+ let version = 0;
+ const render = driveRows({
+ load: () =>
+ new Promise((resolve, reject) => pending.push({ resolve, reject })),
+ version: () => version,
+ });
+
+ render();
+ pending[0].resolve(inventory("/old/hub"));
+ await settle();
+ click(buttons(render(), DETAILS)[0]);
+ assert.equal(buttons(render(), CLEAR_ONE)[0].props?.disabled, false);
+
+ version = 1;
+ render();
+ pending[1].reject(new Error("measure failed"));
+ await settle();
+
+ const failed = render();
+ assert.equal(buttons(failed, CLEAR_ONE)[0].props?.disabled, true);
+ const destructive = [...walk(failed)].filter(
+ (element) =>
+ element.type === "Button" &&
+ typeof element.props?.className === "string" &&
+ element.props.className.includes("bg-destructive"),
+ );
+ assert.equal(destructive[0].props?.disabled, true);
+});
diff --git a/studio/frontend/tests/settings-cache-purge.test.ts b/studio/frontend/tests/settings-cache-purge.test.ts
new file mode 100644
index 00000000000..e4c24d867df
--- /dev/null
+++ b/studio/frontend/tests/settings-cache-purge.test.ts
@@ -0,0 +1,188 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+// A purge names caches by key. The client must never be able to send a path, and a
+// bulk clear must never sweep up the caches whose deletion re-downloads models.
+
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import test from "node:test";
+
+import { loadWithStubs } from "./helpers/module-stubs.ts";
+
+type CachesApi = {
+ loadCacheInventory: () => Promise<unknown>;
+ purgeCaches: (keys: readonly string[]) => Promise<unknown>;
+ inventoryFromApi: (value: unknown) => {
+ caches: { key: string; sizeBytes: number; optIn: boolean }[];
+ totalBytes: number;
+ reclaimableBytes: number;
+ freeBytes: number | null;
+ };
+ bulkPurgeKeys: (inventory: unknown) => string[];
+};
+
+type Request = { url: string; init: RequestInit | undefined };
+
+function loadApi(responder: (url: string, init?: RequestInit) => Response): {
+ api: CachesApi;
+ requests: Request[];
+} {
+ const requests: Request[] = [];
+ const api = loadWithStubs<CachesApi>(
+ new URL("../src/features/settings/api/caches.ts", import.meta.url),
+ {
+ "@/features/auth": {
+ authFetch: async (url: string, init?: RequestInit) => {
+ requests.push({ url, init });
+ return responder(url, init);
+ },
+ },
+ "@/lib/format-fastapi-error": {
+ readFastApiError: async (_response: Response, fallback: string) =>
+ fallback,
+ },
+ },
+ );
+ return { api, requests };
+}
+
+function json(body: unknown): Response {
+ return new Response(JSON.stringify(body), {
+ status: 200,
+ headers: { "Content-Type": "application/json" },
+ });
+}
+
+const apiEntry = (
+ key: string,
+ overrides: Record<string, unknown> = {},
+): Record<string, unknown> => ({
+ key,
+ group: "packages",
+ // biome-ignore lint/style/useNamingConvention: API schema
+ opt_in: false,
+ paths: [`/cache/${key}`],
+ // biome-ignore lint/style/useNamingConvention: API schema
+ size_bytes: 1000,
+ // biome-ignore lint/style/useNamingConvention: API schema
+ entry_count: 2,
+ present: true,
+ purgeable: true,
+ // biome-ignore lint/style/useNamingConvention: API schema
+ blocked_reason: null,
+ ...overrides,
+});
+
+const apiInventory = (
+ caches: Record<string, unknown>[],
+): Record<string, unknown> => ({
+ caches,
+ // biome-ignore lint/style/useNamingConvention: API schema
+ total_bytes: 1000,
+ // biome-ignore lint/style/useNamingConvention: API schema
+ reclaimable_bytes: 1000,
+ // biome-ignore lint/style/useNamingConvention: API schema
+ free_bytes: 42,
+ // biome-ignore lint/style/useNamingConvention: API schema
+ total_disk_bytes: 100,
+});
+
+test("a purge posts cache keys and nothing that could be a path", async () => {
+ const { api, requests } = loadApi(() =>
+ json({
+ results: [
+ {
+ key: "uv",
+ // biome-ignore lint/style/useNamingConvention: API schema
+ freed_bytes: 5,
+ // biome-ignore lint/style/useNamingConvention: API schema
+ removed_entries: 1,
+ errors: [],
+ },
+ ],
+ // biome-ignore lint/style/useNamingConvention: API schema
+ freed_bytes: 5,
+ inventory: apiInventory([]),
+ }),
+ );
+
+ await api.purgeCaches(["uv", "triton"]);
+
+ assert.equal(requests.length, 1);
+ assert.equal(requests[0].url, "/api/settings/caches/purge");
+ assert.equal(requests[0].init?.method, "POST");
+ const body = JSON.parse(String(requests[0].init?.body));
+ assert.deepEqual(Object.keys(body), ["keys"]);
+ assert.deepEqual(body.keys, ["uv", "triton"]);
+});
+
+test("the client offers no way to name a directory", () => {
+ const source = readFileSync(
+ new URL("../src/features/settings/api/caches.ts", import.meta.url),
+ "utf8",
+ );
+ // The request body is built from keys alone: no path, dir or root field.
+ assert.match(source, /JSON\.stringify\(\{ keys \}\)/);
+ assert.doesNotMatch(source, /path:\s*[^;]*JSON\.stringify/);
+});
+
+test("a failed purge surfaces the backend's own message", async () => {
+ const { api } = loadApi(() => new Response(null, { status: 400 }));
+ await assert.rejects(api.purgeCaches(["uv"]), /Failed to clear the caches/);
+});
+
+test("the inventory maps the API's snake_case into the app's shape", async () => {
+ const { api } = loadApi(() =>
+ json(
+ apiInventory([
+ apiEntry("uv"),
+ // biome-ignore lint/style/useNamingConvention: API schema
+ apiEntry("hf_hub", { opt_in: true, group: "models" }),
+ ]),
+ ),
+ );
+ const inventory = (await api.loadCacheInventory()) as ReturnType<
+ CachesApi["inventoryFromApi"]
+ >;
+ assert.equal(inventory.caches[0].sizeBytes, 1000);
+ assert.equal(inventory.caches[0].optIn, false);
+ assert.equal(inventory.caches[1].optIn, true);
+ assert.equal(inventory.freeBytes, 42);
+});
+
+test("a bulk clear leaves out the model cache, the blocked and the empty", () => {
+ const { api } = loadApi(() => json({}));
+ const inventory = api.inventoryFromApi(
+ apiInventory([
+ apiEntry("uv"),
+ // Clearing this one re-downloads models, so it is asked for on its own.
+ // biome-ignore lint/style/useNamingConvention: API schema
+ apiEntry("hf_hub", { opt_in: true }),
+ // biome-ignore lint/style/useNamingConvention: API schema
+ apiEntry("hf_datasets", { opt_in: true }),
+ apiEntry("triton", {
+ purgeable: false,
+ // biome-ignore lint/style/useNamingConvention: API schema
+ blocked_reason: "sits inside the protected folder /outputs",
+ }),
+ // biome-ignore lint/style/useNamingConvention: API schema
+ apiEntry("numba", { present: false, size_bytes: 0, entry_count: 0 }),
+ // Nothing in it, so there is nothing for a clear to do.
+ // biome-ignore lint/style/useNamingConvention: API schema
+ apiEntry("vllm", { size_bytes: 0, entry_count: 0 }),
+ ]),
+ );
+ assert.deepEqual(api.bulkPurgeKeys(inventory), ["uv"]);
+});
+
+test("a cache that measures zero bytes but holds entries is still cleared", () => {
+ // An empty-directory tree costs inodes, the backend can empty it, and it is
+ // the one cache a user cannot easily clear by hand.
+ const { api } = loadApi(() => json({}));
+ const inventory = api.inventoryFromApi(
+ // biome-ignore lint/style/useNamingConvention: API schema
+ apiInventory([apiEntry("triton", { size_bytes: 0, entry_count: 40000 })]),
+ );
+ assert.deepEqual(api.bulkPurgeKeys(inventory), ["triton"]);
+});