From 364ad30a2ffd3b66f480851818b00099009c3543 Mon Sep 17 00:00:00 2001
From: "LocalAI [bot]" <139863280+localai-bot@users.noreply.github.com>
Date: Sun, 8 Mar 2026 09:34:44 +0100
Subject: [PATCH] feat(downloader): add HF_MIRROR environment variable support
 (#8847)

- Added HF_MIRROR env var to configure HuggingFace mirror URLs
- HF_MIRROR takes precedence over HF_ENDPOINT for simpler mirror config
- Supports both full URLs (https://hf-mirror.com) and simple hostnames (hf-mirror.com)
- Auto-adds https:// if no scheme is provided
- Also supports HF env var as an alias for HF_MIRROR

Closes #8414

Signed-off-by: localai-bot <localai-bot@users.noreply.github.com>
Co-authored-by: localai-bot <localai-bot@users.noreply.github.com>
---
 pkg/downloader/uri.go | 22 ++++++++++++++++++++++
 1 file changed, 22 insertions(+)

diff --git a/pkg/downloader/uri.go b/pkg/downloader/uri.go
index 5db5de4a1..cb8795f7e 100644
--- a/pkg/downloader/uri.go
+++ b/pkg/downloader/uri.go
@@ -42,7 +42,29 @@ type URI string
 // HF_ENDPOINT is the HuggingFace endpoint, can be overridden by setting the HF_ENDPOINT environment variable.
 var HF_ENDPOINT string = loadConfig()
 
+// loadConfig returns the HuggingFace endpoint URL.
+// It supports the following environment variables in order of precedence:
+// 1. HF_MIRROR - if set, uses this as the mirror URL (takes precedence over HF_ENDPOINT)
+// 2. HF_ENDPOINT - if set, uses this as the endpoint
+// 3. Default: https://huggingface.co
+//
+// HF_MIRROR supports both full URLs (https://hf-mirror.com) and simple hostnames (hf-mirror.com).
+// If no scheme is provided, https:// is automatically added.
 func loadConfig() string {
+	// Check for HF_MIRROR first (takes precedence)
+	HF_MIRROR := os.Getenv("HF_MIRROR")
+	if HF_MIRROR == "" {
+		HF_MIRROR = os.Getenv("HF")
+	}
+	if HF_MIRROR != "" {
+		// Normalize the mirror URL - add https:// if no scheme
+		if !strings.HasPrefix(HF_MIRROR, "http://") && !strings.HasPrefix(HF_MIRROR, "https://") {
+			HF_MIRROR = "https://" + HF_MIRROR
+		}
+		return HF_MIRROR
+	}
+
+	// Fall back to HF_ENDPOINT
 	HF_ENDPOINT := os.Getenv("HF_ENDPOINT")
 	if HF_ENDPOINT == "" {
 		HF_ENDPOINT = "https://huggingface.co"