Skip to content

Releases: bodaay/HuggingFaceModelDownloader

v3.0.3

30 Jan 18:59
@bodaay bodaay
v3.0.3
acc130e

Choose a tag to compare

View all tags
v3.0.3 Latest
Latest

What's Changed in v3.0.3

Features

  • add GitHub Actions for releases and Docker, update to v3.0.0 (b1cf225)
  • add revision picker for multi-branch repos and improve web UI (183603c)
  • add modern web UI with analyze, cache browser, and authentication (Phase 3.9) (2bdad97)
  • add detailed Transformers model analysis (Phase 3.3) (1170f50)
  • add smart downloader analyzer for HuggingFace repositories (9c2b5c6)
  • add list, info, and mirror commands (0253046)
  • implement HuggingFace cache structure and manifest support (e2bd0c8)

Bug Fixes

  • load cache-dir from config file for all commands (5d7960f)
  • gracefully skip symlinks on Windows (downloads still work) (179e80b)
  • use correct HuggingFace repo name in examples (TheBloke/Mistral-7B-Instruct-v0.2-GGUF) (5a8ac93)
  • use 'install' command instead of -i flag to avoid conflict with CLI's -i (interactive) (0d0b5c9)
  • don't save binary to current directory unless -i flag is used (154f542)
  • update Dockerfile to Go 1.24 for go.mod compatibility (673445d)
  • align release workflow with installer script, reorder Quick Start (29db31b)
  • WebSocket message handling for Jobs page (c16f3c0)
  • use HuggingFace cache structure for web downloads (v3 mode) (fb4bcb3)
  • minor improvements to cache structure and rebuild (d71b6ee)

Documentation

  • update installer commands (-i → install, -w → serve) (959f368)
  • add GitHub Actions status badges, update Go version to 1.24 (91ee5a2)
  • add v3.0.0 release notes (bcc6648)
  • add web UI auth example to Quick Start (63ccc14)
  • remove unverifiable speed claims from README (0bf2bd7)
  • overhaul README for v3 with screenshots and feature highlights (d821b1d)

Other Changes

  • removed duplicate mirror sync (55370ee)

Full Changelog: v2.3.4-final...v3.0.3

Assets 8
Loading

v3.0.1 - Bug Fixes

30 Jan 11:34
@bodaay bodaay
v3.0.1
2f34d27

Choose a tag to compare

View all tags
v3.0.1 - Bug Fixes

Bug Fixes

  • Windows Support: Gracefully skip symlinks on Windows (downloads still work, friendly view skipped)
  • Installer Script: Changed -i to install command to avoid conflict with CLI's -i (interactive mode)
  • Example Repos: Fixed incorrect model names in documentation (TheBloke/Mistral-7B-GGUF → TheBloke/Mistral-7B-Instruct-v0.2-GGUF)
  • Dockerfile: Updated to Go 1.24 for compatibility with go.mod

Documentation

  • Added Windows note about symlink limitations
  • Updated README with correct install and serve commands
  • Added GitHub Actions status badges

Full Changelog: v3.0.0...v3.0.1

Loading

v3.0.0 - The HuggingFace-Native Release

30 Jan 11:11
@bodaay bodaay
v3.0.0
bcc6648

Choose a tag to compare

View all tags
v3.0.0 - The HuggingFace-Native Release

Release Notes - v3.0.0

Release Date: January 2026
The HuggingFace-Native Release

Highlights

Version 3.0.0 is a major release that brings full HuggingFace CLI compatibility. Your downloads are now stored in the standard HuggingFace cache structure, making them instantly accessible to Transformers, Diffusers, and any other HuggingFace-based tools.

New Features

HuggingFace Cache Structure (Default)

Downloads now go directly to ~/.cache/huggingface/hub/ - the same location used by huggingface_hub, Transformers, and other HuggingFace tools.

# Download a model - it's immediately available to Transformers
hfdownloader download microsoft/DialoGPT-medium

# Use it directly in Python - no copying needed!
from transformers import AutoModel
model = AutoModel.from_pretrained("microsoft/DialoGPT-medium")

Dual-Layer Storage

Get the best of both worlds:

  • HuggingFace cache: Content-addressable blobs for deduplication
  • Human-readable symlinks: Easy file browsing at ~/.cache/huggingface/hub/models--{owner}--{repo}/snapshots/{revision}/

Multi-Revision Support

Download specific branches, tags, or commits:

