hf cp copies files among local paths, Hub repos, and buckets
Introduced 2026-06-05 · score 0.98
HOW TO USE IT
When copying a file between a local path and Hub storage, or between supported Hub locations, use `hf cp` with the source and destination paths. Use `-` for stdin or stdout; for Hub folder copies, a trailing `/` on the source copies its contents.
hf cp ./model.safetensors hf://username/my-model/model.safetensorshf cp hf://username/my-model/config.json - | jq .hf cp hf://username/source-model/config.json hf://username/dest-model/config.jsonWHY THIS HELPS
When copying files between a local workspace and Hub storage, or between remote locations, use the unified copy command with the applicable source and destination.
REQUIREMENTS AND LIMITATIONS
- Version: v1.18.0
- SRC (required): Source: local file, `hf://` URI for a repo or bucket, or `-` for stdin.
- DST: Destination: local path, `hf://` URI for a repo or bucket, or `-` for stdout.
- --token TEXT: User Access Token; docs identify token generation at Hugging Face settings.
- trailing `/` on Hub source path: For Hub folder copies, copies the folder contents rather than nesting the folder itself.
- `-` as SRC or DST: Use `-` as source for stdin or destination for stdout.
- Remote-to-remote copies only work within the same storage region.
- Bucket-to-repo copies are not yet supported.
- Docs conflict: Current docs specify `hf cp` copies a single file when a local path is involved; whole local directories require `hf upload`/`hf download` for repos or `hf buckets sync` for buckets. The release note describes trailing-slash folder-content semantics without this local-path limitation.
FIRST-PARTY EVIDENCE
- https://github.com/huggingface/huggingface_hub/releases/tag/v1.18.0
- https://huggingface.co/docs/huggingface_hub/v1.20.1/en/guides/cli
- https://github.com/huggingface/huggingface_hub/blob/main/docs/source/en/package_reference/cli.md
Check the installed version and the source before using it. Entry JSON