MLX-LM model management and Hugging Face cache lifecycle
Parent: MLX-LM native service model lifecycle and release contracts · Published reference · snapshot 2026-10-23 · viability 3.80 / 5 (research)
↓ Facts as markdownall context files
Source-anchored research for MLX-LM model management and Hugging Face cache lifecycle. Run status: COMPLETED.
These notes link each claim to its source. Some citations identify archived research reports that are no longer hosted on this site. A published reference means the content is available; it does not certify independent review or accuracy.Read the editorial policy and follow the sources before relying on a claim.
Structure and components
- The current manager defaults its pattern to mlx and both scan and delete select entries when that substring occurs anywhere in repo.repo_id. A plain scan therefore omits cached repos whose IDs do not contain mlx. (high confidence) (verified as of 2026-10-23) [source]
How it works
- A Hugging Face model repo ID passed to an MLX-LM generation command is downloaded from the Hub when it is not already cached. Conversion writes the resulting MLX model to mlx_model by default, separate from the Hub source cache. (high confidence) (verified as of 2026-10-17) [source]
- Hugging Face revision deletion removes the selected snapshot and its refs, deletes a blob only when no remaining cached revision references it, and removes the repo cache when no revisions remain. (high confidence) (verified as of 2026-10-23) [source]
- For caches using Xet shared blobs, Hugging Face warns that older cache clients can leave shared payloads behind or delete a blob still referenced by another repository. Because mlx_lm.manage delegates deletion to the installed Hugging Face delete_revisions() helper, physical cleanup behavior depends on that runtime helper; the sources do not establish one result for every installation. (medium confidence) (verified as of 2026-10-23) [source]
Comparisons and alternatives
- `mlx_lm.manage` enumerates Hub repository revisions and delegates deletion to `delete_revisions()`, rather than exposing dedicated partial-download maintenance. Current Hugging Face documentation assigns partial-download and detached-revision cleanup to `hf cache prune`; it also says `hf cache ls` flags incomplete downloads and `hf cache rm` can remove partial files when deleting an entire repository. Revision-oriented management therefore does not imply that every repository deletion leaves .incomplete files behind. (high confidence) (verified as of 2026-10-23) [source]
- If the configured Hub cache directory does not exist, scan_cache_dir() raises CacheNotFound. Since mlx_lm.manage --scan calls it directly, a fresh install with no cache directory can fail instead of returning an empty listing; MLX-LM issue 632 reports this behavior and its maintainer says the exception is expected. (high confidence) (verified as of 2026-10-23) [source]
- For --delete, a blank response means no; only y, yes, or 1 confirms. After confirmation, MLX-LM passes every revision hash for each matched repository to HFCacheInfo.delete_revisions(), so the command removes matching repo revisions rather than selecting one file. (high confidence) (verified as of 2026-10-23) [source]
Facts and statements
- mlx_lm.manage calls huggingface_hub.scan_cache_dir() without a custom cache path. The Hub cache defaults to ~/.cache/huggingface/hub; HF_HUB_CACHE can set the cache directory directly and HF_HOME changes its parent. Hub clients using the same configuration can share those cached repo files. (high confidence) (verified as of 2026-10-23) [source]
- The Hub cache stores each model repo under a models--<org>--<repo> directory. It stores commit revisions in snapshots and branch or tag pointers in refs; snapshot files point to blobs, so unchanged files can be shared across revisions without duplicate bytes. (high confidence) (verified as of 2026-10-23) [source]
- mlx_lm.manage --delete applies the same pattern to repo IDs, displays the matching repos with their sizes and local paths, then asks for yes/no confirmation. On confirmation it processes every cached revision it found for each matched repo; a no or blank answer cancels deletion. (high confidence) (verified as of 2026-10-23) [source]
- The current implementation filters only on repo.repo_id and does not restrict repo_type. A dataset or Space whose repo ID matches the pattern can therefore appear in --scan and be selected by --delete, even though the CLI help describes models. (high confidence) (verified as of 2026-10-23) [source]
- The default Hub cache is ~/.cache/huggingface/hub, and HF_HOME or HF_HUB_CACHE can customize its location. Hugging Face describes this as a central cache shared across Hub libraries; LocalAIScope likewise notes that other Hugging Face tools on a Mac share it. Removing a matching entry through MLX therefore changes the cache used by those tools too. (high confidence) [source]
- Hub snapshots represent repository revisions and point to content-addressed blobs, which may be shared among revisions or repositories. Hugging Face distinguishes logical per-repository sizes from physical cache size, so the per-repository SIZE ON DISK shown by mlx_lm.manage --scan is not guaranteed to equal the physical space reclaimed by deletion. (high confidence) (verified as of 2026-10-23) [source]
- mlx_lm.manage --scan displays SIZE ON DISK from repo.size_on_disk_str and LOCAL PATH from repo.repo_path. --pattern performs a substring test against repo.repo_id. With --delete, ask_for_confirmation treats an empty response as no and prints "Deletion cancelled - no changes made."; if no repository matches, it prints "No models found matching pattern" with the pattern. (low confidence) (verified as of 2026-10-23) [source]
- load(..., revision=...) forwards revision to the Hub download helper for a nonlocal model. The supported revision identifier can be a branch name, tag, or commit hash. An existing local model path bypasses the Hub download, so a revision string does not select a different checkpoint within that local directory. (low confidence) (verified as of 2026-10-23) [source]
Children
- No children recorded.