feat(hub): add copyFiles API for remote file copy between buckets and repositories

[Wauplin]

Summary

Implements the "copy files remotely" API in @huggingface/hub, porting the Python HfApi.copy_files functionality to TypeScript/JS.

This enables the "Copy to Bucket" feature on the Hub UI, allowing instant server-side file copy between buckets and from repositories to buckets.

Supported operations

Source	Destination	Mechanism
Bucket	Bucket	Server-side copy by xet hash (no data transfer)
Repo (model/dataset/space) with xet files	Bucket	Server-side copy by xet hash (no data transfer)
Repo with non-xet files (small git files)	Bucket	Download + re-upload via commit()

Not supported (yet)

• Bucket → Repo copy
• Repo → Repo copy

Features

• copyFiles() — main function, exported from @huggingface/hub
• parseHfCopyHandle() — parses hf:// handles (buckets, models, datasets, spaces, with @revision support)
• Single file and recursive folder copy
• Automatic destination path resolution (file vs directory target)
• Batched server-side copy via POST /api/buckets/{id}/batch with NDJSON copyFile operations
• Fallback download+upload path for non-xet repo files using existing commit() infrastructure

Usage

import { copyFiles } from "@huggingface/hub";

// Copy a single file between buckets
await copyFiles({
  source: "hf://buckets/my-bucket/data.bin",
  destination: "hf://buckets/other-bucket/data.bin",
  accessToken: "hf_...",
});

// Copy a folder from a bucket to another bucket
await copyFiles({
  source: "hf://buckets/my-bucket/models/",
  destination: "hf://buckets/other-bucket/backup/",
  accessToken: "hf_...",
});

// Copy from a model repo to a bucket
await copyFiles({
  source: "hf://models/username/my-model/model.safetensors",
  destination: "hf://buckets/my-bucket/",
  accessToken: "hf_...",
});

// Copy an entire dataset to a bucket
await copyFiles({
  source: "hf://datasets/username/my-dataset/",
  destination: "hf://buckets/my-bucket/datasets/",
  accessToken: "hf_...",
});

Reference

Python implementation: huggingface/huggingface_hub#3874

How to test locally

Unit tests (handle parsing)

cd packages/hub
pnpm test -- --testPathPattern copy-files

The parseHfCopyHandle unit tests run without any network access.

Integration tests (require CI Hub access)

The integration tests (copyFiles describe block) run against the CI Hub at https://hub-ci.huggingface.co. They:

1. Create temporary source/destination repos (bucket and/or model)
2. Upload test files
3. Run copyFiles
4. Verify files appear in the destination
5. Clean up repos

To run them:

cd packages/hub

# Set up test credentials (the tests use TEST_ACCESS_TOKEN from src/test/consts.ts)
pnpm test -- --testPathPattern copy-files

Manual testing

You can also test manually against the production Hub:

import { copyFiles } from "@huggingface/hub";

// Copy a public model's files to your bucket
await copyFiles({
  source: "hf://models/openai-community/gpt2",
  destination: "hf://buckets/your-username/your-bucket/models/gpt2/",
  accessToken: "hf_YOUR_TOKEN",
});

Slack Thread

  

[Wauplin]

closing in favor of @julien-c 's PR to come