DOCSEARCHbyAlgolia
Submit Docs

HuggingFace Model Downloader

repository·master·Indexed 22 days ago

https://github.com/bodaay/huggingfacemodeldownloader

A high-performance CLI and Web UI tool for downloading models from the HuggingFace Hub. It features parallel chunked downloads, an interactive GGUF quantization picker, and a smart analyzer to inspect repositories. The tool supports two storage modes (HF Cache and Local Directory), mirror synchronization between machines, proxy configurations (SOCKS5, HTTP/HTTPS), and gated model access via HF_TOKEN.

Tokens
23.9K
Snippets
90
Records
104
Agent score
76%

What's inside HuggingFaceModelDownloader

  1. Configure storage modes: HF Cache vs Local Directory

    master

    The tool supports two distinct storage strategies for downloaded models.

    Mode 1: HuggingFace Cache (Default)

    Files are stored in the standard ~/.cache/huggingface/ structure. This is a dual-layer system:

    • Layer 1 (hub/): The standard content-addressed HF cache. Python libraries like transformers and diffusers find these automatically.
    • Layer 2 (models/): A human-readable view using symlinks to the blobs in Layer 1.

    Note for Windows users: Layer 2 requires Administrator or Developer Mode to create symlinks. If not enabled, files will still download to Layer 1, but the readable paths in Layer 2 won't exist.

    Mode 2: Flat Files (Local Directory)

    If you want real files in a specific folder without symlinks or blob hashes, use --local-dir. This is ideal for tools like llama.cpp or ollama, or for Windows users without elevated privileges.

    Usage

    # Default (HF Cache)
hfdownloader download TheBloke/Mistral-7B-Instruct-v0.2-GGUF

# Local directory (Flat files)
hfdownloader download TheBloke/Mistral-7B-Instruct-v0.2-GGUF --local-dir ./my-model

# Legacy syntax (identical to --local-dir)
hfdownloader download TheBloke/Mistral-7B-Instruct-v0.2-GGUF --legacy -o ./my-model
    hfdownloader download TheBloke/Mistral-7B-Instruct-v0.2-GGUF --local-dir ./my-model

  2. Understand the job status lifecycle

    master

    Jobs move through several states:

    • queued: Waiting to start.
    • running: Download in progress.
    • paused: Paused by user.
    • completed: Finished successfully.
    • failed: Error occurred.
    • cancelled: Cancelled by user.

    Lifecycle Flow: queued $\rightarrow$ running $\rightarrow$ completed / failed / cancelled / paused $\rightarrow$ (if paused) queued $\rightarrow$ running.

  3. Understand HuggingFace Cache Compatibility in v3.0

    master

    HFDownloader v3.0 uses the official HuggingFace Hub cache structure by default. This ensures full interoperability with Python libraries like transformers, diffusers, and datasets.

    Models are stored in a hub/ directory using a blob/snapshot system for deduplication, while a models/ directory provides human-readable symlinks for easy browsing.

    To change the storage location, use the following environment variables:

    • HF_HOME: Overrides the ~/.cache/huggingface root.
    • HF_HUB_CACHE: Overrides the hub/ directory specifically.
    • HF_TOKEN: Used for HuggingFace authentication.

  4. Configure proxy support

    master

    The downloader supports full proxy configurations, including SOCKS5, authentication, and CIDR bypass rules. This is useful for working behind corporate firewalls.

    Usage

    hfdownloader download meta-llama/Llama-2-7b --proxy socks5://localhost:1080
    hfdownloader download meta-llama/Llama-2-7b --proxy socks5://localhost:1080

  5. Sync model cache with Mirror Sync

    master

    Mirror Sync allows you to synchronize your model cache between different machines (e.g., Home to Office, or to a NAS/USB drive).

    Workflow

    1. Add a target: Define where you want to sync to/from.
    2. Compare: Check differences between local and target.
    3. Push/Pull: Transfer the data.

    Commands

    # Add mirror targets
hfdownloader mirror target add office /mnt/nas/hf-models
hfdownloader mirror target add usb /media/usb/hf-cache

# Compare local vs target
hfdownloader mirror diff office

# Push local cache to target
hfdownloader mirror push office

# Pull from target to local
hfdownloader mirror pull office

# Sync specific repos only using filters
hfdownloader mirror push office --filter "Llama,GGUF"

