---
title: hf-cross-region-copy
emoji: 🤗
colorFrom: gray
colorTo: pink
sdk: gradio
sdk_version: 6.15.1
app_file: app.py
pinned: false
license: mit
short_description: Duplicate any Hugging Face repo or bucket via an HF Job
---

# hf-cross-region-copy

UI for duplicating any Hugging Face repository or bucket
([buckets](https://huggingface.co/docs/hub/storage-buckets), models, datasets,
spaces). The actual transfer runs as a
[Hugging Face Job](https://huggingface.co/docs/huggingface_hub/guides/jobs)
using the provided Hugging Face token, so users need a token with write access
and permission to run Jobs.

## Architecture

```
Gradio SDK Space                 HF Job (per request)
┌──────────────────────┐         ┌───────────────────────────┐
│ Gradio UI            │ submit  │ uv run worker.py          │
│ HF token field       │ ──────► │   --type <type>           │
│ Submit / Cancel      │         │   --src/--dst <id>        │
│ Live log viewer      │ ◄────── │                           │
└──────────────────────┘  poll   └───────────────────────────┘
```

Strategy by `--type`:

| Type      | How                                                                       | Volumes                       |
| --------- | ------------------------------------------------------------------------- | ----------------------------- |
| `bucket`  | Source + dest mounted as `Volume(type="bucket", ...)`; worker copies file by file. | source (ro) + dest (rw) |
| `model`   | Bare git fetch of branches/tags → force-push branches/tags + `git lfs push --all`. `git-xet` is enabled locally for the push phase to handle xet-backed large files. Preserves branch/tag history, LFS and xet objects. | no |
| `dataset` | Same as model.                                                            | no                            |
| `space`   | Same as model. The source's `space_sdk` is read and passed to `create_repo` (the API requires it); no other metadata is mirrored. | no |

- The Space is a stock Gradio SDK Space — no Dockerfile, no system packages.
  The user pastes a Hugging Face token; the Space uses it for destination
  creation, Job submission, polling/cancel, and git operations inside the Job.
- On submit, `app.py` creates an empty destination (name + region only, plus
  `space_sdk` for spaces because the API requires it) and picks a Job flavor
  whose ephemeral disk is large enough to hold the mirrored repo (see
  `_pick_flavor` — among the flavors that fit, the cheapest per minute is
  chosen; defaults to `2×` `used_storage` for the disk requirement).
- The worker copies the **content** plus the **git history** (commits,
  branches, tags) and LFS / xet objects.

## What gets migrated

| Item                                                                           | Migrated? | How                              |
| ------------------------------------------------------------------------------ | --------- | -------------------------------- |
| Files + branch/tag git history + LFS/xet objects                               | ✅        | Explicit fetch/push of `refs/heads/*` and `refs/tags/*` |
| Card data (tags, license, model-index, …)                                      | ✅        | Lives in the git tree            |
| Space SDK                                                                      | ✅        | Read from source — required by `create_repo` for spaces |
| Hub PR refs (`refs/pr/*`)                                                      | ❌        | Skipped intentionally; these can break smart-HTTP pack negotiation |
| Everything else (privacy, gated, hardware, variables, volumes, resource group, webhooks, secrets, …) | ❌ | Not migrated — set on the destination after duplication if needed |

## Files

- `app.py` — Gradio Space (UI + Job orchestration, including the size-based
  flavor picker for repos).
- `worker.py` — runs inside the Job; stdlib only, shells out to `git`. Installs
  `git-lfs` (via `apt-get`) and `git-xet` (binary from the `huggingface/xet-core`
  releases) at first run if missing.
- `requirements.txt` — `huggingface_hub>=1.15.0`, `gradio>=6.15.1,<7`, `trackio>=0.26.0,<0.27.0`.

## Configuration

| Env var                 | Default       | Purpose                                                                                          |
| ----------------------- | ------------- | ------------------------------------------------------------------------------------------------ |
| `JOB_FLAVOR`            | `cpu-upgrade` | Flavor used for `bucket` Jobs (repos pick their own based on `used_storage`).                    |
| `JOB_TIMEOUT`           | `2h`          | Max Job runtime.                                                                                 |
| `DISK_OVERHEAD_FACTOR`  | `2.0`         | Multiplier over the source's `used_storage` when picking a flavor for the git mirror.            |
| `TRACKIO_ENABLED`       | `1`           | Set to `0`, `false`, or `no` to disable transfer submission metrics.                             |
| `TRACKIO_PROJECT`       | `hf-cross-region-copy` | Trackio project used for transfer volume metrics grouped by destination region.         |
| `TRACKIO_SPACE_ID`      | unset         | Optional Trackio dashboard Space id for syncing metrics, e.g. `org/trackio-space`.               |
| `GIT_XET_VERSION`       | `v0.2.1`      | git-xet release tag to install inside the Job. Worker-side env.                                  |
| `HF_ENDPOINT`           | `https://huggingface.co` | Hub endpoint (worker-side; override only for testing).                                |

Configuration reference: <https://huggingface.co/docs/hub/spaces-config-reference>.