> For the complete documentation index, see [llms.txt](https://developer.harness.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.harness.io/artifact-registry/new-to-artifact-registry/quickstart/hugging-face-quickstart.md).

# Hugging Face

{% @harness-package-selector/package-selector platforms="%5B%7B%22label%22%3A%22Docker%22%2C%22slug%22%3A%22docker%22%2C%22path%22%3A%22artifact-registry%2Fnew-to-artifact-registry%2Fquickstart%2Fdocker-quickstart%22%7D%2C%7B%22label%22%3A%22Helm%22%2C%22slug%22%3A%22helm%22%2C%22path%22%3A%22artifact-registry%2Fnew-to-artifact-registry%2Fquickstart%2Fhelm-quickstart%22%7D%2C%7B%22label%22%3A%22Helm%20HTTP%22%2C%22slug%22%3A%22helm-http%22%2C%22path%22%3A%22artifact-registry%2Fnew-to-artifact-registry%2Fquickstart%2Fhelm-http-quickstart%22%7D%2C%7B%22label%22%3A%22Generic%22%2C%22slug%22%3A%22generic%22%2C%22path%22%3A%22artifact-registry%2Fnew-to-artifact-registry%2Fquickstart%2Fgeneric-quickstart%22%7D%2C%7B%22label%22%3A%22Raw%20File%22%2C%22slug%22%3A%22raw-file%22%2C%22path%22%3A%22artifact-registry%2Fnew-to-artifact-registry%2Fquickstart%2Fraw-file-quickstart%22%7D%2C%7B%22label%22%3A%22Maven%22%2C%22slug%22%3A%22maven%22%2C%22path%22%3A%22artifact-registry%2Fnew-to-artifact-registry%2Fquickstart%2Fmaven-quickstart%22%7D%2C%7B%22label%22%3A%22Python%22%2C%22slug%22%3A%22python%22%2C%22path%22%3A%22artifact-registry%2Fnew-to-artifact-registry%2Fquickstart%2Fpython-quickstart%22%7D%2C%7B%22label%22%3A%22NPM%22%2C%22slug%22%3A%22npm%22%2C%22path%22%3A%22artifact-registry%2Fnew-to-artifact-registry%2Fquickstart%2Fnpm-quickstart%22%7D%2C%7B%22label%22%3A%22Nuget%22%2C%22slug%22%3A%22nuget%22%2C%22path%22%3A%22artifact-registry%2Fnew-to-artifact-registry%2Fquickstart%2Fnuget-quickstart%22%7D%2C%7B%22label%22%3A%22RPM%22%2C%22slug%22%3A%22rpm%22%2C%22path%22%3A%22artifact-registry%2Fnew-to-artifact-registry%2Fquickstart%2Frpm-quickstart%22%7D%2C%7B%22label%22%3A%22Debian%22%2C%22slug%22%3A%22debian%22%2C%22path%22%3A%22artifact-registry%2Fnew-to-artifact-registry%2Fquickstart%2Fdebian-quickstart%22%7D%2C%7B%22label%22%3A%22Alpine%22%2C%22slug%22%3A%22alpine%22%2C%22path%22%3A%22artifact-registry%2Fnew-to-artifact-registry%2Fquickstart%2Falpine-quickstart%22%7D%2C%7B%22label%22%3A%22Wolfi%22%2C%22slug%22%3A%22wolfi%22%2C%22path%22%3A%22artifact-registry%2Fnew-to-artifact-registry%2Fquickstart%2Fwolfi-quickstart%22%7D%2C%7B%22label%22%3A%22Cargo%22%2C%22slug%22%3A%22cargo%22%2C%22path%22%3A%22artifact-registry%2Fnew-to-artifact-registry%2Fquickstart%2Fcargo-quickstart%22%7D%2C%7B%22label%22%3A%22Conan%22%2C%22slug%22%3A%22conan%22%2C%22path%22%3A%22artifact-registry%2Fnew-to-artifact-registry%2Fquickstart%2Fconan-quickstart%22%7D%2C%7B%22label%22%3A%22Go%22%2C%22slug%22%3A%22go%22%2C%22path%22%3A%22artifact-registry%2Fnew-to-artifact-registry%2Fquickstart%2Fgo-quickstart%22%7D%2C%7B%22label%22%3A%22Hugging%20Face%22%2C%22slug%22%3A%22hugging-face%22%2C%22path%22%3A%22artifact-registry%2Fnew-to-artifact-registry%2Fquickstart%2Fhugging-face-quickstart%22%7D%2C%7B%22label%22%3A%22Conda%22%2C%22slug%22%3A%22conda%22%2C%22path%22%3A%22artifact-registry%2Fnew-to-artifact-registry%2Fquickstart%2Fconda-quickstart%22%7D%2C%7B%22label%22%3A%22Dart%22%2C%22slug%22%3A%22dart%22%2C%22path%22%3A%22artifact-registry%2Fnew-to-artifact-registry%2Fquickstart%2Fdart-quickstart%22%7D%2C%7B%22label%22%3A%22PHP%20Composer%22%2C%22slug%22%3A%22php-composer%22%2C%22path%22%3A%22artifact-registry%2Fnew-to-artifact-registry%2Fquickstart%2Fphp-composer-quickstart%22%7D%2C%7B%22label%22%3A%22Swift%22%2C%22slug%22%3A%22swift%22%2C%22path%22%3A%22artifact-registry%2Fnew-to-artifact-registry%2Fquickstart%2Fswift-quickstart%22%7D%2C%7B%22label%22%3A%22Puppet%22%2C%22slug%22%3A%22puppet%22%2C%22path%22%3A%22artifact-registry%2Fnew-to-artifact-registry%2Fquickstart%2Fpuppet-quickstart%22%7D%2C%7B%22label%22%3A%22Terraform%22%2C%22slug%22%3A%22terraform%22%2C%22path%22%3A%22artifact-registry%2Fnew-to-artifact-registry%2Fquickstart%2Fterraform-quickstart%22%7D%2C%7B%22label%22%3A%22R%20(CRAN)%22%2C%22slug%22%3A%22r-cran%22%2C%22path%22%3A%22artifact-registry%2Fnew-to-artifact-registry%2Fquickstart%2Fr-cran-quickstart%22%7D%2C%7B%22label%22%3A%22RubyGems%22%2C%22slug%22%3A%22rubygems%22%2C%22path%22%3A%22artifact-registry%2Fnew-to-artifact-registry%2Fquickstart%2Frubygems-quickstart%22%7D%5D" selectedPlatform="hugging-face" %}

### Prerequisites <a href="#prerequisites" id="prerequisites"></a>

* Install the **Hugging Face CLI** (`pip install -U huggingface_hub` gives you the `hf` command).

{% hint style="info" %}
**ADDITIONAL INFORMATION**

Depending on your environment, you may need to run addition command, go to [Hugging Face installation](https://huggingface.co/docs/huggingface_hub/en/installation) for more information.
{% endhint %}

* Access to a Harness account with permissions to create registries and generate identity tokens.

***

### Create a Hugging Face artifact registry <a href="#create-a-hugging-face-artifact-registry" id="create-a-hugging-face-artifact-registry"></a>

Start by creating a new Hugging Face registry in your Harness project.

1. Under **Registries**, click **New Artifact Registry**.
2. Select **Hugging Face** as the registry type.
3. Provide a **Registry Name**.

{% hint style="info" %}
**REGISTRY NAME CRITERIA**

Your registry name must start with a letter and can include `lowercase alphanumerics`, `_`, `.` and `-`.
{% endhint %}

4. (Optional) Add a Description and Labels.
5. Choose visibility between **Public** and **Private**.
6. Click **Create Registry**.

{% hint style="info" %}
**PRIVATE REGISTRY**

This registry will serve as your private Hugging Face registry within Harness.
{% endhint %}

{% hint style="warning" %}
**NO UPSTREAM PROXY**

Hugging Face registries do not proxy to the public Hub. If content is not present in your Harness registry, it will not automatically resolve from `huggingface.co`. Teams can switch endpoints when needed or pre-populate the registry with required artifacts. Client-side caching still applies.
{% endhint %}

***

### Configure client <a href="#configure-client" id="configure-client"></a>

#### Configure environment variables <a href="#configure-environment-variables" id="configure-environment-variables"></a>

1. Set up environment variables to connect to Harness Artifact Registry.

```bash
# Recommended timeouts for model/dataset resolution. <a href="#recommended-timeouts-for-modeldataset-resolution" id="recommended-timeouts-for-modeldataset-resolution"></a>
export HF_HUB_ETAG_TIMEOUT=86400
export HF_HUB_DOWNLOAD_TIMEOUT=86400

# Point the client at your Harness registry endpoint (example shown). <a href="#point-the-client-at-your-harness-registry-endpoint-example-shown" id="point-the-client-at-your-harness-registry-endpoint-example-shown"></a>
export HF_ENDPOINT="https://pkg.<env>.harness.io/pkg/<HARNESS_ACCOUNT_ID>/<REGISTRY_NAME>/huggingface"
```

{% hint style="info" %}
**CLIENT VERSION**

For Hugging Face client version 0.19.0 and above, this timeout setting enables model resolution via pipelines and tokenizer libraries.
{% endhint %}

#### Configure authentication <a href="#configure-authentication" id="configure-authentication"></a>

2. Click **Generate token** to generate an identity token.
3. Copy the token.
4. Set the token as an environment variable with the following command:

```bash
export HF_TOKEN="<token from step 2>"
```

#### Deploy models and datasets <a href="#deploy-models-and-datasets" id="deploy-models-and-datasets"></a>

{% tabs %}
{% tab title="Models" %}
Upload a model to Artifact Registry using the huggingface\_hub library:

```python
from huggingface_hub import HfApi
api = HfApi()
api.upload_folder(
    folder_path="<folder_name>", # local folder containing model files
    repo_id="<ARTIFACT_NAME>", # name for the model in the registry
    revision="<VERSION>", # model version (defaults to 'main')
    repo_type="model"
)
```

{% endtab %}

{% tab title="Datasets" %}
Upload a dataset to Artifact Registry using the huggingface\_hub library:

```python
from huggingface_hub import HfApi
api = HfApi()
api.upload_folder(
    folder_path="<folder_name>", # local folder containing dataset files
    repo_id="<ARTIFACT_NAME>", # name for the dataset in the registry
    revision="<VERSION>", # dataset version (defaults to 'main')
    repo_type="dataset"
)
```

{% endtab %}
{% endtabs %}

#### Resolve models and datasets <a href="#resolve-models-and-datasets" id="resolve-models-and-datasets"></a>

{% tabs %}
{% tab title="Models" %}
Download a model from Artifact Registry:

```python
from huggingface_hub import snapshot_download
snapshot_download(
    repo_id="<ARTIFACT_NAME>", revision="<VERSION>", etag_timeout=86400
)
```

{% hint style="info" %}
**MODEL RESOLUTION**

With Hugging Face client version 0.19.0+ and HF\_HUB\_ETAG\_TIMEOUT set, you can resolve models with transformers, diffusers, and other libraries.
{% endhint %}
{% endtab %}

{% tab title="Datasets" %}
Artifact Registry supports resolving models using Hugging Face dataset libraries:

```bash
from datasets import load_dataset
dataset = load_dataset("<ARTIFACT_NAME>")
```

Or download an entire dataset repository using the snapshot\_download API:

```bash
from huggingface_hub import snapshot_download
snapshot_download(
    repo_id="<ARTIFACT_NAME>", revision="<VERSION>", repo_type="dataset", etag_timeout=86400
)
```

{% hint style="warning" %}
**DATASET CACHING**

Artifact Registry fully caches only datasets hosted directly on Hugging Face, not those referencing external sources.
{% endhint %}
{% endtab %}
{% endtabs %}

### Troubleshooting <a href="#troubleshooting" id="troubleshooting"></a>

* Slow downloads or timeouts. Increase **HF\_HUB\_ETAG\_TIMEOUT** and **HF\_HUB\_DOWNLOAD\_TIMEOUT**. Verify network egress to the Harness endpoint.
* File too large. Ensure Git LFS is used automatically by the CLI; confirm the LFS filter in your repo and re-try the upload.