# Download a specific branch
hfdownloader download TheBloke/Mistral-7B-GGUF --revision main

# Download a specific tag
hfdownloader download owner/repo --revision v1.0.0

Model Analysis

Understand models before downloading with the new analyze command:

hfdownloader analyze microsoft/DialoGPT-medium

Shows:

  • Model architecture and framework
  • File types and sizes
  • Quantization formats available
  • Recommended filters for your use case

Enhanced Web UI

  • Revision picker - Select branches/tags from a dropdown
  • Model analysis - Analyze before downloading
  • Cache browser - Explore your local HuggingFace cache
  • Authentication - Secure your web server with --auth-user and --auth-pass

Web Authentication

Secure your web server when exposing to networks:

hfdownloader serve --auth-user admin --auth-pass secret

Legacy Mode

Still need the old flat directory structure? Use --legacy:

hfdownloader download TheBloke/Mistral-7B-GGUF --legacy -o ./models

Docker

Docker images are now automatically published to GitHub Container Registry:

# Pull the image
docker pull ghcr.io/bodaay/huggingfacemodeldownloader:3.0.0

# Run with HuggingFace cache mount
docker run --rm -p 8080:8080 \
  -v ~/.cache/huggingface:/home/hfdownloader/.cache/huggingface \
  ghcr.io/bodaay/huggingfacemodeldownloader:3.0.0 serve

Quick Start

