# MLX-LM model management and Hugging Face cache lifecycle > Source-anchored research for MLX-LM model management and Hugging Face cache lifecycle. Run status: COMPLETED. Parent: [MLX-LM native service model lifecycle and release contracts](https://llms-explorer.com/tree/mlx-lm-native-service-model-lifecycle-and-release-contracts/) · 4 facets · 15 facts · page: https://llms-explorer.com/tree/mlx-lm-model-management-and-hugging-face-cache-lifecycle/ ## 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](https://github.com/ml-explore/mlx-lm/blob/main/mlx_lm/manage.py) ## 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](https://raw.githubusercontent.com/ml-explore/mlx-lm/0d4d3d04f8ab7ce4a51e7209e8615755a48ba94d/README.md) - 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](https://github.com/huggingface/huggingface_hub/blob/main/docs/source/en/guides/manage-cache.md) - 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](https://huggingface.co/docs/huggingface_hub/guides/manage-cache) ## 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](https://github.com/ml-explore/mlx-lm/blob/main/mlx_lm/manage.py) - 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](https://github.com/ml-explore/mlx-lm/blob/main/mlx_lm/manage.py) - 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](https://github.com/ml-explore/mlx-lm/blob/main/mlx_lm/manage.py) ## 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](https://github.com/ml-explore/mlx-lm/blob/main/mlx_lm/manage.py) - The Hub cache stores each model repo under a models---- 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](https://github.com/huggingface/hub-docs/blob/main/docs/hub/local-cache.md) - 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](https://github.com/ml-explore/mlx-lm/blob/main/mlx_lm/manage.py) - 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](https://github.com/ml-explore/mlx-lm/blob/main/mlx_lm/manage.py) - 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](https://huggingface.co/docs/huggingface_hub/guides/manage-cache) - 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](https://huggingface.co/docs/huggingface_hub/guides/manage-cache) - 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](https://raw.githubusercontent.com/ml-explore/mlx-lm/0d4d3d04f8ab7ce4a51e7209e8615755a48ba94d/mlx_lm/manage.py) - 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](https://raw.githubusercontent.com/ml-explore/mlx-lm/0d4d3d04f8ab7ce4a51e7209e8615755a48ba94d/mlx_lm/utils.py)