Skip to content

fix(cookbook): scan macOS HF Library/Caches so Serve lists downloads - #5980

Draft
michaelxer wants to merge 1 commit into
odysseus-dev:devfrom
michaelxer:michaelxer/fix-macos-hf-cache-scan-5978-20260810
Draft

fix(cookbook): scan macOS HF Library/Caches so Serve lists downloads#5980
michaelxer wants to merge 1 commit into
odysseus-dev:devfrom
michaelxer:michaelxer/fix-macos-hf-cache-scan-5978-20260810

Conversation

@michaelxer

Copy link
Copy Markdown
Contributor

Summary

On macOS, Hugging Face downloads often land under ~/Library/Caches/huggingface/hub (and users may set HF_HOME to the hub directory itself). Serve's /api/model/cached scanner only looked under ~/.cache/huggingface/hub (plus a few env overrides), so freshly downloaded models never appeared in the Launch list even though the files were on disk.

This PR adds the macOS Library/Caches hub path, honors HF_HUB_CACHE, treats HF_HOME pointing at a hub directory as scannable, and also runs scan_hf for custom modelDirs that are themselves HF hub caches (models--*).

Target branch

  • This PR targets dev, not main.

Linked Issue

Fixes #5978
Related: #5507 (custom modelDirs with HF hub layout)

Type of Change

  • Bug fix (non-breaking — fixes a confirmed issue)
  • New feature (non-breaking — adds new behaviour)
  • Breaking change (changes or removes existing behaviour)
  • Refactor / cleanup (behaviour unchanged)
  • Documentation only
  • CI / tooling / configuration

What changed

In routes/cookbook_helpers.py _cached_model_scan_script:

  1. Add ~/Library/Caches/huggingface/hub to default HF cache candidates.
  2. Also read HF_HUB_CACHE.
  3. If HF_HOME is set, scan both $HF_HOME/hub and HF_HOME itself (when the env already points at a hub tree).
  4. For each custom model_dir, call scan_hf(normalize_model_dir(...)) before scan_dir(...) so hub-layout directories are listed.

How to Test

python -m pytest \
  tests/test_cookbook_helpers.py::test_cached_model_scan_includes_macos_library_caches \
  tests/test_cookbook_helpers.py::test_cached_model_scan_hf_home_pointing_at_hub_dir \
  tests/test_cookbook_helpers.py::test_cached_model_scan_model_dir_with_hf_hub_layout \
  tests/test_cookbook_helpers.py::test_cached_model_scan_uses_huggingface_cache_env \
  tests/test_cookbook_helpers.py::test_cached_model_scan_runs_additional_hf_cache \
  tests/test_cookbook_helpers.py::test_cached_model_scan_reports_plain_dir_gguf \
  -q
# 6 passed

Manual (macOS):

  1. Download a GGUF so it lives under ~/Library/Caches/huggingface/hub/models--….
  2. Open Cookbook → Launch / cached models.
  3. Confirm the model appears without needing ln -s into ~/.cache.

Checklist

  • I searched open issues and open PRs — this is not a duplicate of an open PR for Cookbook won't find cached models when downloaded on MacOS #5978.
  • This PR targets dev.
  • Changes are limited to the cache scanner + focused regression tests.
  • Full macOS app UI e2e not run on this machine (Linux VPS). Scanner behaviour is covered by unit tests that place a realistic HF hub tree under a fake HOME/Library/Caches/… path.

Visual / UI changes

None — backend scanner only.

@github-actions github-actions Bot added the ready for review Description complete — ready for maintainer review label Aug 10, 2026
@michaelxer
michaelxer force-pushed the michaelxer/fix-macos-hf-cache-scan-5978-20260810 branch 2 times, most recently from f7e5087 to c34c0e2 Compare August 11, 2026 01:11
Serve's /api/model/cached only looked under ~/.cache/huggingface/hub (plus
env overrides). On macOS, huggingface_hub/Xet often writes under
~/Library/Caches/huggingface/hub, so freshly downloaded models never
appeared in the Launch list (odysseus-dev#5978).

Also:
- honor HF_HUB_CACHE
- if HF_HOME already points at a hub directory, scan it directly
- when a custom modelDir is itself an HF hub cache (models--*), run
  scan_hf in addition to scan_dir so those entries are listed (odysseus-dev#5507)

Regression tests cover the macOS path, HF_HOME=hub, and hub-layout modelDirs.
@michaelxer
michaelxer force-pushed the michaelxer/fix-macos-hf-cache-scan-5978-20260810 branch from c34c0e2 to 8856d5c Compare August 12, 2026 17:48
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

ready for review Description complete — ready for maintainer review

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Cookbook won't find cached models when downloaded on MacOS

1 participant