Thumper scans three locations for model files. Each serves a different ecosystem but all are accessible through the unified model discovery system.

The HuggingFace cache uses a content-addressable structure that enables deduplication across model revisions. Understanding this structure helps with troubleshooting and manual cache management.

Directory Layout

~/.cache/huggingface/hub/
  models--stabilityai--stable-diffusion-xl-base-1.0/
    snapshots/
      462165984030d82259a11f4367a4eed129e94a7b/
        model_index.json
        unet/diffusion_pytorch_model.fp16.safetensors -> ../../blobs/abc123...
        vae/diffusion_pytorch_model.safetensors -> ../../blobs/def456...
    blobs/
      abc123...   # Actual file content (shared across snapshots)
      def456...
    refs/
      main        # Points to current snapshot hash

Key Features

• Blobs are content-addressed — identical files across revisions share storage via hard links
• Snapshots represent specific model versions (git commit hashes)
• Refs point to the latest snapshot for each branch (usually “main”)
• Repos with 0 snapshots are aborted downloads and can be safely deleted

Thumper’s discover_all_resilient() function scans all three cache locations on startup and builds a unified model index. The scan is fault-tolerant — if one location fails (e.g., permissions error), the others still complete.

How Discovery Works

• HuggingFace Cache: Uses repo-level discovery via list_cached_repos(), not individual file scan
• Ollama: Reads the manifest directory for model metadata and blob references
• Thumper Store: Scans the flat models directory for .gguf and .safetensors files
• Results are merged into a unified list with stable hash-based IDs

Stable Model IDs

Each discovered model gets a deterministic ID derived from a SHA-256 hash of its file path. This means the same model always has the same ID across process restarts, making bookmarks and favorites reliable.

If multiple users on the same machine use Thumper (or if you want to share models with other HuggingFace-based tools), you can point all instances at a shared cache.

HF_HOME Environment Variable

Set HF_HOME to a shared directory accessible by all users. All HuggingFace-based tools (Thumper, diffusers, transformers CLI) will read from and write to this shared cache.

# Add to /etc/environment or each user's .bashrc
export HF_HOME=/shared/huggingface
 
# Ensure correct permissions
sudo mkdir -p /shared/huggingface
sudo chgrp ai-users /shared/huggingface
sudo chmod 2775 /shared/huggingface

Symlink Strategies

• Thumper automatically symlinks models into app directories (e.g., ComfyUI’s checkpoints/)
• Manual symlinks work too: ln -s ~/.cache/huggingface/hub/models--org--name/snapshots/abc/model.safetensors ~/comfyui/models/checkpoints/
• Hard links save space but only work within the same filesystem

Over time, model caches can grow to hundreds of gigabytes. Thumper provides tools to identify and remove unused models.

Built-in Cleanup

• Settings → Storage shows per-location disk usage and model counts
• Automatic deletion stays disabled until Thumper can prove complete ownership and active-use state
• Aborted HuggingFace downloads (repos with 0 snapshots) are auto-detected and flagged

Manual Cleanup

For manual cleanup, use the official tools for each cache:

# HuggingFace: list and remove cached repos
huggingface-cli scan-cache
huggingface-cli delete-cache
 
# Ollama: list and remove models
ollama list
ollama rm model-name
 
# Thumper-managed models: use the app/model uninstall workflow
# Direct file deletion is not an ownership-safe cleanup method

Use this table to estimate disk requirements based on your workload. These are approximate sizes for typical model configurations.