HuggingFace Import

This guide explains how to import models, datasets, and spaces from HuggingFace Hub into Foundry.

Before You Begin

Supported Scope

Important Notes

• One-time import: After importing, the repository is not synchronized with the original HF repository.
• Large files: Files of several GB or more can be imported, but it may take considerable time.
• Private repositories: An HF access token is required.
• Gated repositories: You must first agree to the license on the HuggingFace website.

Setting Up an HF Access Token

An HuggingFace access token is required to import private repositories.

Step 1: Generate a Token on HuggingFace

1. Go to HuggingFace Settings
2. Click New token
3. Enter a token name (e.g., "Foundry Import")
4. Select Read permission (Write is not required)
5. Click Generate token
6. Copy the generated token (starts with hf_)

Step 2: Register the Token in Foundry

1. Log in to Foundry
2. Navigate to Settings → Integrations
3. Enter the token in the HuggingFace section
4. Click Save

The token is encrypted with AES-256-GCM and stored securely.

Importing a Repository

Step 1: Go to the New Repository Page

Click + New in the top navigation bar, or navigate to the repository creation page.

Step 2: Select Repository Type

Select the type of repository you want to import:

• Model — ML model
• Dataset — Dataset
• Space — Gradio/Docker app (files only)

Step 3: Enable HuggingFace Import

Toggle on From HuggingFace to reveal the HF repository search field.

Step 4: Search for and Select an HF Repository

1. Type a repository name in the search field (e.g., llama, stable-diffusion)
2. Select the desired repository from the dropdown
3. Or enter a repo ID directly (e.g., meta-llama/Llama-2-7b)

Once selected, repository details (download count, likes, file size, etc.) will be displayed.

Step 5: Enter Foundry Repository Information

1. Repository name: The name to use within Foundry
2. Visibility: Public or Private
3. Owner: Your personal account or an organization you belong to

Step 6: Create

Click the Create button to start the import job.

Checking Import Status

You can check the import status from the repository list:

While the import is in progress, access to the repository detail page is restricted and file uploads/modifications are not allowed. All features become available once the import is complete.

In-app and email notifications are sent when the import completes or fails.

Importing via API

Python SDK

from foundry_hub import FoundryApi

api = FoundryApi(token="your_foundry_token")

# Import a repository from HuggingFace
api.create_repo(
    "myuser/my-llama",
    repo_type="model",
    from_huggingface="meta-llama/Llama-2-7b-chat-hf"
)

REST API

# Register an HF access token
curl -X PUT https://foundry.example.com/api/auth/huggingface \
  -H "Authorization: Bearer YOUR_FOUNDRY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"token": "hf_xxxxxxxxxxxx"}'

# Search for an HF repo
curl "https://foundry.example.com/api/huggingface/search?q=llama&type=model" \
  -H "Authorization: Bearer YOUR_FOUNDRY_TOKEN"

# Create a repo via HF import
curl -X POST https://foundry.example.com/api/repos/create \
  -H "Authorization: Bearer YOUR_FOUNDRY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "repo_id": "myuser/my-model",
    "repo_type": "model",
    "from_huggingface": {"repo_id": "meta-llama/Llama-2-7b"}
  }'

Frequently Asked Questions

How do I import a private HF repository?

An HF access token is required. Register the token under Settings → Integrations, and make sure the token has access permissions for the repository.

How do I import a gated repository (license agreement required)?

1. Visit the repository on the HuggingFace website
2. Click the license agreement button
3. Once accepted, the import can be started from Foundry

The import failed. What should I do?

Common causes:

• Repository not found: Verify the HF repo ID
• Access denied: Check token permissions for private repositories
• Rate limit: Wait a moment and retry
• Network error: Temporary error; retry

After a failure, you can delete the repository and create it again.

Can I cancel an import in progress?

Cancellation is not currently supported. You can delete the repository after it completes or fails.

Will the repository stay in sync with the original HF repository after import?

No. Import is a one-time operation. After importing, the repository is managed independently. Updates to the original source are not reflected in the Foundry repository.

Will the Space app run after import?

The import itself only copies files. An imported Space can be run directly using the Deploy feature in Foundry Spaces (Gradio · Docker SDK supported; Streamlit/Static are not supported).

How long does it take for large repositories?

It depends on the file size and number of files:

• Under 1 GB: A few minutes
• 1–10 GB: 10–30 minutes
• Over 10 GB: 1 hour or more

Processing happens in the background, so you can close the page.

Troubleshooting

HF access token error:

"Invalid or expired HF token"

→ The token has expired or is invalid. Generate a new token and register it again.

Access permission error:

"Access denied. Repository may be private or gated."

→ Private repository: Check token permissions
→ Gated repository: Accept the license on HuggingFace first

Network error:

"Request timeout" or "Network error"

→ This is a temporary error. Please try again after a moment.