# 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](https://help.sonatype.com/en/create-a-hugging-face-repository.html "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:mypassword@example.nexus.com/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. (Extended Execution Time). 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](urn:resource:component:801328) 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.