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 the models drive in the Live Monitor when it is not the system disk (#12724)

Daniel Hanaec45587b0e8
diff --git a/studio/backend/main.py b/studio/backend/main.py
index 8f768da034b..792318834a2 100644
--- a/studio/backend/main.py
+++ b/studio/backend/main.py
@@ -2564,6 +2564,10 @@ def get_system_info(
logger.debug(f"Failed to get disk usage: {e}")
disk = None
+ from utils.system_disk import cached_models_disk_usage
+
+ models_disk = cached_models_disk_usage()
+
try:
current_process = psutil.Process(os.getpid())
process_used_mb = round(current_process.memory_info().rss / 1024**2)
@@ -2613,6 +2617,8 @@ def get_system_info(
"free_gb": round(disk.free / 1e9, 2) if disk else 0,
"percent_used": disk.percent if disk else 0,
},
+ # Additive: null unless the HF cache sits on another volume (e.g. a symlinked drive).
+ "models_disk": models_disk,
"gpu": gpu_info,
"inference_gpu": inference_gpu_info,
"ml_packages": ml_packages,
diff --git a/studio/backend/tests/test_models_disk_usage.py b/studio/backend/tests/test_models_disk_usage.py
new file mode 100644
index 00000000000..2f25d87ba61
--- /dev/null
+++ b/studio/backend/tests/test_models_disk_usage.py
@@ -0,0 +1,193 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""#9259: the Live Monitor reports the drive holding the HF cache when it is not the system disk."""
+
+import os
+import sys
+import threading
+import time
+from collections import namedtuple
+from pathlib import Path
+
+import pytest
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
+
+from utils import system_disk # noqa: E402
+
+GB = 10**9
+_Usage = namedtuple("_Usage", "total used free")
+
+
+def second_drive(tmp_path, monkeypatch):
+ """Everything under tmp_path/second is drive 2; the rest, `/` included, is drive 1.
+
+ Matched on the literal path, so only a caller that resolved the symlink lands on drive 2."""
+ second = (tmp_path / "second").resolve()
+ (second / "hf" / "hub").mkdir(parents = True)
+
+ def on_second(path):
+ return Path(path).is_relative_to(second)
+
+ def fake_usage(path):
+ if on_second(path):
+ return _Usage(2000 * GB, 500 * GB, 1500 * GB)
+ return _Usage(100 * GB, 60 * GB, 40 * GB)
+
+ def fake_device(path):
+ os.stat(path) # real errors: missing, permission denied
+ return 2 if on_second(path) else 1
+
+ monkeypatch.setattr(system_disk, "_device", fake_device)
+ monkeypatch.setattr(system_disk.shutil, "disk_usage", fake_usage)
+ return second
+
+
+def test_symlinked_cache_reports_the_drive_holding_the_bytes(second_drive, tmp_path):
+ link = tmp_path / "huggingface"
+ link.symlink_to(second_drive / "hf", target_is_directory = True)
+ assert system_disk.models_disk_usage(link / "hub") == {
+ "total_gb": 2000.0,
+ "free_gb": 1500.0,
+ "percent_used": 25.0,
+ }
+
+
+def test_cache_dir_missing_behind_a_symlink_still_finds_the_target_drive(second_drive, tmp_path):
+ link = tmp_path / "huggingface"
+ link.symlink_to(second_drive / "hf", target_is_directory = True)
+ assert system_disk.models_disk_usage(link / "not-created" / "hub")["total_gb"] == 2000.0
+
+
+def test_cache_on_the_system_disk_adds_nothing(second_drive, tmp_path):
+ assert system_disk.models_disk_usage(tmp_path / "hub") is None
+
+
+def test_cache_not_created_yet_uses_its_parent_volume(second_drive):
+ assert system_disk.models_disk_usage(second_drive / "new" / "hub")["total_gb"] == 2000.0
+
+
+def test_volume_sharing_the_system_pool_adds_nothing(second_drive, monkeypatch):
+ # APFS Data volume / btrfs subvolume: own st_dev, same pool as `/`.
+ pool = _Usage(2000 * GB, 1200 * GB, 800 * GB)
+ shared = _Usage(2000 * GB, 300 * GB, 800 * GB - 5 * 10**6)
+ monkeypatch.setattr(
+ system_disk.shutil,
+ "disk_usage",
+ lambda p: shared if Path(p).is_relative_to(second_drive) else pool,
+ )
+ assert system_disk.models_disk_usage(second_drive / "hf" / "hub") is None
+
+
+ not os.environ.get("GITHUB_ACTIONS") or sys.platform == "win32",
+ reason = "hosted Linux / macOS runners have one disk (Windows checks out on D:, home on C:)",
+)
+def test_hosted_runner_home_cache_is_the_system_disk():
+ # macos runners put home on the APFS Data volume (own st_dev, same container as `/`).
+ assert system_disk.models_disk_usage(Path.home() / ".cache" / "huggingface" / "hub") is None
+
+
+def test_unreadable_cache_is_omitted(monkeypatch):
+ def denied(path):
+ raise PermissionError(path)
+
+ monkeypatch.setattr(system_disk, "_device", denied)
+ assert system_disk.models_disk_usage(Path("/somewhere/hub")) is None
+
+
+def test_active_cache_on_root_volume_is_none_on_a_single_disk_host(tmp_path, monkeypatch):
+ monkeypatch.setattr(system_disk, "_hub_cache", lambda: Path(os.path.abspath(os.sep)) / "x")
+ assert system_disk.models_disk_usage() is None
+
+
+ sys.platform == "win32" or os.geteuid() == 0, reason = "needs POSIX permission bits"
+)
+def test_unreadable_cache_under_a_readable_volume_is_not_its_parent(second_drive):
+ # Python 3.14's Path.exists is False for EACCES too; climbing on it reported the parent volume.
+ locked = second_drive / "locked"
+ (locked / "hub").mkdir(parents = True)
+ locked.chmod(0)
+ try:
+ assert system_disk.models_disk_usage(locked / "hub") is None
+ finally:
+ locked.chmod(0o755)
+
+
+def fresh_cache(monkeypatch):
+ monkeypatch.setattr(system_disk, "_readings", {})
+ monkeypatch.setattr(system_disk, "_probes", {})
+ monkeypatch.setattr(system_disk, "_FIRST_WAIT_S", 0.2)
+
+
+def test_hung_cache_volume_never_blocks_the_poll(fresh_cache, monkeypatch):
+ release, calls = threading.Event(), []
+
+ def hung(cache = None):
+ calls.append(cache)
+ release.wait(10)
+ return {"total_gb": 1.0}
+
+ monkeypatch.setattr(system_disk, "_cache_key", lambda: "studio:/nfs")
+ monkeypatch.setattr(system_disk, "models_disk_usage", hung)
+ for _ in range(5):
+ start = time.monotonic()
+ assert system_disk.cached_models_disk_usage() is None
+ assert time.monotonic() - start < 1.0
+ assert len(calls) == 1, "one probe in flight, not one per poll"
+ release.set()
+ for _ in range(50):
+ if not system_disk._probes:
+ break
+ time.sleep(0.05)
+ assert system_disk.cached_models_disk_usage() == {"total_gb": 1.0}
+
+
+def test_cache_path_is_resolved_off_the_request_thread(fresh_cache, monkeypatch):
+ def blocking_resolve():
+ raise AssertionError("resolved on the request thread")
+
+ monkeypatch.setattr(system_disk, "_hub_cache", blocking_resolve)
+ monkeypatch.setattr(system_disk, "_cache_key", lambda: "studio:/nfs")
+ monkeypatch.setattr(system_disk, "models_disk_usage", lambda cache = None: {"ok": True})
+ assert system_disk.cached_models_disk_usage() == {"ok": True}
+
+
+def test_changed_models_folder_is_reprobed(fresh_cache, monkeypatch):
+ folder = {"key": "a"}
+ monkeypatch.setattr(system_disk, "_cache_key", lambda: folder["key"])
+ monkeypatch.setattr(system_disk, "models_disk_usage", lambda cache = None: {"key": folder["key"]})
+ assert system_disk.cached_models_disk_usage() == {"key": "a"}
+ folder["key"] = "b"
+ assert system_disk.cached_models_disk_usage() == {"key": "b"}
+
+
+def test_switching_away_from_a_hung_folder_probes_the_new_one(fresh_cache, monkeypatch):
+ release = threading.Event()
+ folder = {"key": "nfs"}
+
+ def probe(cache = None):
+ key = folder["key"]
+ if key == "nfs":
+ release.wait(10)
+ return {"key": key}
+
+ monkeypatch.setattr(system_disk, "_cache_key", lambda: folder["key"])
+ monkeypatch.setattr(system_disk, "models_disk_usage", probe)
+ assert system_disk.cached_models_disk_usage() is None
+ folder["key"] = "local"
+ assert system_disk.cached_models_disk_usage() == {"key": "local"}
+ # The slow probe landing late must not evict the active folder's reading.
+ release.set()
+ for _ in range(50):
+ if not system_disk._probes:
+ break
+ time.sleep(0.05)
+ monkeypatch.setattr(
+ system_disk, "models_disk_usage", lambda cache = None: pytest.fail("re-probed")
+ )
+ assert system_disk.cached_models_disk_usage() == {"key": "local"}
diff --git a/studio/backend/utils/system_disk.py b/studio/backend/utils/system_disk.py
new file mode 100644
index 00000000000..cd089b7ba95
--- /dev/null
+++ b/studio/backend/utils/system_disk.py
@@ -0,0 +1,111 @@
+# 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 volume holding downloaded models, when it is not the system disk (#9259)."""
+
+import os
+import shutil
+import threading
+import time
+from pathlib import Path
+from typing import Optional
+
+
+_SAME_POOL_SLACK = 1 << 30
+_TTL_S = 30.0
+_FIRST_WAIT_S = 0.5
+
+
+def _hub_cache() -> Optional[Path]:
+ try:
+ from utils.hf_cache_settings import get_hf_cache_paths
+ return get_hf_cache_paths().hub_cache
+ except Exception: # noqa: BLE001 - a settings read must not fail the system poll
+ return None
+
+
+def _device(path: Path) -> int:
+ return os.stat(path).st_dev
+
+
+def _locate(path: Path) -> tuple[Path, int]:
+ """(nearest existing ancestor, its device). Climbs only past MISSING paths: a fresh install
+ has no cache dir yet, but an unreadable one must not report its parent's volume."""
+ for candidate in (path, *path.parents):
+ try:
+ return candidate, _device(candidate)
+ except NotADirectoryError:
+ continue
+ except FileNotFoundError:
+ # Windows reports an untraversable parent as FileNotFoundError too.
+ from utils.hf_cache_settings import _absence_is_real
+ if not _absence_is_real(candidate):
+ raise
+ raise FileNotFoundError(path)
+
+
+def models_disk_usage(cache: Optional[Path] = None) -> Optional[dict]:
+ """The HF hub cache's volume, or None when it is the system disk or unreadable.
+
+ realpath first: a not-yet-created cache behind a symlink climbs the target's parents.
+ """
+ cache = _hub_cache() if cache is None else cache
+ if cache is None:
+ return None
+ try:
+ target, device = _locate(Path(os.path.realpath(cache)))
+ root = Path(os.path.abspath(os.sep))
+ if device == _device(root):
+ return None
+ usage = shutil.disk_usage(target)
+ system = shutil.disk_usage(root)
+ except (OSError, ValueError):
+ return None
+ # APFS Data volumes (macOS) and btrfs subvolumes (Fedora /home) have their own st_dev but share `/`'s pool.
+ if usage.total == system.total and abs(usage.free - system.free) < _SAME_POOL_SLACK:
+ return None
+ # psutil's percent formula, matching the system disk reading.
+ seen = usage.used + usage.free
+ return {
+ "total_gb": round(usage.total / 1e9, 2),
+ "free_gb": round(usage.free / 1e9, 2),
+ "percent_used": round(usage.used / seen * 100, 1) if seen else 0,
+ }
+
+
+_lock = threading.Lock()
+_readings: dict = {} # cache path -> (monotonic time, reading)
+_probes: dict = {} # cache path -> in-flight thread
+
+
+def _cache_key() -> str:
+ try:
+ from utils.hf_cache_settings import configured_cache_key
+ return configured_cache_key()
+ except Exception: # noqa: BLE001 - a settings read must not fail the system poll
+ return "default"
+
+
+def _probe(key: str) -> None:
+ # Resolving the configured path can block on the same dead mount, so it happens here.
+ reading = models_disk_usage()
+ with _lock:
+ _probes.pop(key, None)
+ _readings[key] = (time.monotonic(), reading)
+
+
+def cached_models_disk_usage() -> Optional[dict]:
+ """models_disk_usage for the 3 s /api/system poll: statvfs on a hung NFS/SMB cache blocks, so
+ the probe runs off the request thread, at most one per cache path, refreshed every _TTL_S.
+ """
+ key = _cache_key()
+ with _lock:
+ at, reading = _readings.get(key, (None, None))
+ if key in _probes or (at is not None and time.monotonic() - at < _TTL_S):
+ return reading
+ probe = threading.Thread(target = _probe, args = (key,), daemon = True)
+ _probes[key] = probe
+ probe.start()
+ probe.join(_FIRST_WAIT_S)
+ with _lock:
+ return _readings.get(key, (None, None))[1]
diff --git a/studio/frontend/src/features/settings/tabs/resources-tab.tsx b/studio/frontend/src/features/settings/tabs/resources-tab.tsx
index 0a303b260b4..85e11a39aa0 100644
--- a/studio/frontend/src/features/settings/tabs/resources-tab.tsx
+++ b/studio/frontend/src/features/settings/tabs/resources-tab.tsx
@@ -318,6 +318,14 @@ export function ResourcesTab() {
const diskFree = systemInfo.disk?.free_gb ?? 0;
const diskUsed = Math.max(0, diskTotal - diskFree);
const diskPercent = diskTotal > 0 ? (diskUsed / diskTotal) * 100 : 0;
+ const modelsDisk = systemInfo.models_disk ?? null;
+ const modelsDiskUsed = modelsDisk
+ ? Math.max(0, modelsDisk.total_gb - modelsDisk.free_gb)
+ : 0;
+ const modelsDiskPercent =
+ modelsDisk && modelsDisk.total_gb > 0
+ ? (modelsDiskUsed / modelsDisk.total_gb) * 100
+ : 0;
const display = gpuMemoryDisplay(displayedGpu);
const usageDevices = display.usageDevices;
const gpuMemoryTotals = gpuMemoryTotalsGb(usageDevices);
@@ -355,6 +363,9 @@ export function ResourcesTab() {
diskFree,
diskUsed,
diskPercent,
+ modelsDisk,
+ modelsDiskUsed,
+ modelsDiskPercent,
vramTotal,
vramDedicated: gpuMemoryTotals.dedicated,
vramShared: gpuMemoryTotals.shared,
@@ -571,6 +582,22 @@ export function ResourcesTab() {
}
percent={hostUnread ? null : metrics.diskPercent}
/>
+ {metrics.modelsDisk && (
+ <MetricTile
+ label={t("settings.resources.liveMonitor.modelsDisk")}
+ value={hostReading(
+ `${formatGb(metrics.modelsDiskUsed)} / ${formatGb(metrics.modelsDisk.total_gb)}`,
+ )}
+ detail={
+ hostUnread
+ ? hostUnreadDetail
+ : t("settings.resources.liveMonitor.free", {
+ value: formatGb(metrics.modelsDisk.free_gb),
+ })
+ }
+ percent={hostUnread ? null : metrics.modelsDiskPercent}
+ />
+ )}
<MetricTile
label={t(
memoryDisplay.sharedOnly
@@ -852,6 +879,18 @@ export function ResourcesTab() {
free: formatGb(metrics.diskFree),
})}
/>
+ {metrics.modelsDisk && (
+ <InfoRow
+ label={t("settings.resources.storage.modelsDisk")}
+ value={t("settings.resources.storage.diskUsage", {
+ used: formatGb(metrics.modelsDiskUsed),
+ total: formatGb(metrics.modelsDisk.total_gb),
+ })}
+ detail={t("settings.resources.storage.diskFree", {
+ free: formatGb(metrics.modelsDisk.free_gb),
+ })}
+ />
+ )}
<SettingsRow
label={t("settings.resources.storage.modelsFolder")}
description={t("settings.resources.storage.modelsFolderDescription")}
diff --git a/studio/frontend/src/hooks/use-system.ts b/studio/frontend/src/hooks/use-system.ts
index 98beb786922..12cf76e624a 100644
--- a/studio/frontend/src/hooks/use-system.ts
+++ b/studio/frontend/src/hooks/use-system.ts
@@ -90,6 +90,12 @@ export interface SystemInfoResponse {
free_gb: number;
percent_used: number;
};
+ /** The models (HF cache) volume; null or absent when it is the system disk. */
+ models_disk?: {
+ total_gb: number;
+ free_gb: number;
+ percent_used: number;
+ } | null;
gpu: SystemGpuInfo;
/** Devices available to GGUF inference; differs when llama.cpp uses Vulkan. */
inference_gpu?: SystemGpuInfo;
diff --git a/studio/frontend/src/i18n/locales/en.ts b/studio/frontend/src/i18n/locales/en.ts
index 10b8acb1dab..8f07c26bae7 100644
--- a/studio/frontend/src/i18n/locales/en.ts
+++ b/studio/frontend/src/i18n/locales/en.ts
@@ -1869,6 +1869,7 @@ export const en = {
cpu: "CPU",
ram: "RAM",
disk: "Disk",
+ modelsDisk: "Models disk",
vram: "VRAM",
cpuCores: "{logical} logical / {physical} physical cores",
currentLoad: "Current load",
@@ -1979,6 +1980,7 @@ export const en = {
storage: {
title: "Storage",
systemDisk: "System disk",
+ modelsDisk: "Models disk",
diskUsage: "{used} used / {total}",
diskFree: "{free} free",
modelsFolder: "Models folder",