# Verify integrity after sync
hfdownloader mirror push office --verify
    hfdownloader mirror push office

  6. Configure Proxy Support via CLI or Config File

    master

    HFDownloader supports HTTP, HTTPS, SOCKS5, and SOCKS5h proxies. You can configure them via CLI flags, a configuration file, or standard environment variables.

    Priority Order:

    1. CLI flags
    2. Configuration file (~/.config/hfdownloader.yaml or ~/.config/hfdownloader.json)
    3. Environment variables (HTTP_PROXY, HTTPS_PROXY, ALL_PROXY)

    Supported Proxy Types:

    • HTTP: http://host:port
    • HTTPS: https://host:port
    • SOCKS5: socks5://host:port (TCP tunneling)
    • SOCKS5h: socks5h://host:port (DNS resolution via proxy)

    Proxy Bypass (NO_PROXY): Supports exact hostnames, domain suffixes (e.g., .internal.com), CIDR ranges (e.g., 10.0.0.0/8), and the wildcard * to bypass all proxies.

    # Basic proxy
hfdownloader download meta-llama/Llama-2-7b --proxy http://proxy.corp.com:8080

# Proxy with authentication
hfdownloader download meta-llama/Llama-2-7b \
  --proxy http://proxy.corp.com:8080 \
  --proxy-user myuser \
  --proxy-pass mypassword

# SOCKS5 proxy
hfdownloader download meta-llama/Llama-2-7b --proxy socks5://localhost:1080

# Disable environment proxy variables
hfdownloader download meta-llama/Llama-2-7b --no-env-proxy

  7. Start the Web UI Dashboard

    master

    The Web UI provides a modern interface for managing the download queue, browsing your cache, and configuring settings. It uses WebSockets for real-time progress updates.

    # Start with default settings (port 8080)
hfdownloader serve

# Custom port and address
hfdownloader serve --port 9000 --addr 0.0.0.0

# Start with authentication
hfdownloader serve --auth-user admin --auth-pass secret

# Use a mirror endpoint
hfdownloader serve --endpoint https://hf-mirror.com

  8. Download models and datasets

    master

    Use the download command to fetch models or datasets from HuggingFace.

    Common workflows:

    • Specific Quantizations: Append the quantization tag to the repo name using a colon (e.g., repo:q4_k_m).
    • Filtering: Use -F to include specific file types (e.g., safetensors) and -E to exclude patterns (e.g., .md,fp16).
    • Performance: Increase speed using -c (connections) and --max-active (concurrent downloads).
    • Resuming: If a download is interrupted, simply run the same command again to resume progress automatically.
    # Analyze → Select → Download
hfdownloader analyze TheBloke/Mistral-7B-Instruct-v0.2-GGUF
hfdownloader download TheBloke/Mistral-7B-Instruct-v0.2-GGUF:q4_k_m

# Download entire model
hfdownloader download meta-llama/Llama-3-8B-Instruct

# Download with filters and excludes
hfdownloader download owner/repo -F safetensors -E ".md,fp16"

# High-speed download
hfdownloader download owner/repo -c 16 --max-active 8

# Resume interrupted download
hfdownloader download owner/repo

  9. Start the HFDownloader Web UI server

    master

    The serve command starts a web-based interface for managing downloads.

    Options:

    • --port: Specify the port to listen on.
    • --auth-user / --auth-pass: Set credentials for protected access.
    • -t: Provide a HuggingFace token for the server session.
    • --endpoint: Use a custom endpoint (e.g., for mirroring via https://hf-mirror.com).
    # Basic server
hfdownloader serve

# Production server with auth
hfdownloader serve \
  --port 8080 \
  --auth-user admin \
  --auth-pass secure123 \
  -t hf_xxxxx

# Mirror server
hfdownloader serve --endpoint https://hf-mirror.com

  10. Analyze a Repository with Smart Repository Analyzer

    master

    Before downloading, use the analyze command to inspect a repository's structure, total size, and available quantization options (e.g., for GGUF models). This helps in choosing the right file size and quality balance.

    # Analyze a repository
hfdownloader analyze TheBloke/Llama-2-7B-GGUF

# JSON output for scripting
hfdownloader analyze TheBloke/Llama-2-7B-GGUF --json

  11. Provide a HuggingFace Token for private models

    master

    To download private or gated models from HuggingFace, you must provide a HuggingFace token. This can be done in two ways:

    1. Via Server Flag: Pass the token when starting the server using the -t flag.
    2. Via Settings API: Send a POST request to the /api/settings endpoint.

    All request and response bodies use application/json.

    hfdownloader serve -t hf_xxxxx