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.
Python agentaichatgptdeepseekfine-tuninggemmaimage-generationllamallmllmsopenaipythonqwenreinforcement-learningself-hostedstable-diffusiontext-to-speechttsuiunsloth
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.pyindex 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_cachesfrom utils.paths import legacy_hf_cache_dir, hf_default_cache_dir, lmstudio_model_dirsfrom utils.hf_cache_settings import known_hf_hub_cachesfrom 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.pyindex 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_modelsupported_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.pyindex 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.pyindex 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.pyindex 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_foldersfrom hub.utils import gguf as gguf_utils+ from hub.utils import inventory_scan as hf_cache_scanfrom utils.models.model_config import detect_gguf_modelsources = 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(mfor 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.pyindex 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 sysimport typesfrom 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.pyindex 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(monkeypatchmonkeypatch.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(monkeypatchassert str((tmp_path / "default").resolve()) in hfassert str((tmp_path / "previous").resolve()) in hfassert str((tmp_path / "custom").resolve()) in hf+ assert str((tmp_path / "custom" / "hub").resolve()) in hfassert str((tmp_path / "lmstudio").resolve()) in lmdiff --git a/studio/backend/tests/test_scan_folder_health.py b/studio/backend/tests/test_scan_folder_health.pyindex 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_permissionsdef 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.pyindex 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, Optionif 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 = depthstatus, 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.