# Analyze a model (no download)
bash <(curl -sSL https://g.bodaay.io/hfd) analyze TheBloke/Mistral-7B-GGUF

# Download Q4_K_M quantization only
bash <(curl -sSL https://g.bodaay.io/hfd) download TheBloke/Mistral-7B-GGUF:q4_k_m

# Start web UI with authentication
bash <(curl -sSL https://g.bodaay.io/hfd) serve --auth-user admin --auth-pass secret

# Install permanently
bash <(curl -sSL https://g.bodaay.io/hfd) -i

Migration from V2

V3 uses a different storage structure by default. Your V2 downloads remain intact.

Option 1: Keep using legacy mode for existing workflows

hfdownloader download owner/repo --legacy -o ./models

Option 2: Re-download to HuggingFace cache (recommended)

# New downloads go to ~/.cache/huggingface/hub/ by default
hfdownloader download owner/repo

Breaking Changes

  • Default storage location changed: Downloads now go to ~/.cache/huggingface/hub/ instead of ./Models/
  • Directory structure changed: Uses HuggingFace blob/symlink structure instead of flat files
  • -o flag behavior changed: In V3 mode, sets HF_HOME; in legacy mode, sets direct output path

Full Changelog

New Features

  • HuggingFace cache structure as default storage
  • analyze command for model inspection
  • --revision flag for multi-branch downloads
  • Web UI revision picker
  • Web UI cache browser
  • Web UI authentication (--auth-user, --auth-pass)
  • GitHub Actions for automated releases
  • GitHub Container Registry for Docker images

Improvements

  • Dual-layer storage (blobs + symlinks)
  • Better progress display
  • Improved error messages

Legacy Support

  • --legacy flag for V2-style flat directory structure
  • Existing V2 workflows continue to work

Full Changelog: v2.3.3...v3.0.0

Loading

Release 2.3.4

13 Jan 16:52
@bodaay bodaay
2.3.4
b0ed850

Choose a tag to compare

View all tags
Release 2.3.4

Updated Build script and binaries to avoid false positive virues detection for windows builds

Loading

Release 2.3.3

01 Jan 12:28
@bodaay bodaay
2.3.3
f3eb298

Choose a tag to compare

View all tags
Release 2.3.3

🐛 Bug Fixes

Fixed: TUI/Web UI showing incorrect total file size

  • Issue: Total download size would start at 8GB, then jump to 35GB, then 214GB during download
  • Cause: plan_item events were emitted incrementally during download loop, not upfront
  • Fix: All plan_item events are now emitted immediately after scanning, before downloads start

Fixed: Settings not taking effect in Web UI

  • Issue: Changing settings (connections, max-active, retries, etc.) had no effect on downloads
  • Cause: Settings were hardcoded in multiple places; serve command was missing flags
  • Fix:
    • Added MultipartThreshold, Verify, Retries fields to server Config
    • Added --multipart-threshold, --verify, --retries flags to serve command
    • Web UI now fetches settings from server on page load (authoritative source)

Fixed: Plan API missing Excludes and Endpoint

  • Issue: Preview/plan requests didn't respect exclude patterns or custom endpoint
  • Fix: Added Excludes, AppendFilterSubdir to job and Endpoint to settings in plan handler
Loading

Release 2.3.1

31 Dec 18:28
@bodaay bodaay
2.3.1
f39f057

Choose a tag to compare

View all tags
Release 2.3.1

Release Notes - v2.3.1

Release Date: December 31, 2025

🎉 Community Features

This release incorporates contributions and suggestions from the community:

✨ New Features

🚫 Exclude Patterns (--exclude, -E)

Exclude specific files from downloads. Thanks to @jeroenkroese (#41)!

# Exclude markdown and ONNX files
hfdownloader download TheBloke/Mistral-7B-GGUF -E .md,onnx

# Exclude full precision models
hfdownloader download owner/repo -E fp16,fp32

🌍 Custom Endpoint (--endpoint)

Use HuggingFace mirrors or enterprise endpoints. Thanks to @windtail (#38)!

# Use China mirror
hfdownloader download owner/repo --endpoint https://hf-mirror.com

# Use enterprise endpoint
hfdownloader serve --endpoint https://your-enterprise.com/hf

🐳 Docker Support

Run hfdownloader in containers. Thanks to @cdeving (#50)!

# Build Docker image
docker build -t hfdownloader .

# Run CLI in container
docker run --rm -v ./models:/data hfdownloader download TheBloke/Mistral-7B-GGUF -o /data

# Run web server in container
docker run --rm -p 8080:8080 -v ./models:/data hfdownloader serve --models-dir /data/Models

📋 Changes

  • Added --exclude / -E flag to CLI download command
  • Added --endpoint flag to both download and serve commands
  • Added Excludes field to Job struct
  • Added Endpoint field to Settings struct
  • Created Dockerfile with multi-stage build
  • Updated API to support excludes in download requests
  • Updated settings endpoint to include custom endpoint config
  • Web UI: Added "Exclude" input field to Model and Dataset download forms
  • Web UI: Updated version display to v2.3.1

🙏 Acknowledgments

Special thanks to the community members whose PRs inspired these features:

Contributor PR Feature
@jeroenkroese #41 Exclude file patterns
@windtail #38 Custom HuggingFace endpoint
@cdeving #50 Docker support

Also thanks to the community for bug reports and PRs that helped identify issues in v2.3.0:

  • URL escaping fix (related to #60)
  • TUI speed improvements (related to #59)
  • API 400 fixes (related to #58)

Release Notes - v2.3.0

Release Date: December 31, 2025

🎉 Highlights

This is a major release introducing a brand new Web UI, complete project restructuring, and numerous bug fixes. The project has been reorganized into a clean, modular architecture following Go best practices.

✨ New Features

🌐 Web Interface

  • Beautiful Terminal-Noir themed Web UI for managing downloads
  • Real-time progress updates via WebSocket
  • Separate pages for downloading Models and Datasets
  • Per-file progress bars with live status updates
  • Settings management (connections, retries, verification mode)
  • Job deduplication - prevents duplicate downloads of the same repo

🚀 One-Liner Web Mode

Start the web UI instantly with:

bash <(curl -sSL https://g.bodaay.io/hfd) -w

Automatically opens your browser to http://localhost:8080

🔧 New CLI Commands

  • hfdownloader serve - Start the web server
  • hfdownloader version - Show version information
  • hfdownloader config - Manage configuration

📦 Reusable Go Package

The downloader is now available as an importable package:

import "github.com/bodaay/HuggingFaceModelDownloader/pkg/hfdownloader"

🐛 Bug Fixes

Fixed: "error: tree API failed: 400 Bad Request"

  • Repository paths with slashes (e.g., Qwen/Qwen3-0.6B) were being incorrectly URL-escaped
  • Now correctly handles repo IDs without double-escaping the slash

Fixed: TUI Speed/ETA Display Jumping Around

  • Implemented Exponential Moving Average (EMA) for smooth speed calculations
  • Added minimum time interval (50ms) before recalculating speed
  • Both per-file and overall speeds are now stable and readable

Fixed: TUI Total File Size Fluctuating

  • File totals no longer get overwritten with incorrect values during progress updates
  • Now only updates total if a valid value is provided

Fixed: Downloads Appearing Stuck

  • Removed blocking HEAD requests during repository scanning
  • Large repos (90+ files) now start downloading within seconds instead of minutes
  • Assumed LFS files support range requests (they always do on HuggingFace)

Fixed: Web UI Progress Not Updating

  • Added progressReader wrapper for real-time progress during single-file downloads
  • Progress events now use correct Downloaded field (cumulative bytes)
  • UI throttled to 10fps to prevent DOM thrashing

🏗️ Architecture Changes

Project Structure

The codebase has been completely reorganized:

├── cmd/hfdownloader/     # CLI entry point
├── internal/
│   ├── cli/              # CLI commands (Cobra)
│   ├── server/           # Web server & API
│   ├── tui/              # Terminal UI
│   └── assets/           # Embedded web assets
├── pkg/hfdownloader/     # Reusable download library
└── scripts/              # Installation scripts

Security Improvements

  • Output path is server-controlled - Cannot be changed via API or Web UI
  • Separate directories for models (./Models/) and datasets (./Datasets/)
  • Token is never logged or exposed in API responses

Testing

  • Comprehensive unit tests for JobManager, API handlers, and WebSocket
  • Integration tests for end-to-end download flows
  • Test coverage for job deduplication and cancellation

📊 Performance Improvements

Improvement Before After
Large repo scan (90+ files) 5+ minutes ~2 seconds
Progress update frequency 1 second 200ms
Speed display stability Jumpy/erratic Smooth (EMA)
Web UI responsiveness Laggy Throttled 10fps

🔄 Breaking Changes

  • Main package moved from hfdownloader/ to pkg/hfdownloader/
  • CLI now uses Cobra commands instead of flags-only
  • main.go replaced with cmd/hfdownloader/main.go
  • Old makefile replaced with build.sh

📥 Installation

One-Liner (Recommended)

# Install to /usr/local/bin
bash <(curl -sSL https://g.bodaay.io/hfd) -i

# Start Web UI
bash <(curl -sSL https://g.bodaay.io/hfd) -w

# Download a model directly
bash <(curl -sSL https://g.bodaay.io/hfd) download TheBloke/Mistral-7B-GGUF

From Source

git clone https://github.com/bodaay/HuggingFaceModelDownloader
cd HuggingFaceModelDownloader
go build -o hfdownloader ./cmd/hfdownloader

📋 Full Changelog

New Files:

  • cmd/hfdownloader/main.go - New CLI entry point
  • internal/server/* - Complete web server implementation
  • internal/assets/* - Embedded web UI (HTML/CSS/JS)
  • pkg/hfdownloader/* - Modular download library
  • build.sh - Cross-platform build script

Modified:

  • scripts/gist_gethfd.sh - Added -w flag for web mode
  • README.md - Updated documentation with web UI info
  • go.mod - Added new dependencies (Cobra, Gorilla WebSocket)

Removed:

  • hfdownloader/ - Moved to pkg/hfdownloader/
  • main.go - Replaced by cmd/hfdownloader/main.go
  • makefile - Replaced by build.sh

Contributors

windtail, jeroenkroese, and cdeving
Loading

Release 2.3.0

31 Dec 16:56
@bodaay bodaay
2.3.0
741cef1

Choose a tag to compare

View all tags
Release 2.3.0

Release Notes - v2.3.0

Release Date: December 31, 2024

🎉 Highlights

This is a major release introducing a brand new Web UI, complete project restructuring, and numerous bug fixes. The project has been reorganized into a clean, modular architecture following Go best practices.

✨ New Features

🌐 Web Interface

  • Beautiful Terminal-Noir themed Web UI for managing downloads
  • Real-time progress updates via WebSocket
  • Separate pages for downloading Models and Datasets
  • Per-file progress bars with live status updates
  • Settings management (connections, retries, verification mode)
  • Job deduplication - prevents duplicate downloads of the same repo

🚀 One-Liner Web Mode

Start the web UI instantly with:

bash <(curl -sSL https://g.bodaay.io/hfd) -w

Automatically opens your browser to http://localhost:8080

🔧 New CLI Commands

  • hfdownloader serve - Start the web server
  • hfdownloader version - Show version information
  • hfdownloader config - Manage configuration

📦 Reusable Go Package

The downloader is now available as an importable package:

import "github.com/bodaay/HuggingFaceModelDownloader/pkg/hfdownloader"

🐛 Bug Fixes

Fixed: "error: tree API failed: 400 Bad Request"

  • Repository paths with slashes (e.g., Qwen/Qwen3-0.6B) were being incorrectly URL-escaped
  • Now correctly handles repo IDs without double-escaping the slash

Fixed: TUI Speed/ETA Display Jumping Around

  • Implemented Exponential Moving Average (EMA) for smooth speed calculations
  • Added minimum time interval (50ms) before recalculating speed
  • Both per-file and overall speeds are now stable and readable

Fixed: TUI Total File Size Fluctuating

  • File totals no longer get overwritten with incorrect values during progress updates
  • Now only updates total if a valid value is provided

Fixed: Downloads Appearing Stuck

  • Removed blocking HEAD requests during repository scanning
  • Large repos (90+ files) now start downloading within seconds instead of minutes
  • Assumed LFS files support range requests (they always do on HuggingFace)

Fixed: Web UI Progress Not Updating

  • Added progressReader wrapper for real-time progress during single-file downloads
  • Progress events now use correct Downloaded field (cumulative bytes)
  • UI throttled to 10fps to prevent DOM thrashing

🏗️ Architecture Changes

Project Structure

The codebase has been completely reorganized:

├── cmd/hfdownloader/     # CLI entry point
├── internal/
│   ├── cli/              # CLI commands (Cobra)
│   ├── server/           # Web server & API
│   ├── tui/              # Terminal UI
│   └── assets/           # Embedded web assets
├── pkg/hfdownloader/     # Reusable download library
└── scripts/              # Installation scripts

Security Improvements

  • Output path is server-controlled - Cannot be changed via API or Web UI
  • Separate directories for models (./Models/) and datasets (./Datasets/)
  • Token is never logged or exposed in API responses

Testing

  • Comprehensive unit tests for JobManager, API handlers, and WebSocket
  • Integration tests for end-to-end download flows
  • Test coverage for job deduplication and cancellation

📊 Performance Improvements

Improvement Before After
Large repo scan (90+ files) 5+ minutes ~2 seconds
Progress update frequency 1 second 200ms
Speed display stability Jumpy/erratic Smooth (EMA)
Web UI responsiveness Laggy Throttled 10fps

🔄 Breaking Changes

  • Main package moved from hfdownloader/ to pkg/hfdownloader/
  • CLI now uses Cobra commands instead of flags-only
  • main.go replaced with cmd/hfdownloader/main.go
  • Old makefile replaced with build.sh

📥 Installation

One-Liner (Recommended)

# Install to /usr/local/bin
bash <(curl -sSL https://g.bodaay.io/hfd) -i

# Start Web UI
bash <(curl -sSL https://g.bodaay.io/hfd) -w

# Download a model directly
bash <(curl -sSL https://g.bodaay.io/hfd) download TheBloke/Mistral-7B-GGUF

From Source

git clone https://github.com/bodaay/HuggingFaceModelDownloader
cd HuggingFaceModelDownloader
go build -o hfdownloader ./cmd/hfdownloader

🙏 Acknowledgments

Thanks to the community for bug reports and PRs that helped identify issues:

  • URL escaping fix (related to #60)
  • TUI speed improvements (related to #59)
  • API 400 fixes (related to #58)

📋 Full Changelog

New Files:

  • cmd/hfdownloader/main.go - New CLI entry point
  • internal/server/* - Complete web server implementation
  • internal/assets/* - Embedded web UI (HTML/CSS/JS)
  • pkg/hfdownloader/* - Modular download library
  • build.sh - Cross-platform build script

Modified:

  • scripts/gist_gethfd.sh - Added -w flag for web mode
  • README.md - Updated documentation with web UI info
  • go.mod - Added new dependencies (Cobra, Gorilla WebSocket)

Removed:

  • hfdownloader/ - Moved to pkg/hfdownloader/
  • main.go - Replaced by cmd/hfdownloader/main.go
  • makefile - Replaced by build.sh
Loading

Release 2.0.0

05 Sep 16:52
@bodaay bodaay
2.0.0
1ecc173

Choose a tag to compare

View all tags
Release 2.0.0

Cleaner mental model (one download command, sensible defaults).

Filesystem‑only resume—reliable and transparent; no “state” files to corrupt.

JSON events and a TUI that looks great everywhere.

Strong cancellation story for real‑world, long‑running downloads.

Loading

Release 1.4.2

26 Oct 03:00
@bodaay bodaay
1.4.2
cbf2f5e

Choose a tag to compare

View all tags
Release 1.4.2

Forced cgo_enabled=0

Loading

Release 1.4.1

12 Oct 11:39
@bodaay bodaay
1.4.1
19f382b

Choose a tag to compare

View all tags
Release 1.4.1

fixed install and install path

Loading