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: faster, clearer model folder management (#14588)

Michael Han465e0c8d27f2
diff --git a/studio/backend/hub/schemas/inventory.py b/studio/backend/hub/schemas/inventory.py
index 000883287b5..a4679485c02 100644
--- a/studio/backend/hub/schemas/inventory.py
+++ b/studio/backend/hub/schemas/inventory.py
@@ -402,7 +402,7 @@ class ScanFolderInfo(BaseModel):
recursive: bool = Field(False, description = "Sub-folders are scanned too")
status: str = Field(
default = "ok",
- description = "Last scan result: ok, permission_denied, missing, or unreadable",
+ description = "Last scan result: ok, permission_denied, missing, unreadable, partial, or slow",
)
diff --git a/studio/backend/hub/services/models/local_inventory.py b/studio/backend/hub/services/models/local_inventory.py
index 91c3a599b01..7931e21f225 100644
--- a/studio/backend/hub/services/models/local_inventory.py
+++ b/studio/backend/hub/services/models/local_inventory.py
@@ -7,10 +7,13 @@ from __future__ import annotations
import asyncio
+import concurrent.futures
+import contextvars
import os
import re
import stat
import threading
+import time
from collections import OrderedDict
from pathlib import Path
from typing import List, NamedTuple, Optional
@@ -44,8 +47,10 @@ from utils.hidden_models import is_hidden_model
from utils.paths.path_utils import is_appledouble_metadata
from utils.paths.scan_folder_health import (
annotate_scan_folders,
+ clear_scan_slow,
note_scan_folder_scanned,
record_scan_failure,
+ record_scan_slow,
refresh_failed_scan_folders,
)
@@ -1107,6 +1112,104 @@ async def _scan_source(label: str, scanner, path: Path) -> List[LocalModelInfo]:
return []
+# A thread per scan under a budget: a fixed pool lets a few hung mounts starve every healthy folder.
+_CUSTOM_FOLDER_SCAN_TIMEOUT_S = 10.0
+_custom_folder_scans: dict[str, tuple[float, concurrent.futures.Future]] = {}
+_custom_folder_scans_lock = threading.Lock()
+
+
+def _run_into(future: concurrent.futures.Future, context: contextvars.Context, work) -> None:
+ if not future.set_running_or_notify_cancel():
+ return
+ try:
+ result = context.run(work)
+ except BaseException as e: # noqa: BLE001 -- handed to the waiter
+ future.set_exception(e)
+ else:
+ future.set_result(result)
+
+
+def _submit_custom_folder_scan(row_path: str, work) -> Optional[concurrent.futures.Future]:
+ """None when an earlier scan of this folder is still stuck past budget: a second thread would only stall on
+ the same mount. So stuck threads stay at one per folder."""
+ with _custom_folder_scans_lock:
+ started, running = _custom_folder_scans.get(row_path, (0.0, None))
+ if (
+ running is not None
+ and not running.done()
+ and time.monotonic() - started > _CUSTOM_FOLDER_SCAN_TIMEOUT_S
+ ):
+ return None
+ future: concurrent.futures.Future = concurrent.futures.Future()
+ threading.Thread(
+ target = _run_into,
+ args = (future, contextvars.copy_context(), work),
+ name = "scan-folder",
+ daemon = True,
+ ).start()
+ # Keep tracking the oldest scan still running: replacing it would restart the clock on a hung mount.
+ if running is None or running.done():
+ _custom_folder_scans[row_path] = (time.monotonic(), future)
+ return future
+
+
+def _abandon_custom_folder_scan(row_path: str, future: concurrent.futures.Future) -> None:
+ logger.warning(
+ "Scan folder %s took over %.0fs; skipped this listing",
+ short_path_for_log(row_path),
+ _CUSTOM_FOLDER_SCAN_TIMEOUT_S,
+ )
+ record_scan_slow(row_path)
+ future.add_done_callback(lambda _f: clear_scan_slow(row_path))
+
+
+async def _run_custom_folder_bounded(row_path: str, work):
+ """``work()`` for one custom folder, or None when it was skipped for being slow."""
+ future = _submit_custom_folder_scan(row_path, work)
+ if future is None:
+ return None
+ try:
+ return await asyncio.wait_for(asyncio.wrap_future(future), _CUSTOM_FOLDER_SCAN_TIMEOUT_S)
+ except asyncio.TimeoutError:
+ _abandon_custom_folder_scan(row_path, future)
+ return None
+
+
+def run_custom_folder_bounded_sync(row_path: str, work):
+ """``_run_custom_folder_bounded`` for a caller already off the event loop."""
+ future = _submit_custom_folder_scan(row_path, work)
+ if future is None:
+ return None
+ try:
+ return future.result(timeout = _CUSTOM_FOLDER_SCAN_TIMEOUT_S)
+ except concurrent.futures.TimeoutError:
+ _abandon_custom_folder_scan(row_path, future)
+ return None
+
+
+def _discover_custom_folder_hf_caches(folder_path: Path) -> list[tuple[Path, Optional[list]]]:
+ try:
+ cache_dirs = hf_cache_scan.scan_folder_hf_caches(folder_path)
+ except Exception as e:
+ logger.warning(
+ "Skipping HF caches under %s: %s", short_path_for_log(folder_path), scrub_paths(e)
+ )
+ return []
+ hf_caches = []
+ for cache_dir in cache_dirs:
+ try:
+ discovered = _discover_hf_cache(cache_dir, entry_limit = _MAX_CUSTOM_FOLDER_ENTRIES)
+ except Exception as e:
+ logger.warning(
+ "Skipping custom HF cache scan for %s: %s",
+ short_path_for_log(cache_dir),
+ scrub_paths(e),
+ )
+ discovered = []
+ hf_caches.append((cache_dir, discovered))
+ return hf_caches
+
+
async def _collect_models_from_default_sources(
models_root: Path,
hf_cache_dir: Path,
@@ -1160,21 +1263,18 @@ async def _collect_models_from_default_sources(
)
for folder in custom_folders:
folder_path = Path(normalize_path(folder["path"])).expanduser()
- hf_caches = []
- for cache_dir in await asyncio.to_thread(hf_cache_scan.scan_folder_hf_caches, folder_path):
- discovered = await _scan_source(
- "custom HF cache",
- lambda path: _discover_hf_cache(path, entry_limit = _MAX_CUSTOM_FOLDER_ENTRIES),
- cache_dir,
- )
- hf_caches.append((cache_dir, discovered))
+ # Carry the registered path: the status registry is keyed on the row, not on the normalized Path this scan walks.
+ row_path = str(folder["path"])
+ hf_caches = await _run_custom_folder_bounded(
+ row_path, lambda path = folder_path: _discover_custom_folder_hf_caches(path)
+ )
+ if hf_caches is None:
+ continue
+ for cache_dir, discovered in hf_caches:
state_repositories.extend(
("model", model_id, cache_dir) for _repo, model_id, _updated in discovered
)
- # Carry the registered path: the status registry is keyed on the row, not on the normalized Path this scan walks.
- custom_sources.append(
- (folder_path, hf_caches, str(folder["path"]), bool(folder.get("recursive")))
- )
+ custom_sources.append((folder_path, hf_caches, row_path, bool(folder.get("recursive"))))
try:
variant_states = await asyncio.to_thread(
download_manifest.build_variant_state_index,
@@ -1221,32 +1321,40 @@ async def _collect_models_from_default_sources(
local_models += await _scan_source("Hermes", scan_hermes_dir, hermes_dir)
hermes_identities = {_inventory_physical_identity(str(d)) for d in hermes_dirs}
+
+ def scan_folder(folder_path: Path, hf_caches, recursive: bool) -> List[LocalModelInfo]:
+ nested_roots = tuple(nested_scan_roots(folder_path)) if recursive else ()
+ custom_models = _scan_custom_folder(
+ folder_path,
+ hf_caches = hf_caches,
+ variant_states = variant_states,
+ active_hub_cache = hf_cache_dir,
+ nested_roots = nested_roots,
+ )
+ if _inventory_physical_identity(str(folder_path)) in hermes_identities:
+ # Registering ~/.hermes/models was how Hermes downloads were listed before this scan;
+ # the walk lists every download a second time under the same id. Anything else kept
+ # in that folder is still the user's custom row.
+ staged = {
+ _inventory_physical_identity(row.path) for row in scan_hermes_dir(folder_path)
+ }
+ custom_models = [
+ model
+ for model in custom_models
+ if _inventory_physical_identity(model.path) not in staged
+ ]
+ return custom_models
+
for folder_path, hf_caches, row_path, recursive in custom_sources:
try:
- nested_roots = (
- tuple(await asyncio.to_thread(nested_scan_roots, folder_path)) if recursive else ()
- )
- custom_models = await asyncio.to_thread(
- _scan_custom_folder,
- folder_path,
- hf_caches = hf_caches,
- variant_states = variant_states,
- active_hub_cache = hf_cache_dir,
- nested_roots = nested_roots,
+ custom_models = await _run_custom_folder_bounded(
+ row_path,
+ lambda path = folder_path, caches = hf_caches, rec = recursive: scan_folder(
+ path, caches, rec
+ ),
)
- if _inventory_physical_identity(str(folder_path)) in hermes_identities:
- # Registering ~/.hermes/models was how Hermes downloads were listed before this scan;
- # the walk lists every download a second time under the same id. Anything else kept
- # in that folder is still the user's custom row.
- staged = {
- _inventory_physical_identity(row.path)
- for row in await asyncio.to_thread(scan_hermes_dir, folder_path)
- }
- custom_models = [
- model
- for model in custom_models
- if _inventory_physical_identity(model.path) not in staged
- ]
+ if custom_models is None:
+ continue
except Exception as e:
logger.warning(
"Skipping unreadable scan folder %s: %s",
@@ -1418,9 +1526,17 @@ def _promote_to_custom_source(model: LocalModelInfo) -> LocalModelInfo:
)
+def _list_custom_folders_with_identity() -> list[dict]:
+ # The identity is a realpath, so it is taken here, off the loop: on a hung network mount it would stall every request.
+ return [
+ {**folder, "_identity": _inventory_path_identity(str(folder.get("path", "")))}
+ for folder in list_scan_folders()
+ ]
+
+
async def _load_custom_folders() -> list[dict]:
try:
- return await asyncio.to_thread(list_scan_folders)
+ return await asyncio.to_thread(_list_custom_folders_with_identity)
except Exception as e:
logger.warning("Could not load custom scan folders: %s", scrub_paths(e))
return []
@@ -1674,7 +1790,7 @@ async def list_local_models_response(models_dir: str = "./models") -> LocalModel
_inventory_path_identity(models_dir),
sources,
tuple(
- _inventory_path_identity(str(folder.get("path", "")))
+ (folder.get("_identity") or _inventory_path_identity(str(folder.get("path", ""))))
+ ("\x00r" if folder.get("recursive") else "")
for folder in custom_folders
),
diff --git a/studio/backend/hub/storage/scan_folders.py b/studio/backend/hub/storage/scan_folders.py
index 667f1d5ee0d..21bfd68dfdb 100644
--- a/studio/backend/hub/storage/scan_folders.py
+++ b/studio/backend/hub/storage/scan_folders.py
@@ -179,6 +179,23 @@ def add_scan_folder_with_status(path: str, recursive: bool | None = None) -> tup
"SELECT id, path, created_at, recursive FROM scan_folders WHERE path = ?",
(normalized,),
).fetchone()
+ if (
+ existing is None
+ and platform.system() == "Darwin"
+ and macos_volume_ignores_case(normalized)
+ ):
+ # realpath keeps the typed case, so ~/Models and ~/models would be two rows scanning one folder.
+ folded = normalized.casefold()
+ existing = next(
+ (
+ row
+ for row in conn.execute(
+ "SELECT id, path, created_at, recursive FROM scan_folders"
+ )
+ if str(row["path"]).casefold() == folded
+ ),
+ None,
+ )
if existing is not None:
# None keeps the stored flag, so a re-add from export registration never resets it.
if recursive is None or bool(existing["recursive"]) == recursive:
@@ -188,7 +205,7 @@ def add_scan_folder_with_status(path: str, recursive: bool | None = None) -> tup
(int(recursive), existing["id"]),
)
conn.commit()
- return {**dict(existing), "recursive": int(recursive)}, True
+ return {**dict(existing), "recursive": recursive}, True
inserted = False
try:
conn.execute(
diff --git a/studio/backend/routes/models.py b/studio/backend/routes/models.py
index 8ce45d38d8c..bc0f5d45916 100644
--- a/studio/backend/routes/models.py
+++ b/studio/backend/routes/models.py
@@ -965,6 +965,7 @@ def collect_local_models(
thing the two do not share; see :func:`_scan_ollama_dir`.
"""
from storage.studio_db import list_scan_folders
+ from hub.services.models.local_inventory import run_custom_folder_bounded_sync
from hub.utils import gguf as gguf_utils
from hub.utils import inventory_scan as hf_cache_scan
from utils.models.model_config import detect_gguf_model
@@ -1005,11 +1006,14 @@ def collect_local_models(
state_repositories = []
state_cache_dirs = [cache_dir for cache_dir, _active_cache in hf_sources]
- state_cache_dirs.extend(
- cache_dir
- for folder in custom_folders
- for cache_dir in hf_cache_scan.scan_folder_hf_caches(Path(folder["path"]))
- )
+ for folder in custom_folders:
+ state_cache_dirs.extend(
+ run_custom_folder_bounded_sync(
+ str(folder["path"]),
+ lambda path = Path(folder["path"]): hf_cache_scan.scan_folder_hf_caches(path),
+ )
+ or ()
+ )
for cache_dir in dict.fromkeys(state_cache_dirs):
try:
for repo_dir in cache_dir.glob("models--*"):
@@ -1062,81 +1066,92 @@ def collect_local_models(
from hub.services.models.local_inventory import _local_model_path_is_symlink
custom_identities: set[str] = set()
- for folder in custom_folders:
- folder_path = Path(folder["path"])
- try:
- # Filter Ollama .studio_links/ from generic scanners: duplicates and internal paths.
- _generic = [
- m
- for m in (
- _scan_models_dir(folder_path, limit = _MAX_MODELS_PER_FOLDER)
- + [
- row
- for cache_dir in hf_cache_scan.scan_folder_hf_caches(folder_path)
- for row in _scan_hf_cache(
- cache_dir,
- active_cache = False,
- variant_states = variant_states,
- )
- ]
- + _scan_lmstudio_dir(folder_path)
- )
- if not any(p in (".studio_links", "ollama_links") for p in Path(m.path).parts)
- ]
- if folder.get("recursive"):
- _generic += _scan_nested_compat_rows(
- folder_path, _generic, limit = _MAX_MODELS_PER_FOLDER
- )
- _generic = _with_comfy_compat_rows(folder_path, _generic, limit = _MAX_MODELS_PER_FOLDER)
- custom_models = []
- for model in _generic:
- path = Path(model.path)
- is_gguf_row = model.model_format == "gguf" or _is_gguf_companion_only_dir(path)
- if not is_gguf_row or model.partial:
- custom_models.append(model)
- continue
- if path.is_dir():
- patterns = ("*", "*/*") if model.source == "hf_cache" else ("*",)
- if any(
- detect_gguf_model(str(file), model_root = str(folder_path)) is not None
- for pattern in patterns
- for file in path.glob(pattern)
- if not _safe_is_dir(file) and file.suffix.lower() == ".gguf"
- ):
- custom_models.append(model)
- elif (
- detect_gguf_model(
- model.path,
- model_root = str(folder_path),
+
+ def _scan_custom_folder(folder_path: Path, recursive: bool) -> list:
+ # Filter Ollama .studio_links/ from generic scanners: duplicates and internal paths.
+ _generic = [
+ m
+ for m in (
+ _scan_models_dir(folder_path, limit = _MAX_MODELS_PER_FOLDER)
+ + [
+ row
+ for cache_dir in hf_cache_scan.scan_folder_hf_caches(folder_path)
+ for row in _scan_hf_cache(
+ cache_dir,
+ active_cache = False,
+ variant_states = variant_states,
)
- is not None
+ ]
+ + _scan_lmstudio_dir(folder_path)
+ )
+ if not any(p in (".studio_links", "ollama_links") for p in Path(m.path).parts)
+ ]
+ if recursive:
+ _generic += _scan_nested_compat_rows(
+ folder_path, _generic, limit = _MAX_MODELS_PER_FOLDER
+ )
+ _generic = _with_comfy_compat_rows(folder_path, _generic, limit = _MAX_MODELS_PER_FOLDER)
+ custom_models = []
+ for model in _generic:
+ path = Path(model.path)
+ is_gguf_row = model.model_format == "gguf" or _is_gguf_companion_only_dir(path)
+ if not is_gguf_row or model.partial:
+ custom_models.append(model)
+ continue
+ if path.is_dir():
+ patterns = ("*", "*/*") if model.source == "hf_cache" else ("*",)
+ if any(
+ detect_gguf_model(str(file), model_root = str(folder_path)) is not None
+ for pattern in patterns
+ for file in path.glob(pattern)
+ if not _safe_is_dir(file) and file.suffix.lower() == ".gguf"
):
custom_models.append(model)
- custom_models = gguf_utils.dedupe_custom_gguf_rows(custom_models)
- if _compat_inventory_path_identity(str(folder_path)) in hermes_identities:
- # Registering ~/.hermes/models was how Hermes downloads were listed before this
- # scan; the walk lists every download a second time under the same id. Anything
- # else kept in that folder is still the user's custom row.
- staged = {
- _compat_inventory_path_identity(m.path) for m in _scan_hermes_dir(folder_path)
- }
- custom_models = [
- m
- for m in custom_models
- if _compat_inventory_path_identity(m.path) not in staged
- ]
- if len(custom_models) < _MAX_MODELS_PER_FOLDER:
- custom_models += _scan_ollama_dir(
- folder_path,
- limit = _MAX_MODELS_PER_FOLDER - len(custom_models),
- materialize_links = materialize_ollama_links,
+ elif (
+ detect_gguf_model(
+ model.path,
+ model_root = str(folder_path),
)
+ is not None
+ ):
+ custom_models.append(model)
+ custom_models = gguf_utils.dedupe_custom_gguf_rows(custom_models)
+ if _compat_inventory_path_identity(str(folder_path)) in hermes_identities:
+ # Registering ~/.hermes/models was how Hermes downloads were listed before this
+ # scan; the walk lists every download a second time under the same id. Anything
+ # else kept in that folder is still the user's custom row.
+ staged = {
+ _compat_inventory_path_identity(m.path) for m in _scan_hermes_dir(folder_path)
+ }
+ custom_models = [
+ m for m in custom_models if _compat_inventory_path_identity(m.path) not in staged
+ ]
+ if len(custom_models) < _MAX_MODELS_PER_FOLDER:
+ custom_models += _scan_ollama_dir(
+ folder_path,
+ limit = _MAX_MODELS_PER_FOLDER - len(custom_models),
+ materialize_links = materialize_ollama_links,
+ )
+ return custom_models
+
+ for folder in custom_folders:
+ folder_path = Path(folder["path"])
+ row_path = str(folder.get("path", folder_path))
+ try:
+ custom_models = run_custom_folder_bounded_sync(
+ row_path,
+ lambda path = folder_path, recursive = bool(folder.get("recursive")): (
+ _scan_custom_folder(path, recursive)
+ ),
+ )
except OSError as e:
logger.warning("Skipping unreadable scan folder %s: %s", folder_path, e)
# Keep the reason so the folder list can show it instead of nothing.
- record_scan_failure(str(folder.get("path", folder_path)), e)
+ record_scan_failure(row_path, e)
+ continue
+ if custom_models is None:
continue
- note_scan_folder_scanned(str(folder.get("path", folder_path)), found = bool(custom_models))
+ note_scan_folder_scanned(row_path, found = bool(custom_models))
# Links below the scan root are distinct aliases (as in the Hub inventory), not twins.
for m in custom_models:
try:
@@ -1341,8 +1356,8 @@ async def list_local_models(
Redacted as ``/api/hub/local`` is: this router mirrors it over the same scan roots, so
leaving it alone recovers the layout that route hides.
"""
- # Resolve all scan directories up front.
- sources = _compat_local_inventory_sources()
+ # Off the loop: the probes stat every source root.
+ sources = await asyncio.to_thread(_compat_local_inventory_sources)
hf_cache_dir = sources.hf_cache_dir
legacy_hf = sources.legacy_hf
hf_default = sources.hf_default
@@ -1406,7 +1421,7 @@ async def get_scan_folders(
"""List all registered custom model scan folders. Redacted like ``/api/hub/scan-folders``."""
from storage.studio_db import list_scan_folders
- folders = list_scan_folders()
+ folders = await asyncio.to_thread(list_scan_folders)
# Opening the dialog is how a fixed folder clears, so recheck the bad ones.
await asyncio.to_thread(refresh_failed_scan_folders, folders)
return redact_inventory_host_paths(
diff --git a/studio/backend/tests/test_scan_folder_scan_budget.py b/studio/backend/tests/test_scan_folder_scan_budget.py
new file mode 100644
index 00000000000..0d9767ebf5b
--- /dev/null
+++ b/studio/backend/tests/test_scan_folder_scan_budget.py
@@ -0,0 +1,152 @@
+# 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 custom folder behind a hung mount must not hold the model list hostage."""
+
+import asyncio
+import threading
+
+import pytest
+
+from hub.services.models import local_inventory
+from utils.paths import scan_folder_health as health
+from utils.paths.scan_folder_health import (
+ STATUS_OK,
+ STATUS_PERMISSION_DENIED,
+ STATUS_SLOW,
+ annotate_scan_folders,
+ refresh_failed_scan_folders,
+)
+
+
[email protected](autouse = True)
+def _fast_budget(monkeypatch):
+ monkeypatch.setattr(local_inventory, "_CUSTOM_FOLDER_SCAN_TIMEOUT_S", 0.2)
+ local_inventory._custom_folder_scans.clear()
+ health._failed.clear()
+ yield
+ health._failed.clear()
+ local_inventory._custom_folder_scans.clear()
+
+
+def _status(path: str) -> str:
+ return annotate_scan_folders([{"path": path}])[0]["status"]
+
+
+def test_a_stuck_folder_is_skipped_marked_slow_and_recovers():
+ release = threading.Event()
+ calls = []
+
+ def stuck():
+ calls.append(1)
+ release.wait(5)
+ return ["row"]
+
+ assert asyncio.run(local_inventory._run_custom_folder_bounded("/mnt/nas", stuck)) is None
+ assert _status("/mnt/nas") == STATUS_SLOW
+ # Still stuck: the next listing skips it at once instead of parking a second thread on the mount.
+ assert local_inventory.run_custom_folder_bounded_sync("/mnt/nas", stuck) is None
+ assert len(calls) == 1
+ release.set()
+ local_inventory._custom_folder_scans["/mnt/nas"][1].result(5)
+ assert _status("/mnt/nas") == STATUS_OK
+ assert local_inventory.run_custom_folder_bounded_sync("/mnt/nas", lambda: ["row"]) == ["row"]
+
+
+def test_overlapping_listings_cannot_grow_threads_on_a_hung_folder():
+ release = threading.Event()
+ started = []
+
+ def stuck():
+ started.append(1)
+ release.wait(5)
+
+ async def overlapping():
+ tasks = []
+ for _ in range(8):
+ tasks.append(
+ asyncio.create_task(local_inventory._run_custom_folder_bounded("/mnt/nas", stuck))
+ )
+ await asyncio.sleep(0.08)
+ return await asyncio.gather(*tasks)
+
+ try:
+ assert asyncio.run(overlapping()) == [None] * 8
+ # Only requests inside the first budget window start a thread; later ones see it stuck.
+ assert len(started) <= 4
+ finally:
+ release.set()
+
+
+def test_stuck_folders_cannot_starve_a_healthy_one():
+ release = threading.Event()
+ try:
+ for index in range(6):
+ assert (
+ local_inventory.run_custom_folder_bounded_sync(
+ f"/mnt/stuck{index}", lambda: release.wait(5)
+ )
+ is None
+ )
+ assert local_inventory.run_custom_folder_bounded_sync("/models", lambda: ["m"]) == ["m"]
+ finally:
+ release.set()
+
+
+def test_healthy_folders_scan_concurrently_and_raise_as_before():
+ async def both():
+ return await asyncio.gather(
+ local_inventory._run_custom_folder_bounded("/a", lambda: ["a"]),
+ local_inventory._run_custom_folder_bounded("/a", lambda: ["a2"]),
+ )
+
+ assert asyncio.run(both()) == [["a"], ["a2"]]
+
+ def denied():
+ raise PermissionError(13, "denied")
+
+ with pytest.raises(PermissionError):
+ local_inventory.run_custom_folder_bounded_sync("/b", denied)
+
+
+def test_a_finished_slow_scan_keeps_a_failure_it_recorded(monkeypatch):
+ health._record("/c", STATUS_SLOW, "/c")
+ health._record("/c", STATUS_PERMISSION_DENIED, "/c")
+ health.clear_scan_slow("/c")
+ assert _status("/c") == STATUS_PERMISSION_DENIED
+
+
+def test_the_folder_list_does_not_reprobe_a_slow_folder(monkeypatch):
+ health._record("/mnt/nas", STATUS_SLOW, "/mnt/nas")
+
+ def hang(*_args, **_kwargs):
+ raise AssertionError("probing a hung mount would hang GET /scan-folders")
+
+ monkeypatch.setattr(health, "probe_folder", hang)
+ refresh_failed_scan_folders([{"path": "/mnt/nas"}])
+ assert _status("/mnt/nas") == STATUS_SLOW
+
+
+def test_macos_case_variants_are_one_folder(tmp_path, monkeypatch):
+ from hub.storage import scan_folders
+ from storage import studio_db
+
+ monkeypatch.setattr(scan_folders, "_denied_path_prefixes", lambda: [])
+ monkeypatch.setattr(scan_folders.platform, "system", lambda: "Darwin")
+ monkeypatch.setattr(scan_folders, "macos_volume_ignores_case", lambda _path: True)
+ folder = tmp_path / "Models"
+ folder.mkdir()
+ real = str(folder.resolve())
+ conn = studio_db.get_connection()
+ try:
+ conn.execute(
+ "INSERT INTO scan_folders (path, created_at, recursive) VALUES (?, ?, ?)",
+ (real.upper(), "2026-01-01", 1),
+ )
+ conn.commit()
+ finally:
+ conn.close()
+ row, inserted = scan_folders.add_scan_folder_with_status(real)
+ assert not inserted
+ assert row["path"] == real.upper() and row["recursive"]
+ assert len(scan_folders.list_scan_folders()) == 1
diff --git a/studio/backend/utils/paths/scan_folder_health.py b/studio/backend/utils/paths/scan_folder_health.py
index 4955543fe99..5d492ce66bb 100644
--- a/studio/backend/utils/paths/scan_folder_health.py
+++ b/studio/backend/utils/paths/scan_folder_health.py
@@ -19,6 +19,8 @@ STATUS_MISSING = "missing"
STATUS_UNREADABLE = "unreadable"
# The folder works, but something inside it is refused.
STATUS_PARTIAL = "partial"
+# The last scan outran its time budget: a hung network mount or a very large tree.
+STATUS_SLOW = "slow"
# Internal only: the probe ran out of budget before it saw everything
STATUS_UNKNOWN = "unknown"
@@ -127,6 +129,18 @@ def record_scan_failure(path: str, error: OSError) -> None:
_record(path, classify_scan_error(error), path)
+def record_scan_slow(path: str) -> None:
+ """Remember that a scan of ``path`` was abandoned for taking too long."""
+ _record(path, STATUS_SLOW, path)
+
+
+def clear_scan_slow(path: str) -> None:
+ """Forget a slow mark once the abandoned scan finishes; a failure it recorded itself stays."""
+ entry = _failed.get(path)
+ if entry is not None and entry[0] == STATUS_SLOW:
+ _failed.pop(path, None)
+
+
def clear_scan_failure(path: str) -> None:
"""Forget a past failure once the folder reads again."""
if _failed:
@@ -173,7 +187,8 @@ def refresh_failed_scan_folders(folders: list[dict]) -> None:
for folder in folders:
path = str(folder.get("path", ""))
entry = _failed.get(path)
- if entry is None:
+ # A slow folder is not probed here: the open could hang this request too. Its abandoned scan clears it on finishing.
+ if entry is None or entry[0] == STATUS_SLOW:
continue
previous = entry[0]
status, cause = probe_folder(path, children = True)
diff --git a/studio/frontend/scripts/check-bundle-budget.ts b/studio/frontend/scripts/check-bundle-budget.ts
index 472abdc3ba7..cedcad4f39d 100644
--- a/studio/frontend/scripts/check-bundle-budget.ts
+++ b/studio/frontend/scripts/check-bundle-budget.ts
@@ -359,8 +359,11 @@ export const BUDGET = {
// Projects recency and the polling cuts behind projects and sources (#14586) live in the eager chat chunk:
// +505 B raw / +309 B transfer (6,879,331 -> 6,879,836 B raw, 2,071,848 -> 2,072,157 B transfer against
// 2749eeedaa, one machine and build, Node 26, 97 chunks). Raised by that, on top of the fork affordances above.
- transferBytes: 2_072_682,
- rawBytes: 6_881_554,
+ // The shared custom folder store and its Undo / already-added toasts in the eager model picker: +557 B raw /
+ // +627 B transfer against 2749eeedaa (6_879_345 -> 6_879_902 raw, 2_071_823 -> 2_072_450 transfer, 97
+ // chunks); the folders dialog itself stays lazy. Raised by that, on top of the above.
+ transferBytes: 2_073_309,
+ rawBytes: 6_882_111,
};
// The chunk count is reported but not budgeted. Splitting a page out of the entry raises it while lowering the
diff --git a/studio/frontend/src/features/chat/api/chat-api.ts b/studio/frontend/src/features/chat/api/chat-api.ts
index 04defb1ca98..ff1eca2f9db 100644
--- a/studio/frontend/src/features/chat/api/chat-api.ts
+++ b/studio/frontend/src/features/chat/api/chat-api.ts
@@ -906,41 +906,6 @@ export async function deleteFineTunedModel(args: {
await parseJsonOrThrow<unknown>(response);
}
-export interface ScanFolderInfo {
- id: number;
- path: string;
- created_at: string;
- /** Sub-folders are scanned too. Absent on older backends. */
- recursive?: boolean;
- /** Result of the last scan. Absent on older backends, which means "ok". */
- status?: "ok" | "permission_denied" | "missing" | "unreadable" | "partial";
-}
-
-export async function listScanFolders(): Promise<ScanFolderInfo[]> {
- const response = await authFetch("/api/models/scan-folders");
- const data = await parseJsonOrThrow<{ folders: ScanFolderInfo[] }>(response);
- return data.folders;
-}
-
-export async function addScanFolder(
- path: string,
- recursive?: boolean,
-): Promise<ScanFolderInfo> {
- const response = await authFetch("/api/models/scan-folders", {
- method: "POST",
- headers: { "Content-Type": "application/json" },
- body: JSON.stringify({ path, recursive }),
- });
- return parseJsonOrThrow<ScanFolderInfo>(response);
-}
-
-export async function removeScanFolder(id: number): Promise<void> {
- const response = await authFetch(`/api/models/scan-folders/${id}`, {
- method: "DELETE",
- });
- await parseJsonOrThrow<unknown>(response);
-}
-
export async function listChatThreads(
args: {
modelType?: ModelType;
diff --git a/studio/frontend/src/features/chat/index.ts b/studio/frontend/src/features/chat/index.ts
index 532b27834d0..797a8b79a94 100644
--- a/studio/frontend/src/features/chat/index.ts
+++ b/studio/frontend/src/features/chat/index.ts
@@ -4,7 +4,6 @@
export { ChatPage, validateChatSearch, type ChatSearch } from "./chat-page";
export { isRenderableRenderHtmlToolPart } from "./artifacts/html-fences";
export {
- addScanFolder,
browseFolders,
ChatThreadDeletedError,
deleteChatAttachment,
@@ -21,12 +20,10 @@ export {
listLoras,
listModels,
listRecommendedFolders,
- listScanFolders,
loadModel,
unloadModel,
notifyChatHistoryUpdated,
notifyChatProjectsUpdated,
- removeScanFolder,
subscribeChatHistoryUpdated,
revealCachedModel,
revealFineTunedModel,
@@ -38,7 +35,6 @@ export {
type ChatAttachmentRecord,
type KvCacheEstimate,
type LocalModelInfo,
- type ScanFolderInfo,
CHAT_HISTORY_UPDATED_EVENT,
fetchSidebarThreadRows,
} from "./api/chat-api";
diff --git a/studio/frontend/src/features/hub/catalog/download-location-picker.tsx b/studio/frontend/src/features/hub/catalog/download-location-picker.tsx
index 8091e27e26c..3a018153af8 100644
--- a/studio/frontend/src/features/hub/catalog/download-location-picker.tsx
+++ b/studio/frontend/src/features/hub/catalog/download-location-picker.tsx
@@ -20,7 +20,7 @@ import { Folder02Icon } from "@hugeicons/core-free-icons";
import { HugeiconsIcon } from "@hugeicons/react";
import { useState } from "react";
import { setDownloadDir, useDownloadDir } from "../download-manager";
-import { type ScanFolderInfo, listScanFolders } from "../inventory/api";
+import { useScanFolders } from "../inventory/scan-folders-store";
const MODELS_FOLDER = "";
const PATH_SEPARATORS = /[\\/]+/;
@@ -33,7 +33,8 @@ function folderName(path: string): string {
export function DownloadLocationPicker() {
const isOwner = useIsAccountOwner();
const dir = useDownloadDir();
- const [folders, setFolders] = useState<ScanFolderInfo[]>([]);
+ const [menuOpen, setMenuOpen] = useState(false);
+ const { folders } = useScanFolders(menuOpen && isOwner);
const [browserOpen, setBrowserOpen] = useState(false);
if (!isOwner) {
@@ -65,15 +66,7 @@ export function DownloadLocationPicker() {
return (
<>
- <DropdownMenu
- onOpenChange={(open) => {
- if (open) {
- listScanFolders()
- .then(setFolders)
- .catch(() => undefined);
- }
- }}
- >
+ <DropdownMenu open={menuOpen} onOpenChange={setMenuOpen}>
<DropdownMenuTrigger asChild={true}>
<button
type="button"
diff --git a/studio/frontend/src/features/hub/catalog/models-toolbar.tsx b/studio/frontend/src/features/hub/catalog/models-toolbar.tsx
index fa6221e40e1..1868b13bd98 100644
--- a/studio/frontend/src/features/hub/catalog/models-toolbar.tsx
+++ b/studio/frontend/src/features/hub/catalog/models-toolbar.tsx
@@ -463,7 +463,7 @@ export const ModelsToolbar = memo(function ModelsToolbar({
<button
type="button"
onClick={onManageLocalFolders}
- aria-label="Add folder"
+ aria-label="Model folders"
className={cn(
triggerBase,
"field-filter relative inline-flex size-9 shrink-0 items-center justify-center rounded-full p-0",
@@ -477,7 +477,7 @@ export const ModelsToolbar = memo(function ModelsToolbar({
</button>
</TooltipTrigger>
<TooltipContent side="bottom" sideOffset={6}>
- Add folder
+ Model folders
</TooltipContent>
</Tooltip>
)}
diff --git a/studio/frontend/src/features/hub/catalog/on-device-folders-dialog.tsx b/studio/frontend/src/features/hub/catalog/on-device-folders-dialog.tsx
index 5cc9e82c335..8b452810751 100644
--- a/studio/frontend/src/features/hub/catalog/on-device-folders-dialog.tsx
+++ b/studio/frontend/src/features/hub/catalog/on-device-folders-dialog.tsx
@@ -2,7 +2,6 @@
// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
import { Button } from "@/components/ui/button";
-import { Checkbox } from "@/components/ui/checkbox";
import {
Dialog,
DialogContent,
@@ -12,6 +11,7 @@ import {
} from "@/components/ui/dialog";
import { Input } from "@/components/ui/input";
import { Spinner } from "@/components/ui/spinner";
+import { Switch } from "@/components/ui/switch";
import {
Tooltip,
TooltipContent,
@@ -20,11 +20,16 @@ import {
import { useIsAccountOwner } from "@/features/auth";
import {
type ScanFolderInfo,
- addScanFolder,
+ addScanFolderToStore,
+ countModelsPerFolder,
+ folderDisplayName,
formatBytes,
- listScanFolders,
- removeScanFolder,
+ refreshScanFolders,
+ removeScanFolderFromStore,
scanFolderStatusCopy,
+ setScanFolderRecursive,
+ useDeviceInventorySources,
+ useScanFolders,
} from "@/features/hub";
import { FolderBrowser } from "@/features/model-picker";
import {
@@ -43,21 +48,19 @@ import { cn } from "@/lib/utils";
import {
Delete02Icon,
Download01Icon,
- FileSearchIcon,
FolderAddIcon,
FolderExportIcon,
FolderOpenIcon,
FolderSearchIcon,
+ InformationCircleIcon,
PlusSignIcon,
Refresh01Icon,
} from "@hugeicons/core-free-icons";
import { HugeiconsIcon } from "@hugeicons/react";
-import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { useCallback, useEffect, useMemo, useState } from "react";
+import { setDownloadDir, useDownloadDir } from "../download-manager";
-function pathTail(path: string): string {
- const parts = path.split(/[\\/]/).filter(Boolean);
- return parts.at(-1) ?? path;
-}
+type Pending = "add" | `remove:${number}` | `recursive:${number}` | null;
function formatError(error: unknown): string {
return error instanceof Error ? error.message : String(error);
@@ -68,6 +71,11 @@ function formatFreeSpace(bytes: number | null): string | null {
return `${formatBytes(bytes)} free`;
}
+function modelCountLabel(count: number): string {
+ if (count === 0) return "No models found";
+ return count === 1 ? "1 model" : `${count} models`;
+}
+
export function OnDeviceFoldersDialog({
open,
onOpenChange,
@@ -75,73 +83,63 @@ export function OnDeviceFoldersDialog({
}: {
open: boolean;
onOpenChange: (open: boolean) => void;
+ /** For lists outside the shared inventory (the Images LoRA list); the inventory itself refreshes on its own. */
onInventoryChange?: () => void;
}) {
- const [folders, setFolders] = useState<ScanFolderInfo[]>([]);
+ const isOwner = useIsAccountOwner();
+ const { folders, loaded, loading, error: listError } = useScanFolders(open);
+ const { localModels } = useDeviceInventorySources(["localModels"], {
+ enabled: open,
+ });
const [path, setPath] = useState("");
- const [recursive, setRecursive] = useState(false);
+ const [inputError, setInputError] = useState<string | null>(null);
const [browserOpen, setBrowserOpen] = useState(false);
- const [loading, setLoading] = useState(false);
- const [error, setError] = useState<string | null>(null);
- const [pending, setPending] = useState<"add" | `remove:${number}` | null>(
- null,
- );
- const refreshIdRef = useRef(0);
- const mutationVersionRef = useRef(0);
+ const [pending, setPending] = useState<Pending>(null);
const [downloadCache, setDownloadCache] =
useState<HuggingFaceCacheSettings | null>(null);
const [downloadCacheLoaded, setDownloadCacheLoaded] = useState(false);
const [downloadBrowserOpen, setDownloadBrowserOpen] = useState(false);
const [downloadSaving, setDownloadSaving] = useState(false);
+ const browserDownloadDir = useDownloadDir();
const sortedFolders = useMemo(
- () => [...folders].sort((a, b) => a.path.localeCompare(b.path)),
+ () =>
+ [...folders].sort(
+ (a, b) =>
+ folderDisplayName(a.path).localeCompare(folderDisplayName(b.path)) ||
+ a.path.localeCompare(b.path),
+ ),
[folders],
);
- const refreshFolders = useCallback(() => {
- const refreshId = refreshIdRef.current + 1;
- const mutationVersion = mutationVersionRef.current;
- refreshIdRef.current = refreshId;
- setLoading(true);
- setError(null);
- listScanFolders()
- .then((nextFolders) => {
- if (refreshIdRef.current !== refreshId) {
- return;
- }
- if (mutationVersionRef.current !== mutationVersion) {
- return;
- }
- setFolders(nextFolders);
- })
- .catch((err) => {
- if (refreshIdRef.current === refreshId) {
- setError(formatError(err));
- }
- })
- .finally(() => {
- if (refreshIdRef.current === refreshId) {
- setLoading(false);
- }
- });
- }, []);
+ const modelCounts = useMemo(
+ () =>
+ localModels.ready
+ ? countModelsPerFolder(
+ folders.map((folder) => folder.path),
+ localModels.rows.map((row) => row.path),
+ )
+ : null,
+ [folders, localModels.ready, localModels.rows],
+ );
+ // A finished inventory scan is what records a folder as slow or unreadable.
+ const scannedAt = localModels.refreshedAt;
useEffect(() => {
- if (!open) return;
- const timer = window.setTimeout(refreshFolders, 0);
- return () => window.clearTimeout(timer);
- }, [open, refreshFolders]);
+ if (open && scannedAt !== null) {
+ void refreshScanFolders().catch(() => undefined);
+ }
+ }, [open, scannedAt]);
useEffect(() => {
if (!open) return;
+ setInputError(null);
let cancelled = false;
// The dialog stays mounted between opens, so re-arm the flag or a reopen
// shows the previous answer as if it were fresh.
setDownloadCacheLoaded(false);
loadHuggingFaceCacheSettings()
- // Indexed locations do not depend on this. Null drops the stale path
- // rather than offer Change against a location we could not confirm.
+ // Null drops the stale path rather than offer Change against a location we could not confirm.
.catch(() => null)
.then((settings) => {
if (cancelled) return;
@@ -153,23 +151,18 @@ export function OnDeviceFoldersDialog({
};
}, [open]);
- const handleInventoryChanged = useCallback(() => {
- onInventoryChange?.();
- }, [onInventoryChange]);
-
- // Relocating the cache changes which repos are on disk, but updateHuggingFaceCacheSettings
- // already bumps the inventory version, which re-fetches every source. Refreshing here too would
- // scan twice, since the two rounds carry different version keys and cannot be deduplicated.
+ // updateHuggingFaceCacheSettings bumps the inventory version, which re-fetches every source;
+ // refreshing here too would scan twice under two keys that cannot be deduplicated.
const saveDownloadLocation = useCallback(async (nextPath: string | null) => {
setDownloadSaving(true);
try {
const settings = await updateHuggingFaceCacheSettings(nextPath);
setDownloadCache(settings);
- toast.success("Download location updated", {
+ toast.success("Models folder updated", {
description: settings.cacheHome,
});
} catch (err) {
- toast.error("Couldn't update the download location", {
+ toast.error("Couldn't change the Models folder", {
description: formatError(err),
});
} finally {
@@ -193,78 +186,109 @@ export function OnDeviceFoldersDialog({
}, [saveDownloadLocation]);
const handleAdd = useCallback(
- async (rawPath: string) => {
+ async (rawPath: string, source: "input" | "browse") => {
const nextPath = rawPath.trim();
if (!nextPath || pending) return;
setPending("add");
- setError(null);
+ setInputError(null);
try {
- const folder = await addScanFolder(nextPath, recursive);
+ const { folder, alreadyAdded } = await addScanFolderToStore(nextPath);
setPath("");
- mutationVersionRef.current += 1;
- setFolders((current) => {
- const withoutDuplicate = current.filter(
- (row) => row.id !== folder.id,
- );
- return [...withoutDuplicate, folder];
- });
- toast.success("Location added", {
- description: pathTail(folder.path),
+ if (alreadyAdded) {
+ toast.info("Already in your folders", {
+ description: folderDisplayName(folder.path),
+ });
+ return;
+ }
+ toast.success("Folder added", {
+ description: folderDisplayName(folder.path),
});
- handleInventoryChanged();
+ onInventoryChange?.();
} catch (err) {
const message = formatError(err);
- setError(message);
- toast.error("Couldn't add location", { description: message });
+ if (source === "input") setInputError(message);
+ else toast.error("Couldn't add folder", { description: message });
} finally {
setPending(null);
}
},
- [handleInventoryChanged, pending, recursive],
+ [onInventoryChange, pending],
);
- const isOwner = useIsAccountOwner();
const browseLocations = useCallback(async () => {
- const picked = await pickNativeModelFolder(isOwner);
- if (picked === undefined) setBrowserOpen(true);
- else if (picked) await handleAdd(picked);
+ try {
+ const picked = await pickNativeModelFolder(isOwner);
+ if (picked === undefined) setBrowserOpen(true);
+ else if (picked) await handleAdd(picked, "browse");
+ } catch (err) {
+ toast.error("Couldn't open the folder picker", {
+ description: formatError(err),
+ });
+ }
}, [handleAdd, isOwner]);
- // Scan folders are arbitrary paths that may be moved or deleted after they
- // were registered, so surface the command's failure as a toast.
const handleOpen = useCallback(async (folder: ScanFolderInfo) => {
try {
await openModelsDir(folder.path);
} catch (err) {
- toast.error("Couldn't open location", { description: formatError(err) });
+ toast.error("Couldn't open folder", { description: formatError(err) });
}
}, []);
+ const handleRecursive = useCallback(
+ async (folder: ScanFolderInfo, recursive: boolean) => {
+ if (pending) return;
+ setPending(`recursive:${folder.id}`);
+ try {
+ await setScanFolderRecursive(folder, recursive);
+ onInventoryChange?.();
+ } catch (err) {
+ toast.error("Couldn't change the folder", {
+ description: formatError(err),
+ });
+ } finally {
+ setPending(null);
+ }
+ },
+ [onInventoryChange, pending],
+ );
+
const handleRemove = useCallback(
async (folder: ScanFolderInfo) => {
- const key = `remove:${folder.id}` as const;
if (pending) return;
- setPending(key);
- setError(null);
+ setPending(`remove:${folder.id}`);
try {
- await removeScanFolder(folder.id);
- mutationVersionRef.current += 1;
- setFolders((current) => current.filter((row) => row.id !== folder.id));
- toast.success("Location removed", {
- description: pathTail(folder.path),
+ await removeScanFolderFromStore(folder.id);
+ onInventoryChange?.();
+ // Removing only stops the scan, so an undo is safer than a confirm step.
+ toast.success("Folder removed", {
+ description: folderDisplayName(folder.path),
+ action: {
+ label: "Undo",
+ onClick: () => {
+ addScanFolderToStore(folder.path, Boolean(folder.recursive))
+ .then(() => onInventoryChange?.())
+ .catch((err) =>
+ toast.error("Couldn't restore folder", {
+ description: formatError(err),
+ }),
+ );
+ },
+ },
});
- handleInventoryChanged();
} catch (err) {
- const message = formatError(err);
- setError(message);
- toast.error("Couldn't remove location", { description: message });
+ toast.error("Couldn't remove folder", {
+ description: formatError(err),
+ });
} finally {
setPending(null);
}
},
- [handleInventoryChanged, pending],
+ [onInventoryChange, pending],
);
+ const freeSpace = formatFreeSpace(downloadCache?.freeBytes ?? null);
+
return (
<>
<Dialog open={open} onOpenChange={onOpenChange}>
@@ -273,33 +297,40 @@ export function OnDeviceFoldersDialog({
overlayClassName="bg-black/20 backdrop-blur-none"
>
<DialogHeader className="shrink-0 border-b border-border/60 px-5 py-4">
- <DialogTitle className="text-ui-15">
- On-device locations
- </DialogTitle>
- <DialogDescription className="sr-only">
- Hugging Face model folders, GGUF files, and adapters are indexed
- here.
+ <DialogTitle className="text-ui-15">Model folders</DialogTitle>
+ <DialogDescription className="text-ui-12 text-muted-foreground">
+ Unsloth lists models from your Models folder and from any custom
+ folders you add. Nothing is moved or copied.
</DialogDescription>
</DialogHeader>
<div className="min-h-0 flex-1 space-y-4 overflow-y-auto px-5 py-4">
- <div className="rounded-[14px] border border-border/70 bg-muted/20 p-3">
- <div className="mb-2 flex items-center gap-2 text-ui-12 font-medium text-foreground">
+ <section
+ aria-labelledby="models-folder-heading"
+ className="rounded-[14px] border border-border/70 bg-muted/20 p-3"
+ >
+ <div
+ id="models-folder-heading"
+ className="mb-2 flex items-center gap-2 text-ui-12 font-medium text-foreground"
+ >
<HugeiconsIcon
icon={Download01Icon}
strokeWidth={1.75}
className="size-3.5 text-muted-foreground"
/>
- Download location
+ Models folder
+ <span className="font-normal text-muted-foreground">
+ New downloads are saved here
+ </span>
</div>
<div className="flex flex-col gap-2 sm:flex-row sm:items-center">
<Input
readOnly={true}
- aria-label="Model download location"
+ aria-label="Models folder"
value={
downloadCache?.cacheHome ??
- (downloadCacheLoaded ? "Unknown" : "Loading...")
+ (downloadCacheLoaded ? "Unavailable" : "Loading...")
}
title={downloadCache?.cacheHome}
className="field-soft h-9 min-w-0 flex-1 rounded-full px-3 font-mono text-ui-12"
@@ -325,7 +356,8 @@ export function OnDeviceFoldersDialog({
)}
Change
</Button>
- {downloadCache?.isCustom ? (
+ {downloadCache?.isCustom &&
+ downloadCache.source !== "environment" ? (
<Button
type="button"
variant="ghost"
@@ -342,127 +374,87 @@ export function OnDeviceFoldersDialog({
<p className="mt-2 text-ui-10p5 text-muted-foreground">
{downloadCache?.source === "environment"
- ? `Managed by the ${
+ ? `Set by the ${
downloadCache.environmentVariable ?? "HF_HOME"
- } environment variable.`
+ } environment variable. Unset it to choose a folder here.`
: [
- "New downloads only. Models already on disk stay where they are.",
- formatFreeSpace(downloadCache?.freeBytes ?? null),
+ "Models you already downloaded stay where they are.",
+ freeSpace,
]
.filter(Boolean)
.join(" · ")}
</p>
- </div>
-
- <div className="rounded-[14px] border border-border/70 bg-muted/20 p-3">
- <div className="mb-2 flex items-center gap-2 text-ui-12 font-medium text-foreground">
- <HugeiconsIcon
- icon={FolderAddIcon}
- strokeWidth={1.75}
- className="size-3.5 text-muted-foreground"
- />
- Add location
- </div>
+ {isOwner && browserDownloadDir ? (
+ <p className="mt-1.5 text-ui-10p5 text-muted-foreground">
+ Downloads from this browser go to{" "}
+ <span
+ className="font-mono text-foreground"
+ title={browserDownloadDir}
+ >
+ {folderDisplayName(browserDownloadDir)}
+ </span>{" "}
+ instead (Download to menu).{" "}
+ <button
+ type="button"
+ onClick={() => setDownloadDir(null)}
+ className="font-medium text-foreground underline-offset-2 hover:underline"
+ >
+ Use the Models folder
+ </button>
+ </p>
+ ) : null}
+ </section>
- <div className="flex flex-col gap-2 sm:flex-row sm:items-center">
- <div className="relative min-w-0 flex-1">
- <HugeiconsIcon
- icon={FileSearchIcon}
- strokeWidth={1.75}
- className="pointer-events-none absolute left-3 top-1/2 size-3.5 -translate-y-1/2 text-muted-foreground"
- />
- <Input
- value={path}
- onChange={(event) => setPath(event.target.value)}
- onKeyDown={(event) => {
- if (event.key !== "Enter") return;
- event.preventDefault();
- void handleAdd(path);
- }}
- placeholder="Paste model folder or file path"
- className="field-soft h-9 rounded-full pl-9 pr-3 font-mono text-ui-12 placeholder:font-sans"
- />
- </div>
- <div className="flex shrink-0 items-center gap-2">
+ <section
+ aria-labelledby="custom-folders-heading"
+ className="overflow-hidden rounded-[14px] border border-border/70"
+ >
+ <div className="flex h-10 items-center justify-between gap-2 border-b border-border/60 px-3">
+ <div className="flex min-w-0 items-center gap-1.5">
+ <span
+ id="custom-folders-heading"
+ className="text-ui-12 font-medium text-foreground"
+ >
+ Custom folders
+ </span>
+ {loaded && folders.length > 0 ? (
+ <span className="text-ui-11 text-muted-foreground">
+ {folders.length}
+ </span>
+ ) : null}
<Tooltip>
<TooltipTrigger asChild={true}>
- <Button
+ <button
type="button"
- variant="outline"
- size="icon-sm"
- onClick={() => void browseLocations()}
- aria-label="Browse locations"
- className="size-9 rounded-full"
+ aria-label="What can a custom folder hold?"
+ className="inline-flex size-6 items-center justify-center rounded-full text-muted-foreground transition-colors hover:bg-muted hover:text-foreground"
>
<HugeiconsIcon
- icon={FolderSearchIcon}
+ icon={InformationCircleIcon}
strokeWidth={1.75}
- className="size-4"
+ className="size-3.5"
/>
- </Button>
+ </button>
</TooltipTrigger>
- <TooltipContent side="bottom" className="tooltip-compact">
- Browse
+ <TooltipContent
+ side="bottom"
+ className="tooltip-compact max-w-xs"
+ >
+ GGUF files, Hugging Face model folders or caches, LM
+ Studio and Ollama libraries, LoRA adapters, and ComfyUI
+ installs (diffusion_models, unet, checkpoints and
+ extra_model_paths.yaml).
</TooltipContent>
</Tooltip>
- <Button
- type="button"
- size="sm"
- onClick={() => void handleAdd(path)}
- disabled={!path.trim() || pending !== null}
- className="h-9 rounded-full px-3 text-ui-12p5"
- >
- {pending === "add" ? (
- <Spinner className="size-3.5" />
- ) : (
- <HugeiconsIcon
- icon={PlusSignIcon}
- strokeWidth={1.75}
- data-icon="inline-start"
- className="size-3.5"
- />
- )}
- Add
- </Button>
</div>
- </div>
- <div className="mt-2 flex items-center gap-2">
- <Checkbox
- id="scan-folder-recursive"
- checked={recursive}
- onCheckedChange={(checked) => setRecursive(checked === true)}
- />
- <label
- htmlFor="scan-folder-recursive"
- className="text-ui-12 text-muted-foreground"
- >
- Also scan sub-folders
- </label>
- </div>
- <p className="mt-2 text-ui-10p5 text-muted-foreground">
- Adding a ComfyUI folder, or its models folder, lists the image
- and video models in its diffusion_models, unet and checkpoints
- folders, plus any extra_model_paths.yaml entries.
- </p>
- </div>
-
- {error ? (
- <div className="rounded-[10px] border border-destructive/20 bg-destructive/5 px-3 py-2 text-ui-12 text-destructive">
- {error}
- </div>
- ) : null}
-
- <div className="overflow-hidden rounded-[14px] border border-border/70">
- <div className="flex h-10 items-center justify-between border-b border-border/60 px-3">
- <span className="text-ui-12 font-medium text-foreground">
- Indexed locations
- </span>
<Tooltip>
<TooltipTrigger asChild={true}>
<button
type="button"
- aria-label="Refresh locations"
- onClick={refreshFolders}
+ aria-label="Refresh folders"
+ onClick={() =>
+ void refreshScanFolders().catch(() => undefined)
+ }
disabled={loading}
className="inline-flex size-7 items-center justify-center rounded-full text-muted-foreground transition-colors hover:bg-muted hover:text-foreground disabled:opacity-50"
>
@@ -479,133 +471,120 @@ export function OnDeviceFoldersDialog({
</Tooltip>
</div>
- <div className="max-h-64 overflow-y-auto">
- {loading ? (
+ <div className="border-b border-border/60 bg-muted/20 p-3">
+ <form
+ className="flex flex-col gap-2 sm:flex-row sm:items-center"
+ onSubmit={(event) => {
+ event.preventDefault();
+ void handleAdd(path, "input");
+ }}
+ >
+ <Input
+ value={path}
+ onChange={(event) => {
+ setPath(event.target.value);
+ if (inputError) setInputError(null);
+ }}
+ aria-label="Folder path"
+ aria-invalid={inputError ? true : undefined}
+ aria-describedby={
+ inputError ? "custom-folder-error" : undefined
+ }
+ placeholder="Paste a folder path"
+ spellCheck={false}
+ autoComplete="off"
+ className="field-soft h-9 min-w-0 flex-1 rounded-full px-3 font-mono text-ui-12 placeholder:font-sans"
+ />
+ <div className="flex shrink-0 items-center gap-2">
+ <Button
+ type="button"
+ variant="outline"
+ size="sm"
+ onClick={() => void browseLocations()}
+ disabled={pending !== null}
+ className="h-9 rounded-full px-3 text-ui-12p5"
+ >
+ <HugeiconsIcon
+ icon={FolderSearchIcon}
+ strokeWidth={1.75}
+ data-icon="inline-start"
+ className="size-3.5"
+ />
+ Browse...
+ </Button>
+ <Button
+ type="submit"
+ size="sm"
+ disabled={!path.trim() || pending !== null}
+ className="h-9 rounded-full px-3 text-ui-12p5"
+ >
+ {pending === "add" ? (
+ <Spinner className="size-3.5" />
+ ) : (
+ <HugeiconsIcon
+ icon={PlusSignIcon}
+ strokeWidth={1.75}
+ data-icon="inline-start"
+ className="size-3.5"
+ />
+ )}
+ Add
+ </Button>
+ </div>
+ </form>
+ {inputError ? (
+ <p
+ id="custom-folder-error"
+ role="alert"
+ className="mt-2 px-1 text-ui-11 text-destructive"
+ >
+ {inputError}
+ </p>
+ ) : null}
+ </div>
+
+ <div className="max-h-72 overflow-y-auto">
+ {!loaded && loading ? (
<div className="flex h-24 items-center justify-center gap-2 text-ui-12 text-muted-foreground">
<Spinner className="size-3.5" />
- Loading locations...
+ Loading folders...
+ </div>
+ ) : !loaded && listError ? (
+ <div className="flex h-24 items-center justify-center px-4 text-center text-ui-12 text-destructive">
+ {listError}
</div>
) : sortedFolders.length === 0 ? (
- <div className="flex h-28 flex-col items-center justify-center gap-2 px-4 text-center text-ui-12 text-muted-foreground">
+ <div className="flex flex-col items-center justify-center gap-1.5 px-6 py-6 text-center">
<HugeiconsIcon
- icon={FolderOpenIcon}
+ icon={FolderAddIcon}
strokeWidth={1.75}
className="size-5 text-muted-foreground/60"
/>
- No custom locations
+ <p className="text-ui-12 font-medium text-foreground">
+ No custom folders yet
+ </p>
+ <p className="max-w-sm text-ui-11 text-muted-foreground">
+ Add a folder where you keep models, such as an LM Studio,
+ Ollama or ComfyUI folder, or an external drive.
+ </p>
</div>
) : (
- sortedFolders.map((folder) => {
- const removing = pending === `remove:${folder.id}`;
- const problem = scanFolderStatusCopy(folder.status);
- return (
- <div
+ <ul aria-labelledby="custom-folders-heading">
+ {sortedFolders.map((folder) => (
+ <FolderRow
key={folder.id}
- className={cn(
- "grid min-h-12 w-full items-center gap-3 border-b border-border/50 px-3 py-2 last:border-b-0",
- isTauri
- ? "grid-cols-[2rem_minmax(0,1fr)_2rem_2rem]"
- : "grid-cols-[2rem_minmax(0,1fr)_2rem]",
- )}
- >
- <div className="flex size-8 shrink-0 items-center justify-center rounded-[9px] bg-muted text-muted-foreground">
- <HugeiconsIcon
- icon={FolderOpenIcon}
- strokeWidth={1.75}
- className="size-4"
- />
- </div>
- <div className="min-w-0 overflow-hidden">
- <p
- className="block w-full truncate text-ui-12p5 font-medium text-foreground"
- title={pathTail(folder.path)}
- >
- {pathTail(folder.path)}
- </p>
- <Tooltip>
- <TooltipTrigger asChild={true}>
- <p className="block w-full truncate font-mono text-ui-10p5 text-muted-foreground">
- {folder.path}
- </p>
- </TooltipTrigger>
- <TooltipContent
- side="bottom"
- className="tooltip-compact max-w-xs break-all"
- >
- {folder.path}
- </TooltipContent>
- </Tooltip>
- {folder.recursive ? (
- <p className="text-ui-10p5 text-muted-foreground">
- Includes sub-folders
- </p>
- ) : null}
- {problem ? (
- <p
- data-testid={`scan-folder-problem-${folder.id}`}
- className="mt-1 text-ui-10p5 text-amber-600 dark:text-amber-500"
- >
- {problem.title}. {problem.hint}
- </p>
- ) : null}
- </div>
- {isTauri ? (
- <Tooltip>
- <TooltipTrigger asChild={true}>
- <button
- type="button"
- aria-label={`Open ${folder.path}`}
- onClick={() => void handleOpen(folder)}
- className="inline-flex size-8 shrink-0 items-center justify-center rounded-full text-muted-foreground transition-colors hover:bg-muted hover:text-foreground"
- >
- <HugeiconsIcon
- icon={FolderExportIcon}
- strokeWidth={1.75}
- className="size-4"
- />
- </button>
- </TooltipTrigger>
- <TooltipContent
- side="left"
- className="tooltip-compact"
- >
- Open in file manager
- </TooltipContent>
- </Tooltip>
- ) : null}
- <Tooltip>
- <TooltipTrigger asChild={true}>
- <button
- type="button"
- aria-label={`Remove ${folder.path}`}
- onClick={() => void handleRemove(folder)}
- disabled={pending !== null}
- className="inline-flex size-8 shrink-0 items-center justify-center rounded-full text-muted-foreground transition-colors hover:bg-destructive/10 hover:text-destructive disabled:opacity-50"
- >
- {removing ? (
- <Spinner className="size-3.5" />
- ) : (
- <HugeiconsIcon
- icon={Delete02Icon}
- strokeWidth={1.75}
- className="size-4"
- />
- )}
- </button>
- </TooltipTrigger>
- <TooltipContent
- side="left"
- className="tooltip-compact"
- >
- Remove from list
- </TooltipContent>
- </Tooltip>
- </div>
- );
- })
+ folder={folder}
+ modelCount={modelCounts?.get(folder.path) ?? null}
+ pending={pending}
+ onOpen={handleOpen}
+ onRecursive={handleRecursive}
+ onRemove={handleRemove}
+ />
+ ))}
+ </ul>
)}
</div>
- </div>
+ </section>
</div>
</DialogContent>
</Dialog>
@@ -613,7 +592,7 @@ export function OnDeviceFoldersDialog({
<FolderBrowser
open={browserOpen}
onOpenChange={setBrowserOpen}
- onSelect={(selectedPath) => void handleAdd(selectedPath)}
+ onSelect={(selectedPath) => void handleAdd(selectedPath, "browse")}
/>
<FolderBrowser
@@ -621,10 +600,144 @@ export function OnDeviceFoldersDialog({
onOpenChange={setDownloadBrowserOpen}
onSelect={(selectedPath) => void saveDownloadLocation(selectedPath)}
initialPath={downloadCache?.cacheHome}
- title="Choose model download location"
- confirmLabel="Use for future downloads"
+ title="Choose the Models folder"
+ confirmLabel="Use for new downloads"
showModelHints={false}
/>
</>
);
}
+
+function FolderRow({
+ folder,
+ modelCount,
+ pending,
+ onOpen,
+ onRecursive,
+ onRemove,
+}: {
+ folder: ScanFolderInfo;
+ modelCount: number | null;
+ pending: Pending;
+ onOpen: (folder: ScanFolderInfo) => void;
+ onRecursive: (folder: ScanFolderInfo, recursive: boolean) => void;
+ onRemove: (folder: ScanFolderInfo) => void;
+}) {
+ const name = folderDisplayName(folder.path);
+ const problem = scanFolderStatusCopy(folder.status);
+ const removing = pending === `remove:${folder.id}`;
+ const toggling = pending === `recursive:${folder.id}`;
+ const switchId = `scan-folder-recursive-${folder.id}`;
+ return (
+ <li className="flex min-h-14 items-center gap-3 border-b border-border/50 px-3 py-2.5 last:border-b-0">
+ <div className="flex size-8 shrink-0 items-center justify-center rounded-[9px] bg-muted text-muted-foreground">
+ <HugeiconsIcon
+ icon={FolderOpenIcon}
+ strokeWidth={1.75}
+ className="size-4"
+ />
+ </div>
+ <div className="min-w-0 flex-1">
+ <div className="flex min-w-0 items-baseline gap-2">
+ <p
+ className="truncate text-ui-12p5 font-medium text-foreground"
+ title={name}
+ >
+ {name}
+ </p>
+ {modelCount !== null && !problem ? (
+ <span className="shrink-0 text-ui-10p5 text-muted-foreground">
+ {modelCountLabel(modelCount)}
+ </span>
+ ) : null}
+ </div>
+ <p
+ className="truncate font-mono text-ui-10p5 text-muted-foreground"
+ title={folder.path}
+ >
+ {folder.path}
+ </p>
+ {problem ? (
+ <p
+ data-testid={`scan-folder-problem-${folder.id}`}
+ className="mt-1 text-ui-10p5 text-amber-600 dark:text-amber-500"
+ >
+ {problem.title}. {problem.hint}
+ </p>
+ ) : null}
+ </div>
+ <div className="flex shrink-0 items-center gap-1.5">
+ <Tooltip>
+ <TooltipTrigger asChild={true}>
+ <label
+ htmlFor={switchId}
+ className="flex cursor-pointer items-center gap-1.5 rounded-full px-1.5 py-1 text-ui-11 text-muted-foreground"
+ >
+ <span className="hidden sm:inline">Sub-folders</span>
+ {toggling ? (
+ <Spinner className="size-3.5" />
+ ) : (
+ <Switch
+ id={switchId}
+ size="sm"
+ checked={Boolean(folder.recursive)}
+ onCheckedChange={(checked) => onRecursive(folder, checked)}
+ disabled={pending !== null}
+ aria-label={`Also scan sub-folders of ${name}`}
+ />
+ )}
+ </label>
+ </TooltipTrigger>
+ <TooltipContent side="bottom" className="tooltip-compact">
+ Also scan sub-folders
+ </TooltipContent>
+ </Tooltip>
+ {isTauri ? (
+ <Tooltip>
+ <TooltipTrigger asChild={true}>
+ <button
+ type="button"
+ aria-label={`Open ${name} in file manager`}
+ onClick={() => onOpen(folder)}
+ className="inline-flex size-8 items-center justify-center rounded-full text-muted-foreground transition-colors hover:bg-muted hover:text-foreground"
+ >
+ <HugeiconsIcon
+ icon={FolderExportIcon}
+ strokeWidth={1.75}
+ className="size-4"
+ />
+ </button>
+ </TooltipTrigger>
+ <TooltipContent side="left" className="tooltip-compact">
+ Open in file manager
+ </TooltipContent>
+ </Tooltip>
+ ) : null}
+ <Tooltip>
+ <TooltipTrigger asChild={true}>
+ <button
+ type="button"
+ aria-label={`Remove ${name}`}
+ onClick={() => onRemove(folder)}
+ disabled={pending !== null}
+ className="inline-flex size-8 items-center justify-center rounded-full text-muted-foreground transition-colors hover:bg-destructive/10 hover:text-destructive disabled:opacity-50"
+ >
+ {removing ? (
+ <Spinner className="size-3.5" />
+ ) : (
+ <HugeiconsIcon
+ icon={Delete02Icon}
+ strokeWidth={1.75}
+ className="size-4"
+ />
+ )}
+ </button>
+ </TooltipTrigger>
+ <TooltipContent side="left" className="tooltip-compact">
+ Remove from list (files stay on disk)
+ </TooltipContent>
+ </Tooltip>
+ </div>
+ </li>
+ );
+}
diff --git a/studio/frontend/src/features/hub/hub-page.tsx b/studio/frontend/src/features/hub/hub-page.tsx
index bab532d9d8f..6f21a97d9cb 100644
--- a/studio/frontend/src/features/hub/hub-page.tsx
+++ b/studio/frontend/src/features/hub/hub-page.tsx
@@ -2237,7 +2237,6 @@ export function ModelsPage() {
<OnDeviceFoldersDialog
open={foldersDialogOpen}
onOpenChange={setFoldersDialogOpen}
- onInventoryChange={refreshInventory}
/>
<FreeUpSpaceDialog
open={freeUpSpaceOpen}
diff --git a/studio/frontend/src/features/hub/index.ts b/studio/frontend/src/features/hub/index.ts
index 68f0f9aa4d7..a9badaa802d 100644
--- a/studio/frontend/src/features/hub/index.ts
+++ b/studio/frontend/src/features/hub/index.ts
@@ -115,6 +115,19 @@ export {
export { useInventoryVersion } from "./stores/inventory-events";
export { looksLikeLocalPath, localPathCacheKey } from "./lib/local-path";
export { scanFolderStatusCopy } from "./lib/scan-folder-status";
+export {
+ countModelsPerFolder,
+ folderDisplayName,
+} from "./lib/scan-folder-models";
+export {
+ addScanFolderToStore,
+ refreshScanFolders,
+ removeScanFolderFromStore,
+ setScanFolderRecursive,
+ useScanFolders,
+ type AddScanFolderResult,
+ type ScanFoldersState,
+} from "./inventory/scan-folders-store";
export type { ScanFolderStatus } from "./lib/scan-folder-status";
export { hubTokenHeader } from "./lib/hub-token-header";
export {
diff --git a/studio/frontend/src/features/hub/inventory/api.ts b/studio/frontend/src/features/hub/inventory/api.ts
index 51ef742da8a..0e7c9252edc 100644
--- a/studio/frontend/src/features/hub/inventory/api.ts
+++ b/studio/frontend/src/features/hub/inventory/api.ts
@@ -480,8 +480,11 @@ export async function deleteLocalModel(path: string, id?: string): Promise<void>
export async function listScanFolders(): Promise<ScanFolderInfo[]> {
const response = await authFetch("/api/hub/scan-folders");
- const data = await parseJsonOrThrow<{ folders: ScanFolderInfo[] }>(response);
- return data.folders;
+ const data = await parseJsonOrThrow<{ folders?: ScanFolderInfo[] }>(
+ response,
+ );
+ // Every surface iterates this list, so a body without it must not take the page down.
+ return Array.isArray(data?.folders) ? data.folders : [];
}
export async function addScanFolder(
diff --git a/studio/frontend/src/features/hub/inventory/scan-folders-store.ts b/studio/frontend/src/features/hub/inventory/scan-folders-store.ts
new file mode 100644
index 00000000000..da6e4f0f780
--- /dev/null
+++ b/studio/frontend/src/features/hub/inventory/scan-folders-store.ts
@@ -0,0 +1,157 @@
+// 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 { useEffect, useSyncExternalStore } from "react";
+import { subscribeInventory } from "../stores/inventory-events";
+import {
+ type ScanFolderInfo,
+ addScanFolder,
+ listScanFolders,
+ removeScanFolder,
+} from "./api";
+
+/** One copy of the custom folder list for every surface (folders dialog, model picker, Download
+ * to menu), so a change in one shows in the others and opening any of them is one request. */
+export interface ScanFoldersState {
+ folders: ScanFolderInfo[];
+ loaded: boolean;
+ loading: boolean;
+ error: string | null;
+}
+
+const EMPTY_STATE: ScanFoldersState = {
+ folders: [],
+ loaded: false,
+ loading: false,
+ error: null,
+};
+
+let state = EMPTY_STATE;
+let inFlight: Promise<ScanFolderInfo[]> | null = null;
+// Bumped by every local mutation, so a list fetched before it cannot overwrite its result.
+let mutationSeq = 0;
+// The mutation's own inventory bump must not refetch the list it is about to update in place.
+let mutating = 0;
+const listeners = new Set<() => void>();
+
+function setState(next: Partial<ScanFoldersState>): void {
+ state = { ...state, ...next };
+ for (const listener of [...listeners]) listener();
+}
+
+function errorMessage(error: unknown): string {
+ return error instanceof Error ? error.message : String(error);
+}
+
+export function getScanFoldersState(): ScanFoldersState {
+ return state;
+}
+
+export function subscribeScanFolders(listener: () => void): () => void {
+ listeners.add(listener);
+ return () => listeners.delete(listener);
+}
+
+/** Concurrent callers share one request. */
+export function refreshScanFolders(): Promise<ScanFolderInfo[]> {
+ if (inFlight) return inFlight;
+ const seq = mutationSeq;
+ let superseded = false;
+ setState({ loading: true });
+ const request = listScanFolders()
+ .then((folders) => {
+ // May predate a mutation that landed meanwhile: reread rather than drop it.
+ superseded = seq !== mutationSeq;
+ if (!superseded) setState({ folders, loaded: true, error: null });
+ return state.folders;
+ })
+ .catch((error: unknown) => {
+ setState({ error: errorMessage(error) });
+ throw error;
+ })
+ .finally(() => {
+ inFlight = null;
+ setState({ loading: false });
+ if (superseded) void refreshScanFolders().catch(() => undefined);
+ });
+ inFlight = request;
+ return request;
+}
+
+function revalidateScanFolders(): void {
+ if (inFlight || mutating > 0) return;
+ void refreshScanFolders().catch(() => undefined);
+}
+
+async function mutate<T>(request: () => Promise<T>): Promise<T> {
+ mutating += 1;
+ try {
+ return await request();
+ } finally {
+ mutating -= 1;
+ }
+}
+
+function upsert(folder: ScanFolderInfo): void {
+ mutationSeq += 1;
+ const rest = state.folders.filter((row) => row.id !== folder.id);
+ setState({ folders: [...rest, folder] });
+}
+
+export interface AddScanFolderResult {
+ folder: ScanFolderInfo;
+ alreadyAdded: boolean;
+}
+
+/** `recursive` undefined keeps the stored flag of a folder that is already registered. */
+export async function addScanFolderToStore(
+ path: string,
+ recursive?: boolean,
+): Promise<AddScanFolderResult> {
+ const known = new Map(state.folders.map((row) => [row.id, row]));
+ const folder = await mutate(() => addScanFolder(path, recursive));
+ const previous = known.get(folder.id);
+ // The add route answers "ok" without scanning; keep a known row's last status.
+ upsert({ ...folder, status: previous?.status ?? folder.status });
+ return {
+ folder,
+ alreadyAdded:
+ previous !== undefined &&
+ Boolean(previous.recursive) === Boolean(folder.recursive),
+ };
+}
+
+export async function setScanFolderRecursive(
+ folder: ScanFolderInfo,
+ recursive: boolean,
+): Promise<void> {
+ await addScanFolderToStore(folder.path, recursive);
+}
+
+export async function removeScanFolderFromStore(id: number): Promise<void> {
+ await mutate(() => removeScanFolder(id));
+ mutationSeq += 1;
+ setState({ folders: state.folders.filter((row) => row.id !== id) });
+}
+
+export function useScanFolders(enabled = true): ScanFoldersState {
+ const snapshot = useSyncExternalStore(
+ subscribeScanFolders,
+ getScanFoldersState,
+ getScanFoldersState,
+ );
+ // Read on every open: health changes without an inventory bump (a scan finishing, a fix outside Studio).
+ useEffect(() => {
+ if (!enabled) return;
+ revalidateScanFolders();
+ return subscribeInventory(revalidateScanFolders);
+ }, [enabled]);
+ return snapshot;
+}
+
+export function resetScanFoldersStoreForTests(): void {
+ state = EMPTY_STATE;
+ inFlight = null;
+ mutationSeq = 0;
+ mutating = 0;
+}
diff --git a/studio/frontend/src/features/hub/lib/scan-folder-models.ts b/studio/frontend/src/features/hub/lib/scan-folder-models.ts
new file mode 100644
index 00000000000..8886878ba13
--- /dev/null
+++ b/studio/frontend/src/features/hub/lib/scan-folder-models.ts
@@ -0,0 +1,33 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+function comparable(path: string): string {
+ const slashed = path.replace(/\\/g, "/").replace(/\/+$/, "");
+ // Drive-letter and UNC paths are Windows, which ignores case.
+ return /^([A-Za-z]:|\/\/)/.test(slashed) ? slashed.toLowerCase() : slashed;
+}
+
+/** Listed models per registered folder, counted from rows the inventory already holds. A model
+ * under two nested folders counts for the innermost one only. */
+export function countModelsPerFolder(
+ folderPaths: readonly string[],
+ modelPaths: readonly string[],
+): Map<string, number> {
+ const folders = folderPaths
+ .map((path) => ({ path, key: comparable(path) }))
+ .sort((a, b) => b.key.length - a.key.length);
+ const counts = new Map<string, number>(folderPaths.map((path) => [path, 0]));
+ for (const modelPath of modelPaths) {
+ const key = comparable(modelPath);
+ const owner = folders.find(
+ (folder) => key === folder.key || key.startsWith(`${folder.key}/`),
+ );
+ if (owner) counts.set(owner.path, (counts.get(owner.path) ?? 0) + 1);
+ }
+ return counts;
+}
+
+export function folderDisplayName(path: string): string {
+ const parts = path.split(/[\\/]/).filter(Boolean);
+ return parts.at(-1) ?? path;
+}
diff --git a/studio/frontend/src/features/hub/lib/scan-folder-status.ts b/studio/frontend/src/features/hub/lib/scan-folder-status.ts
index 76280b0e4af..55e85f596e6 100644
--- a/studio/frontend/src/features/hub/lib/scan-folder-status.ts
+++ b/studio/frontend/src/features/hub/lib/scan-folder-status.ts
@@ -13,7 +13,8 @@ export type ScanFolderStatus =
| "permission_denied"
| "missing"
| "unreadable"
- | "partial";
+ | "partial"
+ | "slow";
export interface ScanFolderStatusCopy {
title: string;
@@ -30,11 +31,11 @@ function hostPlatform(userAgent: string): "mac" | "windows" | "other" {
function permissionHint(userAgent: string): string {
switch (hostPlatform(userAgent)) {
case "mac":
- return "Grant access in System Settings > Privacy & Security > Files and Folders, then reopen this dialog.";
+ return "Grant access in System Settings > Privacy & Security > Files and Folders, then refresh the list.";
case "windows":
- return "Check the folder's security permissions, or allow Unsloth in Controlled Folder Access, then reopen this dialog.";
+ return "Check the folder's security permissions, or allow Unsloth in Controlled Folder Access, then refresh the list.";
default:
- return "Check the folder's permissions, then reopen this dialog.";
+ return "Check the folder's permissions, then refresh the list.";
}
}
@@ -61,7 +62,12 @@ export function scanFolderStatusCopy(
case "unreadable":
return {
title: "This folder could not be read",
- hint: "The drive may be disconnected or failing. Check it, then reopen this dialog.",
+ hint: "The drive may be disconnected or failing. Check it, then refresh the list.",
+ };
+ case "slow":
+ return {
+ title: "This folder is taking too long to scan",
+ hint: "It may be on a slow or disconnected network drive. Its models are skipped until a scan finishes in time.",
};
default:
return null;
diff --git a/studio/frontend/src/features/model-picker/components/model-selector/pickers.tsx b/studio/frontend/src/features/model-picker/components/model-selector/pickers.tsx
index c3a5910632a..57669fb4ece 100644
--- a/studio/frontend/src/features/model-picker/components/model-selector/pickers.tsx
+++ b/studio/frontend/src/features/model-picker/components/model-selector/pickers.tsx
@@ -26,14 +26,10 @@ import { usePlatformStore } from "@/config/env";
import { useIsAccountOwner } from "@/features/auth";
import { ApiProviderLogo } from "@/features/chat";
import {
- type ScanFolderInfo,
- addScanFolder,
deleteFineTunedModel,
listGgufVariants,
listRecommendedFolders,
- listScanFolders,
listLoras,
- removeScanFolder,
revealFineTunedModel,
} from "@/features/chat";
import {
@@ -87,6 +83,11 @@ import {
HubFailureHint,
useHubAvailability,
useOnlineStatus,
+ type ScanFolderInfo,
+ addScanFolderToStore,
+ folderDisplayName,
+ removeScanFolderFromStore,
+ useScanFolders,
} from "@/features/hub";
import type { HfTaskFilter } from "@/features/hub/hooks/use-hub-model-search";
import { INVENTORY_FRESHNESS_WINDOW_MS } from "@/features/hub/inventory";
@@ -2811,7 +2812,6 @@ let _cachedModelsCache: CachedModelRepo[] = [];
let _lmStudioCache: LocalModelInfo[] = [];
let _localDirCache: LocalModelInfo[] = [];
let _customFolderCache: LocalModelInfo[] = [];
-let _scanFoldersCache: ScanFolderInfo[] = [];
/** True when any on-device model (downloaded GGUF, cached repo, LM Studio, or custom-folder model)
* is known. Reads the module caches, which persist across popover mounts, so the selector can
@@ -3548,8 +3548,7 @@ export function HubModelPicker({
setUpdateConflictKey(null);
}, [updateConflictKey]);
- const [scanFolders, setScanFolders] =
- useState<ScanFolderInfo[]>(_scanFoldersCache);
+ const { folders: scanFolders } = useScanFolders();
const [folderInput, setFolderInput] = useState("");
const [folderError, setFolderError] = useState<string | null>(null);
const [showFolderInput, setShowFolderInput] = useState(false);
@@ -3561,15 +3560,8 @@ export function HubModelPicker({
void pickerInventory.refreshInventory();
}, [pickerInventory.refreshInventory]);
- const refreshScanFolders = useCallback(() => {
- listScanFolders()
- .then((v) => {
- _scanFoldersCache = v;
- setScanFolders(v);
- })
- .catch(() => {});
- }, []);
-
+ // The store's mutations bump the inventory version, which refetches every inventory reader
+ // (this picker's included); a forced refresh on top would scan twice.
const handleAddFolder = useCallback(
async (overridePath?: string) => {
// An explicit path lets the folder browser submit in the same tick it calls `setFolderInput`;
@@ -3582,20 +3574,15 @@ export function HubModelPicker({
// From the folder browser's "Use this folder": the typed-input panel is closed, so surface failures via toast.
const fromBrowser = overridePath !== undefined;
try {
- const created = await addScanFolder(trimmed);
- // Backend returns the existing row for duplicates, so dedupe.
- const next = _scanFoldersCache.some(
- (f) => f.id === created.id || f.path === created.path,
- )
- ? _scanFoldersCache
- : [..._scanFoldersCache, created];
- _scanFoldersCache = next;
- setScanFolders(next);
+ const { folder, alreadyAdded } = await addScanFolderToStore(trimmed);
setFolderInput("");
setShowFolderInput(false);
- refreshLocalModelsList();
+ if (alreadyAdded) {
+ toast.info("Already in your folders", {
+ description: folderDisplayName(folder.path),
+ });
+ }
onFoldersChange?.();
- void refreshScanFolders();
} catch (e) {
const message = e instanceof Error ? e.message : "Failed to add folder";
setFolderError(message);
@@ -3606,13 +3593,7 @@ export function HubModelPicker({
setFolderLoading(false);
}
},
- [
- folderInput,
- folderLoading,
- refreshScanFolders,
- refreshLocalModelsList,
- onFoldersChange,
- ],
+ [folderInput, folderLoading, onFoldersChange],
);
const isOwner = useIsAccountOwner();
@@ -3628,22 +3609,30 @@ export function HubModelPicker({
}, [handleAddFolder, isOwner]);
const handleRemoveFolder = useCallback(
- async (id: number) => {
+ async (folder: ScanFolderInfo) => {
try {
- await removeScanFolder(id);
- // Optimistic: drop it immediately.
- const next = _scanFoldersCache.filter((f) => f.id !== id);
- _scanFoldersCache = next;
- setScanFolders(next);
- refreshScanFolders();
- refreshLocalModelsList();
+ await removeScanFolderFromStore(folder.id);
onFoldersChange?.();
+ toast.success("Folder removed", {
+ description: folderDisplayName(folder.path),
+ action: {
+ label: "Undo",
+ onClick: () => {
+ addScanFolderToStore(folder.path, Boolean(folder.recursive))
+ .then(() => onFoldersChange?.())
+ .catch((e) =>
+ toast.error("Couldn't restore folder", {
+ description: e instanceof Error ? e.message : undefined,
+ }),
+ );
+ },
+ },
+ });
} catch (e) {
toast.error(e instanceof Error ? e.message : "Failed to remove folder");
- refreshScanFolders();
}
},
- [refreshScanFolders, refreshLocalModelsList, onFoldersChange],
+ [onFoldersChange],
);
const refreshCachedLists = useCallback(() => {
@@ -3685,11 +3674,10 @@ export function HubModelPicker({
);
useEffect(() => {
- refreshScanFolders();
listRecommendedFolders()
.then(setRecommendedFolders)
.catch(() => {});
- }, [refreshScanFolders]);
+ }, []);
useEffect(() => {
if (!shouldRefreshPickerInventoryOnMount(cachedReadyAtMount.current)) {
@@ -7819,7 +7807,7 @@ export function HubModelPicker({
icon={Folder02Icon}
className="size-3.5"
/>
- Custom Folders
+ Custom folders
</button>
<div className="flex items-center gap-0.5">
<button
@@ -7913,7 +7901,7 @@ export function HubModelPicker({
</div>
<button
type="button"
- onClick={() => handleRemoveFolder(f.id)}
+ onClick={() => void handleRemoveFolder(f)}
aria-label={`Remove folder ${f.path}`}
className="shrink-0 rounded p-1 text-muted-foreground transition-colors hover:bg-destructive/10 hover:text-destructive focus-visible:bg-destructive/10 focus-visible:text-destructive"
>
diff --git a/studio/frontend/tests/hub-on-device-filters.test.ts b/studio/frontend/tests/hub-on-device-filters.test.ts
index a01a13a2b41..fe22061aa7c 100644
--- a/studio/frontend/tests/hub-on-device-filters.test.ts
+++ b/studio/frontend/tests/hub-on-device-filters.test.ts
@@ -50,9 +50,9 @@ test("a row's own vision flag counts as Vision", () => {
assert.equal(matchesInventoryCapabilities(row, ["vision"]), true);
});
-test("Add folder and Free up space are icon buttons with labels", () => {
+test("Model folders and Free up space are icon buttons with labels", () => {
const toolbar = readSrc("features/hub/catalog/models-toolbar.tsx");
- for (const label of ["Add folder", "Free up space"]) {
+ for (const label of ["Model folders", "Free up space"]) {
assert.match(toolbar, new RegExp(`aria-label="${label}"`));
assert.doesNotMatch(toolbar, new RegExp(`/>\\s*${label}\\s*</button>`));
}
diff --git a/studio/frontend/tests/scan-folder-models.test.ts b/studio/frontend/tests/scan-folder-models.test.ts
new file mode 100644
index 00000000000..83d76a5f8ab
--- /dev/null
+++ b/studio/frontend/tests/scan-folder-models.test.ts
@@ -0,0 +1,77 @@
+// 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 assert from "node:assert/strict";
+import test from "node:test";
+
+import { readSrcAsync, registerBundlerResolver } from "./helpers/kit.ts";
+
+registerBundlerResolver();
+
+const { countModelsPerFolder, folderDisplayName } = await import(
+ "../src/features/hub/lib/scan-folder-models.ts"
+);
+const { scanFolderStatusCopy } = await import(
+ "../src/features/hub/lib/scan-folder-status.ts"
+);
+
+test("models count toward the folder that holds them", () => {
+ const counts = countModelsPerFolder(
+ ["/models", "/data/lms"],
+ [
+ "/models/a.gguf",
+ "/models/sub/b",
+ "/models-old/c.gguf",
+ "/data/lms/x/y.gguf",
+ "/elsewhere/z.gguf",
+ ],
+ );
+ assert.equal(counts.get("/models"), 2);
+ assert.equal(counts.get("/data/lms"), 1);
+});
+
+test("a nested folder takes its own models from its parent", () => {
+ const counts = countModelsPerFolder(
+ ["/models", "/models/comfy"],
+ ["/models/a.gguf", "/models/comfy/unet/b.safetensors"],
+ );
+ assert.equal(counts.get("/models"), 1);
+ assert.equal(counts.get("/models/comfy"), 1);
+});
+
+test("Windows paths compare without case or slash direction", () => {
+ const counts = countModelsPerFolder(
+ ["D:\\Models\\"],
+ ["d:/models/q4.gguf", "D:\\Models\\sub\\m"],
+ );
+ assert.equal(counts.get("D:\\Models\\"), 2);
+});
+
+test("a folder name is the last path segment", () => {
+ assert.equal(folderDisplayName("/Users/me/LM Studio/models"), "models");
+ assert.equal(folderDisplayName("C:\\AI\\gguf\\"), "gguf");
+});
+
+test("a folder skipped for taking too long says so", () => {
+ const copy = scanFolderStatusCopy("slow", "Mozilla/5.0 (Macintosh)");
+ assert.ok(copy);
+ assert.match(copy.title, /too long/);
+ assert.match(copy.hint, /network drive/);
+});
+
+test("every folder surface shares one store and the hub API", async () => {
+ const [pickers, dialog, chip, chatIndex] = await Promise.all([
+ readSrcAsync("features/model-picker/components/model-selector/pickers.tsx"),
+ readSrcAsync("features/hub/catalog/on-device-folders-dialog.tsx"),
+ readSrcAsync("features/hub/catalog/download-location-picker.tsx"),
+ readSrcAsync("features/chat/index.ts"),
+ ]);
+ for (const source of [pickers, dialog, chip]) {
+ assert.match(source, /useScanFolders\(/);
+ assert.doesNotMatch(source, /\blistScanFolders\(/);
+ }
+ // The /api/models copy never bumped the inventory version, so the rest of the app went stale.
+ assert.doesNotMatch(chatIndex, /ScanFolder/);
+ // Re-adding from the dialog must not send an explicit flag that resets a folder's sub-folder setting.
+ assert.match(dialog, /addScanFolderToStore\(nextPath\)/);
+});
diff --git a/studio/frontend/tests/scan-folders-store.test.ts b/studio/frontend/tests/scan-folders-store.test.ts
new file mode 100644
index 00000000000..acc7f9fbf35
--- /dev/null
+++ b/studio/frontend/tests/scan-folders-store.test.ts
@@ -0,0 +1,75 @@
+// 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 assert from "node:assert/strict";
+import { register } from "node:module";
+import test, { after } from "node:test";
+import { installLocalStorageFake } from "./helpers/kit.ts";
+
+register("./helpers/download-lifecycle-resolver.mjs", import.meta.url);
+installLocalStorageFake();
+
+const originalFetch = globalThis.fetch;
+after(() => {
+ globalThis.fetch = originalFetch;
+});
+
+const server = [{ id: 1, path: "/models/a", created_at: "", recursive: false }];
+let listGate: Promise<void> | null = null;
+let lists = 0;
+let bareBody = false;
+globalThis.fetch = (async (_input: string, init?: RequestInit) => {
+ const json = (body: unknown, status = 200) =>
+ new Response(JSON.stringify(body), {
+ status,
+ headers: { "Content-Type": "application/json" },
+ });
+ if (init?.method === "POST") {
+ const row = { id: 2, path: "/models/b", created_at: "", recursive: false };
+ server.push(row);
+ return json(row, 201);
+ }
+ lists += 1;
+ if (bareBody) return json({});
+ const snapshot = server.map((row) => ({ ...row }));
+ if (listGate) await listGate;
+ return json({ folders: snapshot });
+}) as typeof fetch;
+
+const store = await import("../src/features/hub/inventory/scan-folders-store.ts");
+
+test("an add during the first load keeps the folders the load was fetching", async () => {
+ store.resetScanFoldersStoreForTests();
+ let release: () => void = () => {};
+ listGate = new Promise((resolve) => {
+ release = resolve;
+ });
+ const firstLoad = store.refreshScanFolders();
+ await store.addScanFolderToStore("/models/b");
+ listGate = null;
+ release();
+ await firstLoad;
+ // The superseded list is read again rather than dropped.
+ await new Promise((resolve) => setTimeout(resolve, 0));
+ while (store.getScanFoldersState().loading) {
+ await new Promise((resolve) => setTimeout(resolve, 0));
+ }
+ assert.deepEqual(
+ store
+ .getScanFoldersState()
+ .folders.map((row) => row.path)
+ .sort(),
+ ["/models/a", "/models/b"],
+ );
+ assert.equal(lists, 2);
+});
+
+test("a list body without folders reads as none instead of crashing the page", async () => {
+ store.resetScanFoldersStoreForTests();
+ bareBody = true;
+ try {
+ assert.deepEqual(await store.refreshScanFolders(), []);
+ } finally {
+ bareBody = false;
+ }
+});