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: find models in a Hugging Face cache folder added as a location (#11970)

Nilay49d6c01c0aae
diff --git a/studio/backend/core/inference/local_model_resolver.py b/studio/backend/core/inference/local_model_resolver.py
index 151e60aa2cd..a3f08687380 100644
--- a/studio/backend/core/inference/local_model_resolver.py
+++ b/studio/backend/core/inference/local_model_resolver.py
@@ -811,6 +811,7 @@ def _build_index() -> dict[str, _LocalGgufEntry]:
_is_hidden_model,
)
from hub.utils.gguf import dedupe_custom_gguf_rows, suppress_grouped_gguf_file_rows
+ from hub.utils.inventory_scan import scan_folder_hf_caches
from utils.paths import legacy_hf_cache_dir, hf_default_cache_dir, lmstudio_model_dirs
from utils.hf_cache_settings import known_hf_hub_caches
from core.inference.model_ids import public_model_id
@@ -889,7 +890,7 @@ def _build_index() -> dict[str, _LocalGgufEntry]:
fp = Path(folder["path"])
custom_found += dedupe_custom_gguf_rows(
_scan_models_dir(fp, limit = 200)
- + _scan_hf_once(fp)
+ + [row for hub in scan_folder_hf_caches(fp) for row in _scan_hf_once(hub)]
+ _scan_lmstudio_dir(fp)
+ _scan_ollama_dir(fp, limit = 200, materialize_links = False)
)
diff --git a/studio/backend/hub/services/models/local_inventory.py b/studio/backend/hub/services/models/local_inventory.py
index 6f7a3f13546..73273021a96 100644
--- a/studio/backend/hub/services/models/local_inventory.py
+++ b/studio/backend/hub/services/models/local_inventory.py
@@ -705,16 +705,19 @@ async def _collect_models_from_default_sources(
)
for folder in custom_folders:
folder_path = Path(normalize_path(folder["path"])).expanduser()
- discovered = await _scan_source(
- "custom HF cache",
- lambda path: _discover_hf_cache(path, entry_limit = _MAX_CUSTOM_FOLDER_ENTRIES),
- folder_path,
- )
+ 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))
+ 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, discovered, str(folder["path"])))
- state_repositories.extend(
- ("model", model_id, folder_path) for _repo, model_id, _updated in discovered
- )
+ custom_sources.append((folder_path, hf_caches, str(folder["path"])))
try:
variant_states = await asyncio.to_thread(
download_manifest.build_variant_state_index,
@@ -747,12 +750,12 @@ 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}
- for folder_path, discovered, row_path in custom_sources:
+ for folder_path, hf_caches, row_path in custom_sources:
try:
custom_models = await asyncio.to_thread(
_scan_custom_folder,
folder_path,
- discovered = discovered,
+ hf_caches = hf_caches,
variant_states = variant_states,
active_hub_cache = hf_cache_dir,
)
@@ -789,13 +792,15 @@ async def _collect_models_from_default_sources(
def _scan_custom_folder(
folder_path: Path,
*,
- discovered: Optional[list[tuple[Path, str, Optional[float]]]] = None,
+ hf_caches: Optional[list[tuple[Path, Optional[list]]]] = None,
variant_states: Optional[download_manifest.VariantStateIndex] = None,
active_hub_cache: Optional[Path] = None,
) -> List[LocalModelInfo]:
from utils.models.model_config import detect_gguf_model
supported_formats: set[ModelFormat] = {"gguf", "safetensors", "adapter"}
+ if hf_caches is None:
+ hf_caches = [(path, None) for path in hf_cache_scan.scan_folder_hf_caches(folder_path)]
def _is_supported(m: LocalModelInfo) -> bool:
# A diffusers pipeline keeps its weights in component subdirs, so its root lands as "unknown"; judge it on its shape rather than on a format the layout cannot report.
@@ -811,14 +816,18 @@ def _scan_custom_folder(
limit = _MAX_MODELS_PER_CUSTOM_FOLDER,
entry_limit = _MAX_CUSTOM_FOLDER_ENTRIES,
)
- + _scan_hf_cache(
- folder_path,
- entry_limit = _MAX_CUSTOM_FOLDER_ENTRIES,
- active_cache = False,
- discovered = discovered,
- variant_states = variant_states,
- active_hub_cache = active_hub_cache,
- )
+ + [
+ row
+ for cache_dir, discovered in hf_caches
+ for row in _scan_hf_cache(
+ cache_dir,
+ entry_limit = _MAX_CUSTOM_FOLDER_ENTRIES,
+ active_cache = False,
+ discovered = discovered,
+ variant_states = variant_states,
+ active_hub_cache = active_hub_cache,
+ )
+ ]
+ _scan_lmstudio_dir(folder_path, entry_limit = _MAX_CUSTOM_FOLDER_ENTRIES)
)
if _is_supported(m)
diff --git a/studio/backend/hub/tests/test_model_services.py b/studio/backend/hub/tests/test_model_services.py
index 984b9299d03..064a8af8b07 100644
--- a/studio/backend/hub/tests/test_model_services.py
+++ b/studio/backend/hub/tests/test_model_services.py
@@ -1455,6 +1455,73 @@ def test_local_inventory_lists_a_hermes_dir_registered_as_a_scan_folder_once(mon
]
+def _hf_home_with_gguf(hf_home: Path) -> None:
+ repo = hf_home / "hub" / "models--Org--Model-GGUF"
+ blob = repo / "blobs" / ("a" * 64)
+ blob.parent.mkdir(parents = True)
+ blob.write_bytes(b"GGUF" + b"\x03\x00\x00\x00" + b"\x00" * 64)
+ snapshot = repo / "snapshots" / ("0" * 40)
+ snapshot.mkdir(parents = True)
+ (snapshot / "Model-Q4_K_M.gguf").symlink_to(blob)
+ (repo / "refs").mkdir()
+ (repo / "refs" / "main").write_text("0" * 40)
+
+
[email protected]("registered", [("hf_home",), ("hf_home/hub",), ("hf_home", "hf_home/hub")])
+def test_local_inventory_lists_a_registered_hf_home(monkeypatch, tmp_path, registered):
+ _hf_home_with_gguf(tmp_path / "hf_home")
+ monkeypatch.setattr(local_inventory, "note_scan_folder_scanned", lambda *_a, **_k: None)
+
+ rows = asyncio.run(
+ local_inventory._collect_models_from_default_sources(
+ tmp_path / "models",
+ tmp_path / "hf",
+ tmp_path / "legacy",
+ tmp_path / "default",
+ (),
+ (),
+ (),
+ (),
+ [{"path": str(tmp_path / path)} for path in registered],
+ )
+ )
+ rows = local_inventory._filter_and_dedupe_local_models(rows)
+
+ assert [(row.source, row.model_id) for row in rows] == [("hf_cache", "Org/Model-GGUF")]
+
+
+def test_local_inventory_checks_for_hf_home_hub_off_the_event_loop(monkeypatch, tmp_path):
+ _hf_home_with_gguf(tmp_path / "hf_home")
+ monkeypatch.setattr(local_inventory, "note_scan_folder_scanned", lambda *_a, **_k: None)
+ real = local_inventory.hf_cache_scan.scan_folder_hf_caches
+ on_loop = []
+
+ def _spy(folder):
+ try:
+ asyncio.get_running_loop()
+ on_loop.append(True)
+ except RuntimeError:
+ on_loop.append(False)
+ return real(folder)
+
+ monkeypatch.setattr(local_inventory.hf_cache_scan, "scan_folder_hf_caches", _spy)
+ asyncio.run(
+ local_inventory._collect_models_from_default_sources(
+ tmp_path / "models",
+ tmp_path / "hf",
+ tmp_path / "legacy",
+ tmp_path / "default",
+ (),
+ (),
+ (),
+ (),
+ [{"path": str(tmp_path / "hf_home")}],
+ )
+ )
+
+ assert on_loop and not any(on_loop)
+
+
def test_list_local_gguf_variants_skips_big_endian_sibling(tmp_path):
(tmp_path / "model-Q4_K_M-be.gguf").write_bytes(b"x" * 100)
(tmp_path / "model-Q4_K_M.gguf").write_bytes(b"y" * 10)
diff --git a/studio/backend/hub/utils/inventory_scan.py b/studio/backend/hub/utils/inventory_scan.py
index a63fcb16d00..82a0abc9a96 100644
--- a/studio/backend/hub/utils/inventory_scan.py
+++ b/studio/backend/hub/utils/inventory_scan.py
@@ -427,6 +427,15 @@ def _compute_all_hf_cache_scans() -> list:
return scans
+def scan_folder_hf_caches(folder: Path) -> list[Path]:
+ # A registered HF_HOME keeps its cache one level down, in hub/.
+ hub = folder / "hub"
+ try:
+ return [folder, hub] if hub.is_dir() else [folder]
+ except OSError:
+ return [folder]
+
+
def default_ref_snapshot(repo_dir: Path) -> Optional[Path]:
"""Snapshot dir that ``refs/main`` names in *repo_dir*, or ``None``. Where ``from_pretrained(repo_id)`` lands, so the repo id is safe as a load id only when this matches the snapshot the row advertises."""
ref_path = repo_dir / "refs" / "main"
diff --git a/studio/backend/routes/models.py b/studio/backend/routes/models.py
index d80ad6e1886..d44b2af12db 100644
--- a/studio/backend/routes/models.py
+++ b/studio/backend/routes/models.py
@@ -840,6 +840,7 @@ def collect_local_models(
"""
from storage.studio_db import list_scan_folders
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
sources = sources or _compat_local_inventory_sources()
@@ -876,7 +877,11 @@ def collect_local_models(
state_repositories = []
state_cache_dirs = [cache_dir for cache_dir, _active_cache in hf_sources]
- state_cache_dirs.extend(Path(folder["path"]) for folder in custom_folders)
+ 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 cache_dir in dict.fromkeys(state_cache_dirs):
try:
for repo_dir in cache_dir.glob("models--*"):
@@ -928,11 +933,15 @@ def collect_local_models(
m
for m in (
_scan_models_dir(folder_path, limit = _MAX_MODELS_PER_FOLDER)
- + _scan_hf_cache(
- folder_path,
- active_cache = False,
- variant_states = variant_states,
- )
+ + [
+ 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)
diff --git a/studio/backend/tests/test_local_model_format.py b/studio/backend/tests/test_local_model_format.py
index 4ebf1c7d8fb..7bdf9b5fd2b 100644
--- a/studio/backend/tests/test_local_model_format.py
+++ b/studio/backend/tests/test_local_model_format.py
@@ -21,6 +21,8 @@ import sys
import types
from pathlib import Path
+import pytest
+
# Keep runnable without optional logging deps (mirrors the sibling tests).
if "structlog" not in sys.modules:
@@ -244,6 +246,28 @@ def test_local_route_returns_hermes_downloads(monkeypatch, tmp_path):
assert [(m.source, Path(m.path)) for m in response.models] == [("hermes", weight)]
[email protected]("registered", [("hf_home",), ("hf_home/hub",), ("hf_home", "hf_home/hub")])
+def test_compat_inventory_lists_a_registered_hf_home(tmp_path, registered):
+ repo = tmp_path / "hf_home" / "hub" / "models--Org--Model-GGUF"
+ blob = repo / "blobs" / ("a" * 64)
+ blob.parent.mkdir(parents = True)
+ blob.write_bytes(b"GGUF" + b"\x03\x00\x00\x00" + b"\x00" * 64)
+ snapshot = repo / "snapshots" / ("0" * 40)
+ snapshot.mkdir(parents = True)
+ (snapshot / "Model-Q4_K_M.gguf").symlink_to(blob)
+ (repo / "refs").mkdir()
+ (repo / "refs" / "main").write_text("0" * 40)
+
+ rows = models_route.collect_local_models(
+ tmp_path / "models",
+ custom_folders = [{"path": str(tmp_path / path)} for path in registered],
+ sources = _empty_compat_sources(tmp_path),
+ materialize_ollama_links = False,
+ )
+
+ assert [(row.source, row.model_id) for row in rows] == [("hf_cache", "Org/Model-GGUF")]
+
+
def test_compat_inventory_preserves_ollama_tags_sharing_a_blob(tmp_path):
root = tmp_path / "ollama"
digest = "sha256-model"
diff --git a/studio/backend/tests/test_openai_auto_switch.py b/studio/backend/tests/test_openai_auto_switch.py
index dcc189f0712..8eb32b16b20 100644
--- a/studio/backend/tests/test_openai_auto_switch.py
+++ b/studio/backend/tests/test_openai_auto_switch.py
@@ -1993,7 +1993,7 @@ def test_build_index_covers_legacy_default_lmstudio_and_custom_roots(monkeypatch
monkeypatch.setattr(
studio_db, "list_scan_folders", lambda: [{"path": str(tmp_path / "custom")}]
)
- for sub in ("active", "previous", "legacy", "default", "lmstudio", "custom"):
+ for sub in ("active", "previous", "legacy", "default", "lmstudio", "custom", "custom/hub"):
(tmp_path / sub).mkdir()
resolver._build_index()
@@ -2004,6 +2004,7 @@ def test_build_index_covers_legacy_default_lmstudio_and_custom_roots(monkeypatch
assert str((tmp_path / "default").resolve()) in hf
assert str((tmp_path / "previous").resolve()) in hf
assert str((tmp_path / "custom").resolve()) in hf
+ assert str((tmp_path / "custom" / "hub").resolve()) in hf
assert str((tmp_path / "lmstudio").resolve()) in lm
diff --git a/studio/backend/tests/test_scan_folder_health.py b/studio/backend/tests/test_scan_folder_health.py
index da36ff4e73a..a748b26e981 100644
--- a/studio/backend/tests/test_scan_folder_health.py
+++ b/studio/backend/tests/test_scan_folder_health.py
@@ -806,6 +806,26 @@ def test_a_denied_hf_snapshot_commit_directory_is_not_ok(tmp_path: Path):
commit.chmod(stat.S_IRWXU)
+@requires_posix_permissions
+def test_a_denied_hf_snapshot_under_a_registered_hf_home_is_not_ok(tmp_path: Path):
+ repo = tmp_path / "hub" / "models--org--model"
+ (repo / "blobs").mkdir(parents = True)
+ (repo / "blobs" / "deadbeef").write_bytes(b"stub")
+ commit = repo / "snapshots" / ("a" * 40)
+ commit.mkdir(parents = True)
+ (commit / "config.json").write_text("{}", encoding = "utf-8")
+ commit.chmod(0o000)
+ try:
+ status, cause = probe_folder(str(tmp_path), children = True)
+ assert status == STATUS_PERMISSION_DENIED
+ assert cause == str(commit)
+
+ note_scan_folder_scanned(str(tmp_path), found = False)
+ assert scan_folder_status(str(tmp_path)) == STATUS_PERMISSION_DENIED
+ finally:
+ commit.chmod(stat.S_IRWXU)
+
+
@requires_posix_permissions
def test_the_snapshot_level_costs_nothing_on_a_plain_folder(tmp_path: Path, monkeypatch):
"""Only a directory named ``snapshots`` buys the extra level.
diff --git a/studio/backend/utils/paths/scan_folder_health.py b/studio/backend/utils/paths/scan_folder_health.py
index 5eb44eeec73..4955543fe99 100644
--- a/studio/backend/utils/paths/scan_folder_health.py
+++ b/studio/backend/utils/paths/scan_folder_health.py
@@ -29,6 +29,7 @@ _PROBE_DEPTH = 2
_PROBE_OPEN_LIMIT = 64
# A huggingface_hub cache keeps the weights only in <root>/models--org--name/snapshots/<commit>/, so refusing that directory leaves the folder looking healthy and empty at once.
_HF_SNAPSHOTS_DIR = "snapshots"
+_HF_HOME_HUB_DIR = "hub"
def _probe_dir(path: str, *, depth: int, budget: list[int]) -> tuple[str, Optional[str]]:
@@ -60,6 +61,8 @@ def _probe_dir(path: str, *, depth: int, budget: list[int]) -> tuple[str, Option
if child_depth <= 0 and name == _HF_SNAPSHOTS_DIR:
# Spend one more level here rather than raising the depth everywhere: a diffusers pipeline's component directories would otherwise burn the budget.
child_depth = 1
+ elif depth == _PROBE_DEPTH and name == _HF_HOME_HUB_DIR:
+ child_depth = depth
status, cause = _probe_dir(subdir, depth = child_depth, budget = budget)
if status == STATUS_MISSING:
# It was in the listing a moment ago and is gone now (a model being deleted, or a download renaming its temp directory), which says nothing about the folder the user registered.