HuggingFace Downloader

Search GGUF repositories, inspect exact file sizes, and download models straight into LlamaTray — with live trending discovery, visual model cards, smart quantization filters, HTTP Range resume support, and gated token management.

LlamaTray includes a built-in HuggingFace downloader so you can find, explore, and fetch GGUF models without leaving the application. Click the Download from HF button next to the model path field in the model section. The dialog opens in an expanded, high-contrast footprint with two tabs (Search and Manual), an inline Selection Summary Panel, and a shared download-folder row.

Search tab & Live Discovery

The 🔍 Search tab queries the HuggingFace Hub API directly:

GET https://huggingface.co/api/models?search=<query>&filter=gguf&sort=<sort>&direction=-1&limit=20
  • Live Community Trends: On initial open, the downloader automatically triggers a search sorted by trendingScore, discovering active models from the Hugging Face community without typing.
  • Sorting Options: Switch sorting on the fly between Downloads, Likes, Last Modified, and Trending using the dropdown.
  • Visual Model Cards: Model results render as two-row micro-cards showing the bold model name (with text-elision preventing truncation), publisher badge, download count (formatted with k/M suffixes), like count, and a 🔒 Gated badge for restricted models.
  • Gated Models & Token Input: For gated or private repositories (e.g., Llama 3, Gemma), enter your Hugging Face access token directly in the password-masked field. Clicking Save stores it securely to ~/.llamatray/hf_token with strict owner-only permissions (0600), and passes it as a Bearer authorization header to both metadata and download requests.

Smart GGUF Filtering & File Inspection

Selecting any model from the list loads its available files in the right-hand GGUF Files pane:

  • Tree API Inspection: File names and exact byte sizes are queried recursively via /api/models/{repo}/tree/main before initiating any download. If the Tree API is unavailable, it gracefully falls back to the metadata endpoint with parallel HEAD probes.
  • Quick Quantization Filters: Quick-filter buttons above the file list let you instantly isolate specific quantization tiers:
    • [All] — Displays every .gguf file in the repository.
    • [Q4 (Recommended)] — Isolates balanced 4-bit quantizations (Q4_K_M, Q4_K_S, IQ4_XS, etc.).
    • [Q5] — Filters 5-bit quantizations (Q5_K_M, Q5_K_S, etc.).
    • [Q8] — High-fidelity 8-bit quantizations (Q8_0).
    • [Small (Q2-Q3)] — Lightweight quantizations for resource-constrained VRAM budgets.
  • Instant Search: A dedicated file search filter lets you type any arbitrary pattern (e.g. UD-IQ3 or imatrix).
  • ⭐ Recommended Badges: Industry-standard balanced quants (Q4_K_M and Q5_K_M) are highlighted with high-contrast recommendation badges for quick decision-making.

Seamless Download Workflow

Clicking a file updates the inline Selection Summary Panel directly within the Search tab, detailing the target repository, file name, formatted size, and local destination folder. You can click Download immediately without being redirected to the Manual tab.

Manual tab

The ✏️ Manual tab provides direct text fields for HuggingFace Repo (user/repo, e.g. unsloth/Qwen3-VL-30B-A3B-Instruct-GGUF) and File Name (e.g. Qwen3-VL-30B-A3B-Instruct-UD-IQ3_XXS.gguf). Use this tab when you already have an exact repository path or want to fetch a newly created repository.

Download Engine & HTTP Range Resume

When you start a download, LlamaTray streams the file directly from:

GET https://huggingface.co/{repo}/resolve/main/{filename}
  • Resumable Downloads via .part Files: Downloads are staged into {folder}/{filename}.part. If a download is paused, cancelled, or interrupted by network dropouts, the partial file is preserved. Re-starting the download automatically sends an Range: bytes=<existing>- HTTP header, seamlessly resuming the transfer from where it stopped.
  • High-Performance Chunking & GUI Throttling: Network transfers utilize 1 MB memory buffers and a 150 ms throttled GUI progress timer. This prevents Qt UI thread lockups and keeps the entire desktop responsive even during multi-gigabit downloads.
  • Atomic Finalization: Once the download reaches 100%, the .part file is atomically renamed to {filename}.

After the Download

  • Single Model mode: The downloaded model is automatically set as the active model path in LlamaTray, logged in the console, and the command preview updates immediately.
  • Router Mode: The model lands in your router’s configured models folder, automatically updating the router’s active model list.