From e4b93527393786d6393cbed082a1a6128850ec3f Mon Sep 17 00:00:00 2001 From: Michelle Habonneau <83347449+Michellehbn@users.noreply.github.com> Date: Tue, 7 Jul 2026 12:42:11 +0200 Subject: [PATCH 1/3] Update models-downloading with downloading behind a proxy or firewall info --- docs/hub/models-downloading.md | 41 ++++++++++++++++++++++++++++++++++ 1 file changed, 41 insertions(+) diff --git a/docs/hub/models-downloading.md b/docs/hub/models-downloading.md index 88413edc1a..dd02a828a4 100644 --- a/docs/hub/models-downloading.md +++ b/docs/hub/models-downloading.md @@ -82,3 +82,44 @@ hf-mount start repo openai-community/gpt2 /tmp/gpt2 ``` Repos are mounted read-only. See [Mount as a Local Filesystem](./storage-buckets-access#mount-as-a-local-filesystem) for full setup details, backend options, and caching. + +## Downloading behind a proxy or firewall + +If your network restricts outbound traffic through a firewall or proxy, downloading models and datasets requires more than just `huggingface.co`. File contents are served from separate storage and CDN hostnames, and `from_pretrained` / `hf download` will fail if these are not reachable, even when `huggingface.co` itself is allowlisted. + +Allowlist the following hostnames (all over HTTPS / port 443): + +| Hostname | Purpose | +|---|---| +| `huggingface.co` | Hub API, metadata, and download redirects | +| `cas-server.xethub.hf.co` | Xet storage coordination (US) | +| `transfer.xethub.hf.co` | Xet chunk transfer (US) | +| `cas-bridge.xethub.hf.co` | Xet content delivery bridge (US) | +| `cas-server.xethub-eu.hf.co` | Xet storage coordination (EU) | +| `transfer.xethub-eu.hf.co` | Xet chunk transfer (EU) | +| `cas-bridge.xethub-eu.hf.co` | Xet content delivery bridge (EU) | +| `us.aws.cdn.hf.co` | CDN edge (AWS, US) | +| `us.gcp.cdn.hf.co` | CDN edge (GCP, US) | +| `cdn-lfs.hf.co` | LFS file content (legacy/global CDN) | +| `cdn-lfs-us-1.hf.co` | LFS file content (US CDN) | +| `cdn-lfs-eu-1.hf.co` | LFS file content (EU CDN) | +| `cdn-lfs.huggingface.co` | LFS file content (legacy) | +| `cdn-lfs-us-1.huggingface.co` | LFS file content (US, legacy) | +| `cdn-lfs-eu-1.huggingface.co` | LFS file content (EU, legacy) | + +> [!TIP] +> Downloads follow HTTP redirects from `huggingface.co` to these hostnames, so +> allowlisting `huggingface.co` alone is not sufficient. A `ReadTimeoutError` (rather than +> a connection error) partway through a download usually means the initial connection +> succeeded but a storage or CDN host is blocked. + +> [!TIP] +> If you use wildcard rules, `*.hf.co` and `*.xethub.hf.co` cover current and future +> CDN and Xet endpoints. Note that the legacy `cdn-lfs*.huggingface.co` hosts are on +> `huggingface.co`, not `hf.co`, so a `*.hf.co` wildcard does not cover them, keep +> `*.huggingface.co` allowlisted as well, or list those hosts explicitly. + +> [!WARNING] +> These hostnames may change as our storage and CDN infrastructure evolves. Where your +> security policy allows it, prefer the `*.hf.co` / `*.xethub.hf.co` / `*.huggingface.co` +> wildcards so allowlists don't break when a specific endpoint changes. From 8a0ca5dd70a6d25538776066153fd24557553888 Mon Sep 17 00:00:00 2001 From: Michelle Habonneau <83347449+Michellehbn@users.noreply.github.com> Date: Wed, 8 Jul 2026 10:32:31 +0200 Subject: [PATCH 2/3] Update models-downloading.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Addresses comments from @rajatarya 💪 --- docs/hub/models-downloading.md | 34 ++++++++++++++++++++-------------- 1 file changed, 20 insertions(+), 14 deletions(-) diff --git a/docs/hub/models-downloading.md b/docs/hub/models-downloading.md index dd02a828a4..fcc8368c20 100644 --- a/docs/hub/models-downloading.md +++ b/docs/hub/models-downloading.md @@ -92,14 +92,14 @@ Allowlist the following hostnames (all over HTTPS / port 443): | Hostname | Purpose | |---|---| | `huggingface.co` | Hub API, metadata, and download redirects | -| `cas-server.xethub.hf.co` | Xet storage coordination (US) | -| `transfer.xethub.hf.co` | Xet chunk transfer (US) | -| `cas-bridge.xethub.hf.co` | Xet content delivery bridge (US) | -| `cas-server.xethub-eu.hf.co` | Xet storage coordination (EU) | -| `transfer.xethub-eu.hf.co` | Xet chunk transfer (EU) | -| `cas-bridge.xethub-eu.hf.co` | Xet content delivery bridge (EU) | -| `us.aws.cdn.hf.co` | CDN edge (AWS, US) | -| `us.gcp.cdn.hf.co` | CDN edge (GCP, US) | +| `cas-server.xethub.hf.co` | Xet storage protocol APIs + upload (US) | +| `transfer.xethub.hf.co` | Xet storage download APIs (US) | +| `cas-bridge.xethub.hf.co` | HTTP/LFS content delivery bridge, legacy (US) | +| `cas-server.xethub-eu.hf.co` | Xet storage protocol APIs + upload (EU) | +| `transfer.xethub-eu.hf.co` | Xet storage download APIs (EU) | +| `cas-bridge.xethub-eu.hf.co` | HTTP/LFS content delivery bridge, legacy (EU) | +| `us.aws.cdn.hf.co` | CDN edge (AWS) | +| `us.gcp.cdn.hf.co` | CDN edge (GCP) | | `cdn-lfs.hf.co` | LFS file content (legacy/global CDN) | | `cdn-lfs-us-1.hf.co` | LFS file content (US CDN) | | `cdn-lfs-eu-1.hf.co` | LFS file content (EU CDN) | @@ -114,12 +114,18 @@ Allowlist the following hostnames (all over HTTPS / port 443): > succeeded but a storage or CDN host is blocked. > [!TIP] -> If you use wildcard rules, `*.hf.co` and `*.xethub.hf.co` cover current and future -> CDN and Xet endpoints. Note that the legacy `cdn-lfs*.huggingface.co` hosts are on -> `huggingface.co`, not `hf.co`, so a `*.hf.co` wildcard does not cover them, keep -> `*.huggingface.co` allowlisted as well, or list those hosts explicitly. +> Wildcard behavior depends on how your proxy matches domains. Many enterprise proxies +> treat an allowlist entry as a suffix match that covers subdomains at any depth. If yours +> does, the simplest option is to allowlist the suffixes `hf.co` and `huggingface.co` — +> these cover every current and future storage and CDN endpoint. +> +> If your proxy only supports single-label wildcards (where `*.hf.co` matches +> `cdn-lfs.hf.co` but not the deeper `us.aws.cdn.hf.co` or `cas-bridge.xethub.hf.co`), +> allowlist the explicit hostnames from the table above. Note that `*.xethub.hf.co` does +> not cover the EU hosts under `xethub-eu.hf.co`, and `*.cdn.hf.co` does not cover the +> two-label `us.aws.cdn.hf.co` / `us.gcp.cdn.hf.co`. > [!WARNING] > These hostnames may change as our storage and CDN infrastructure evolves. Where your -> security policy allows it, prefer the `*.hf.co` / `*.xethub.hf.co` / `*.huggingface.co` -> wildcards so allowlists don't break when a specific endpoint changes. +> security policy allows it, allowlist the `hf.co` and `huggingface.co` suffixes (all +> subdomains) so your rules don't break when a specific endpoint changes. From 6a9e062fcd52676befbf7f050123c9f79cb96d33 Mon Sep 17 00:00:00 2001 From: Michelle Habonneau <83347449+Michellehbn@users.noreply.github.com> Date: Wed, 8 Jul 2026 11:02:04 +0200 Subject: [PATCH 3/3] Update docs/hub/models-downloading.md Co-authored-by: Hugo Larcher --- docs/hub/models-downloading.md | 35 +++++++++++++++++----------------- 1 file changed, 18 insertions(+), 17 deletions(-) diff --git a/docs/hub/models-downloading.md b/docs/hub/models-downloading.md index fcc8368c20..b279a96e56 100644 --- a/docs/hub/models-downloading.md +++ b/docs/hub/models-downloading.md @@ -89,23 +89,24 @@ If your network restricts outbound traffic through a firewall or proxy, download Allowlist the following hostnames (all over HTTPS / port 443): -| Hostname | Purpose | -|---|---| -| `huggingface.co` | Hub API, metadata, and download redirects | -| `cas-server.xethub.hf.co` | Xet storage protocol APIs + upload (US) | -| `transfer.xethub.hf.co` | Xet storage download APIs (US) | -| `cas-bridge.xethub.hf.co` | HTTP/LFS content delivery bridge, legacy (US) | -| `cas-server.xethub-eu.hf.co` | Xet storage protocol APIs + upload (EU) | -| `transfer.xethub-eu.hf.co` | Xet storage download APIs (EU) | -| `cas-bridge.xethub-eu.hf.co` | HTTP/LFS content delivery bridge, legacy (EU) | -| `us.aws.cdn.hf.co` | CDN edge (AWS) | -| `us.gcp.cdn.hf.co` | CDN edge (GCP) | -| `cdn-lfs.hf.co` | LFS file content (legacy/global CDN) | -| `cdn-lfs-us-1.hf.co` | LFS file content (US CDN) | -| `cdn-lfs-eu-1.hf.co` | LFS file content (EU CDN) | -| `cdn-lfs.huggingface.co` | LFS file content (legacy) | -| `cdn-lfs-us-1.huggingface.co` | LFS file content (US, legacy) | -| `cdn-lfs-eu-1.huggingface.co` | LFS file content (EU, legacy) | + +| Hostname | Purpose | +|-------------------------------|-------------------------------------------| +| `huggingface.co` | Hub API, metadata, and download redirects | +| `cas-server.xethub.hf.co` | Xet storage protocol APIs + upload (US) | +| `cas-server.xethub-eu.hf.co` | Xet storage protocol APIs + upload (EU) | +| `transfer.xethub.hf.co` | Xet storage download APIs (US) | +| `transfer.xethub-eu.hf.co` | Xet storage download APIs (EU) | +| `cas-bridge.xethub.hf.co` | Bridge CDN, legacy (US) | +| `cas-bridge.xethub-eu.hf.co` | Bridge CDN, legacy (EU) | +| `us.aws.cdn.hf.co` | CDN edge (US) | +| `us.gcp.cdn.hf.co` | CDN edge (US) | +| `cdn-lfs.hf.co` | LFS CDN, legacy (global) | +| `cdn-lfs-us-1.hf.co` | LFS CDN (US) | +| `cdn-lfs-eu-1.hf.co` | LFS CDN (EU) | +| `cdn-lfs.huggingface.co` | LFS CDN, legacy (global) | +| `cdn-lfs-us-1.huggingface.co` | LFS CDN, legacy (US) | +| `cdn-lfs-eu-1.huggingface.co` | LFS CDN, legacy (EU) | > [!TIP] > Downloads follow HTTP redirects from `huggingface.co` to these hostnames, so