Skip to main content

Configure Hugging Face with Nexus

Tip

Some files in Hugging Face model repositories may have filename extensions that do not match their actual content type. When strict content validation is enabled, Nexus Repository rejects these files. If you encounter a content type mismatch error, such as 404 Detected content type [image/png], but expected [image/jpeg], disable Strict Content Validation for the affected proxy repository.

Configure the Hugging Face client to connect to and authenticate with a Nexus Hugging Face proxy repository. Note that you must create a Hugging Face proxy repository in Nexus before configuring your Hugging Face client. Refer to Create a Hugging Face Repository for more details.

Environment Variables

Configure your Hugging Face client using environment variables to point to your Nexus repository.

Basic Configuration

export HF_ENDPOINT="http://<nexus-host>/repository/<repo-name>"

Where,

  • <nexus-host> - URL of your Nexus instance.

  • <repo-name> - Name of your Hugging Face proxy repository in Nexus.

Example:

export HF_ENDPOINT="http://example.nexus.com/repository/huggingface-proxy"

Configuration with Authentication

For repositories requiring authentication, include credentials in the URL:

export HF_ENDPOINT="http://<token>:<password>@<nexus-host>/repository/<repo-name>"

Where,

  • <token>: Your Nexus username or usertoken name code

  • <password>: Your Nexus password or usertoken pass code

  • <nexus-host>: URL of your Nexus instance

  • <repo-name>: Name of your Hugging Face proxy repository

Example:

export HF_ENDPOINT="http://myuser:[email protected]/repository/huggingface-proxy"

Sonatype recommends using usertoken name code and usertoken pass code instead of username/password. Navigate to Account → User Token → Access User Token → Authenticate to access your user token.

Timeout Configuration

Hugging Face models can be large, requiring increased timeout values.

Variable

Purpose

Recommended Value

HF_HUB_DOWNLOAD_TIMEOUT

Download timeout in seconds

120 or higher

HF_HUB_ETAG_TIMEOUT

ETag timeout in seconds

1800

Example:

export HF_HUB_DOWNLOAD_TIMEOUT=120
export HF_HUB_ETAG_TIMEOUT=1800

Retry Timeout for Large Files

You may experience timeout errors on the client side for larger models as model files are not retrieved by the client until they are cached in Nexus Repository. Retry download after a couple of minutes and increase the retry timeout:

export HF_HUB_DOWNLOAD_TIMEOUT=300

Disable Xet Support

Nexus Repository does not support Xet yet. Disable Xet when using Hugging Face clients:

export HF_HUB_DISABLE_XET=1

Python Client Configuration

For Python clients using huggingface_hub, you can pass timeout parameters directly to function calls.

snapshot_download with Timeout

from huggingface_hub import snapshot_download
snapshot_download(repo_id="microsoft/OmniParser", repo_type="model", local_dir="/Users/Documents/hugging", etag_timeout=900)

Where,

  • repo_id - Model identifier in namespace/model-name format

  • etag_timeout: Timeout in seconds for ETag operations

Transformers and Diffusers Configuration

Set timeout for transformers and diffusers libraries with custom HTTP backend:

from diffusers import StableDiffusionPipeline
from huggingface_hub import configure_http_backend
from requests.adapters import HTTPAdapter
from requests import Session
from urllib3.util.retry import Retry

timeout = 900
session = Session()
retries = Retry(total=5, backoff_factor=0.5, status_forcelist=[500, 502, 503, 504])

class TimeoutHTTPAdapter(HTTPAdapter):
    def __init__(self, *args, **kwargs):
        self.timeout = kwargs.pop("timeout", timeout)
        super().__init__(*args, **kwargs)

    def send(self, request, **kwargs):
        kwargs["timeout"] = self.timeout
        return super().send(request, **kwargs)

adapter = TimeoutHTTPAdapter(max_retries=retries, timeout=timeout)
session.mount("https://", adapter)
session.mount("http://", adapter)

def get_custom_session():
    return session

configure_http_backend(get_custom_session)
pipeline = StableDiffusionPipeline.from_pretrained("CompVis/stable-diffusion-v1-4")

Header Authorization (Alternative Method)

You can also configure authentication through base64 encoded token.

import base64
import os
from huggingface_hub import snapshot_download

base64_token = base64.b64encode("<token_user>:<token_pass>".encode('utf-8')).decode('utf-8')
headers = {"Authorization": f"Basic {base64_token}"}
model_path = snapshot_download(repo_id="repo_id", repo_type="model", endpoint=os.environ["HF_ENDPOINT"], headers=headers)

Where,

  • <token_user> - Your Nexus username or usertoken name code

  • <token_pass> - Your Nexus password or usertoken pass code

Bearer Token Authentication

Nexus Repository can issue a Hugging Face Bearer token for an authenticated Nexus user. The user must have read permission for the target Hugging Face repository. See Realms for more details.

Activate Hugging Face Bearer Token Realm

Take the following steps for self-hosted Nexus Repository:

  1. Navigate to Settings → Security → Realms.

  2. Move HuggingFace Bearer Token Realm (HuggingFaceToken) to the Active list.

  3. Select Save.

Sonatype manages security realm configuration for Sonatype Cloud deployments.

Obtain the Token

Use the following command to obtain the bearer token:

curl -u <username>:<password> \
  https://<nexus-host>/repository/<repo-name>/api/token

Where,

  • <username> - Your Nexus username

  • <password> - Your Nexus password

  • <nexus-host> - Your Nexus Repository host URL

  • <repo-name> - Name of your Hugging Face proxy repository

The response returns the Hugging Face token in the following format:

{"token":"HuggingFaceToken.<opaque>"}

Use the Token

Use Bearer token authentication for huggingface-cli login and hf auth login workflows. Paste the obtained token response when prompted or use it directly in HTTP requests.

curl -H "Authorization: Bearer HuggingFaceToken.<opaque>" \
  https://<nexus-host>/repository/<repo-name>/api/whoami-v2

Where,

  • HuggingFaceToken.<opaque> - Token returned from /api/token

  • <nexus-host> - Your Nexus Repository host URL

  • <repo-name> - Your Hugging Face repository name

Note

The /api/token endpoint is a Nexus Repository–specific convenience endpoint and has no equivalent in the Hugging Face API. As a result, scripts written for the native Hugging Face API are not directly compatible with Nexus Repository and must be modified to use the /api/token endpoint instead.