Comfy-Org / Comfy-Org/Comfy-Desktop

Feature Request: Support HF_ENDPOINT environment variable and custom Hugging Face mirror for model downloads

Open
#1,211 1 comment 3 reactions 0 assignees View on GitHub
Dominant language
TypeScript
Stars
458
Forks
59
Avg merge
22h 18m
Merged PRs (30d)
45

Description

### Is your feature request related to a problem? Please describe.

For users in regions with slow or unstable access to `huggingface.co` (e.g. mainland China), the de facto standard `HF_ENDPOINT` environment variable is universally used across the Hugging Face ecosystem to route model downloads through community mirrors like `https://hf-mirror.com`.

However, this standard convention **does not work at all** in Comfy Desktop:
- Setting `HF_ENDPOINT` in system shell configs (`.zshrc` / `.bash_profile`), has zero effect on model downloads in the app.
- Downloads triggered from the Missing Models panel or the Errors tab always connect directly to `huggingface.co`, resulting in extremely slow speeds, timeouts, or complete failures for users without direct, stable access to Hugging Face.

### Root Cause

The primary model download flow in Comfy Desktop runs entirely on the **Electron main process (Node.js + Chromium network stack)**, completely bypassing the Python backend:
1. An injected content script intercepts download clicks from the Missing Models UI
2. It passes the raw `huggingface.co` URL to the main process via IPC (`desktop2-download-model` channel)
3. The main process calls `session.downloadURL()` directly with the original, unmodified URL
4. This download path never uses the official `huggingface_hub` library, so it never reads or respects the `HF_ENDPOINT` environment variable

Python-side `HF_ENDPOINT` configurations only affect downloads initiated manually from ComfyUI-Manager's Model Manager page, which is not the default download entry for most end users.

### Describe the solution you'd like

Native support for Hugging Face mirror configuration. Two preferred implementation options:

1. **Respect the standard `HF_ENDPOINT` environment variable** (recommended, zero UI changes)
Read `process.env.HF_ENDPOINT` in the main process, and automatically replace `https://huggingface.co` with the configured mirror endpoint before initiating any model download. This is the widely adopted convention across the entire Hugging Face toolchain.

2. **Add an explicit settings option**
Add a dedicated input field in the app preferences where users can set a custom Hugging Face mirror base URL, applied globally to all download paths.

Ideally the mirror configuration should apply to **all download paths** in the application: both the Missing Models panel (Electron layer) and any Python-side model downloads.

### Temporary workaround (manual patch)

Currently this can be fixed by manually modifying the packaged `app.asar` bundle:

1. Extract the `app.asar` archive from `Comfy Desktop.app/Contents/Resources/`
2. Locate the `desktop2-download-model` IPC handler in the main process code
3. Add a URL replacement before passing the URL to `startModelDownload`:
```typescript
// Before
return startModelDownload(win, url, filename, directory, event.sender)

// After
const mirroredUrl = url.replace("https://huggingface.co", "https://hf-mirror.com")
return startModelDownload(win, mirroredUrl, filename, directory, event.sender)
```
4. Repack `app.asar` and replace the original file in the application bundle

This workaround must be reapplied after every app update, which is inconvenient and not user-friendly.

### Additional context

`hf-mirror.com` is a widely used, community-maintained Hugging Face mirror serving millions of AI developers in China. Native support for `HF_ENDPOINT` would drastically improve the out-of-box experience for users in regions with poor direct Hugging Face connectivity, without requiring users to set up system-level global proxies or manually patch the application after every update.

Thank you for considering this feature request.

Contributor guide

No contributing guide indexed for this repository

Research direction

Inspect the Electron main-process desktop2-download-model IPC handler and the startModelDownload path described in the issue. Trace how Missing Models, Errors, and Python-side downloads are initiated, beginning with the existing environment configuration. Done means a configured HF_ENDPOINT or mirror is honored by the relevant download paths without repatching app.asar.

Written by the indexing model from the issue text.

Assessment

Tech stack
electron, node.js, typescript
Domain
desktop
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
55/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.