The `huggingface-cli delete-cache` command is a powerful utility within the Hugging Face CLI designed to manage and clean up the local cache used by Hugging Face libraries (Transformers, Datasets, Diffusers, etc.). This cache stores downloaded model weights, tokenizers, datasets, and other files to avoid re-downloading them repeatedly, but it can grow quite large over time.

Syntax

Explanation and Usage Examples

The `delete-cache` command allows you to selectively remove cached files based on various criteria, such as model/dataset name, path, age, size, or revision. By default, it performs a dry run, showing you what *would* be deleted without actually removing any files. You must use `--no-dry-run` to execute the deletion.

**Common Options:**

* `--model <model_id>`: Delete cache entries specifically for a given model ID (e.g., `bert-base-uncased`).

* `--dataset <dataset_id>`: Delete cache entries specifically for a given dataset ID (e.g., `glue`).

* `--path <cache_path>`: Delete cache entries located at a specific local path.

* `--revision <revision>`: Delete cache entries for a specific revision (branch name, tag name, or commit hash). Often used with `--model` or `--dataset`.

* `--force`: Skip confirmation prompt when deleting.

* `--no-dry-run`: **Crucial!** Actually delete the files. Without this, the command only shows what *would* be deleted.

* `--size-less-than <size>`: Delete files smaller than the specified size (e.g., `10MB`, `500KB`, `1GB`).

* `--size-greater-than <size>`: Delete files larger than the specified size.

* `--last-accessed-before <date>`: Delete files not accessed since the specified date (e.g., `2023-01-01`, `1 month ago`).

* `--last-accessed-after <date>`: Delete files accessed after the specified date.

* `--last-modified-before <date>`: Delete files modified before the specified date.

* `--last-modified-after <date>`: Delete files modified after the specified date.

* `--include-patterns <pattern>`: Only delete files matching the given glob pattern(s) (e.g., `*.safetensors`). Can be specified multiple times.

* `--exclude-patterns <pattern>`: Exclude files matching the given glob pattern(s) from deletion. Can be specified multiple times.

---

Usage Examples

1. **Perform a dry run to see all deletable cache entries:**

This command will list all cached files that are candidates for deletion without actually removing them.

2. **Delete the entire Hugging Face cache (use with extreme caution!):**

This will prompt you for confirmation. Add `--force` to skip the prompt.

3. **Delete cache for a specific model:**

This will delete all cached files associated with the `bert-base-uncased` model.

4. **Delete cache for a specific dataset:**

This removes all cached files for the `glue` dataset.

5. **Delete cache entries for an older revision of a model:**

If you've tested an experimental branch `v2-experimental` of a model and want to remove its cache.

6. **Delete all cached files larger than 1GB:**

Useful for freeing up disk space by removing very large models or datasets.

7. **Delete all cached files that haven't been accessed in the last 6 months:**

This helps clean up stale cache entries that are no longer actively used.

8. **Delete only `.safetensors` files from the cache that are older than a year:**

This combines multiple filters for more granular control.

9. **Delete all cached files for a model, excluding its tokenizer files:**

---

**Important Considerations:**

* **Dry Run First:** Always run `huggingface-cli delete-cache` without `--no-dry-run` initially to review what will be deleted. This prevents accidental data loss.

* **Impact:** Deleting cached files means they will need to be re-downloaded if accessed again, which can consume bandwidth and time.

* **Cache Location:** The default cache directory is typically `~/.cache/huggingface/hub` or `HF_HOME/hub`. You can inspect this directory to understand its contents.