[CLI] Support hf:// URIs in `hf upload` and `hf download` by Wauplin · Pull Request #4297 · huggingface/huggingface_hub

Wauplin · 2026-05-29T15:27:45Z

This PR lets hf upload and hf download accept a single hf:// URI in place of the positional repo id. The URI follows the usual hf://[<TYPE>/]<ID>[@<REVISION>][/<PATH>] grammar, so the repo type, revision and (optionally) the file path are all read straight from it. This is mostly a convenience to avoid having to pass --repo-type / --revision / filename arguments.

When a URI is provided, it is the single source of truth: passing --repo-type or --revision on top of it raises an error. A path embedded in the URI can't be combined with positional filenames (download) or the path_in_repo argument (upload) either.

No breaking changes expected.

Examples

# Download a single file from a dataset at a given revision
hf download hf://datasets/HuggingFaceM4/FineVision@refs/pr/1/data/train.parquet

# Download an entire repo
hf download hf://datasets/google/fleurs

# Upload a single file to a dataset on a specific branch
hf upload hf://datasets/Wauplin/my-cool-dataset@my-branch/data/train.csv ./train.csv

# Trying to also pass --repo-type / --revision is rejected
$ hf download hf://datasets/google/fleurs --revision main
Error: '--revision' cannot be used with an 'hf://' URI ('hf://datasets/google/fleurs').

The download/upload guides and the CLI reference are updated accordingly.

Note

Low Risk
CLI-only convenience layer on existing download/upload APIs with explicit validation; default behavior for plain repo IDs is unchanged.

Overview
hf download and hf upload now accept an hf:// URI as the repo argument, encoding repo type, optional revision, and optional path in one string (e.g. hf://datasets/org/repo@branch/data/file.parquet).

When the argument starts with hf://, parse_hf_uri drives routing: single-file vs snapshot vs subfolder (trailing / preserved for downloads). --repo-type and --revision are rejected if set alongside a URI; embedded paths cannot be combined with extra positional filenames (download) or path_in_repo (upload). Bucket URIs error with a pointer to hf sync.

RepoTypeOptionalOpt replaces the default model repo type on these commands so “no --repo-type” is distinguishable from an explicit --repo-type model, which matters for URI conflict checks. Plain repo IDs still default to models when --repo-type is omitted.

Docs (CLI, download, upload guides and CLI reference) and tests cover URI examples, validation, and malformed hf:// handling via HfUriError.

^{Reviewed by Cursor Bugbot for commit 4ca3210. Bugbot is set up for automated code reviews on this repo. Configure here.}

`hf upload` and `hf download` now accept a single `hf://` URI as repo id, reading the repo type, revision and path from the URI. Passing `--repo-type` or `--revision` alongside a URI is rejected, and bucket URIs are not supported by these commands. Plain repo ids keep working as before. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Wauplin · 2026-05-29T15:30:39Z

+# Same as `RepoTypeOpt` but optional (defaults to `None` rather than `model`). Used by commands that
+# accept an `hf://` URI as repo id: a `None` default lets us tell apart "user did not pass --repo-type"
+# from "user explicitly passed --repo-type model", which is required to detect conflicts with the URI.
+RepoTypeOptionalOpt = Annotated[


this part I'll need to double-check (likely that we don't need RepoTypeOpt to default to "model" in the first place

addressed it 3071ec7

reverted in 9bf05aa, too complex to get it working without changing too many places

bot-ci-comment · 2026-05-29T15:34:15Z

The docs for this PR live here. All of your documentation changes will be reflected on that endpoint. The docs are available until 30 days after the last update.

julien-c · 2026-05-30T14:00:56Z

and this one more specifically @mishig25

julien-c · 2026-05-30T14:01:40Z

Nice call rejecting --repo-type/--revision when passing a URI

Branch on the `hf://` prefix instead of `is_hf_uri()` so a malformed URI surfaces a precise HfUriError (already formatted in cli/_errors.py) rather than silently falling through to the plain-repo-id path and failing later. Also preserve a trailing '/' from the URI path so `hf download` routes folder URIs through the subfolder download code path (e.g. `.../data/` -> `data/**`). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Wauplin · 2026-06-01T16:14:51Z

+    # `repo_id` may be a plain repo id or an `hf://` URI (e.g. `hf://datasets/my-org/my-dataset@v1.0/data/`).
+    # When a URI is provided, it is authoritative for the repo type, revision and (optionally) path in repo,
+    # so explicit `--repo-type` / `--revision` options are forbidden alongside it.
+    # We branch on the `hf://` prefix (the user's *intent*) rather than on whether the string parses as a
+    # valid URI: a malformed URI then surfaces a precise `HfUriError` (formatted globally in `cli/_errors.py`)
+    # instead of silently falling through to the plain-repo-id path and failing later with an opaque error.
+    if repo_id.startswith(constants.HF_PROTOCOL):
+        if repo_type is not None:
+            raise CLIError(f"'--repo-type' cannot be used with an 'hf://' URI ('{repo_id}').")
+        if revision is not None:
+            raise CLIError(f"'--revision' cannot be used with an 'hf://' URI ('{repo_id}').")
+        uri = parse_hf_uri(repo_id)
+        if uri.is_bucket:
+            raise CLIError("Buckets are not supported by `hf upload`. Use `hf sync` instead.")
+        repo_id, repo_type_str, revision = uri.id, uri.type, uri.revision
+        if uri.path_in_repo:
+            if path_in_repo is not None:
+                raise CLIError(
+                    f"Cannot combine a path in the hf:// URI ('{uri.path_in_repo}') with the `path_in_repo` argument ('{path_in_repo}')."
+                )
+            path_in_repo = uri.path_in_repo
+    else:
+        repo_type_str = (repo_type or RepoType.model).value


this logic is duplicated between upload and download on purpose. I first tested a factorized version but it was bloating the code / making things more complex than what they should. Hence why it's like this now. Happy to revisit in the future if it was a bad decision

Reverts: - 52efb10 better - 3b347bdf good - 4ad8936 a - 3071ec7 remove RepoTypeOptionalOpt in favor of RepoTypeOpt Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

hanouticelina

perfect!

huggingface-hub-bot · 2026-06-11T12:33:35Z

This PR has been shipped as part of the v1.19.0 release.

Wauplin commented May 29, 2026

View reviewed changes

Wauplin commented Jun 1, 2026

View reviewed changes

Wauplin requested a review from hanouticelina June 1, 2026 16:15

Wauplin marked this pull request as ready for review June 1, 2026 16:15

Wauplin and others added 6 commits June 2, 2026 10:57

remove RepoTypeOptionalOpt in favor of RepoTypeOpt

3071ec7

a

4ad8936

good

3b347fb

better

52efb10

Revert last 4 commits (down to 002a326)

9bf05aa

Reverts: - 52efb10 better - 3b347bdf good - 4ad8936 a - 3071ec7 remove RepoTypeOptionalOpt in favor of RepoTypeOpt Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Merge branch 'main' into cli-support-hf-uri-upload-download

4ca3210

hanouticelina approved these changes Jun 5, 2026

View reviewed changes

Wauplin merged commit 9fd9bce into main Jun 5, 2026
26 checks passed

Wauplin deleted the cli-support-hf-uri-upload-download branch June 5, 2026 11:23

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[CLI] Support hf:// URIs in `hf upload` and `hf download`#4297

[CLI] Support hf:// URIs in `hf upload` and `hf download`#4297
Wauplin merged 8 commits into
mainfrom
cli-support-hf-uri-upload-download

Wauplin commented May 29, 2026 •

edited by cursor Bot

Loading

Uh oh!

Wauplin May 29, 2026

Uh oh!

Wauplin Jun 2, 2026

Uh oh!

Wauplin Jun 2, 2026

Uh oh!

bot-ci-comment Bot commented May 29, 2026

Uh oh!

julien-c commented May 30, 2026

Uh oh!

julien-c commented May 30, 2026 •

edited

Loading

Uh oh!

Wauplin Jun 1, 2026

Uh oh!

hanouticelina left a comment

Uh oh!

Uh oh!

huggingface-hub-bot Bot commented Jun 11, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

Wauplin commented May 29, 2026 • edited by cursor Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Examples

Uh oh!

Wauplin May 29, 2026

Choose a reason for hiding this comment

Uh oh!

Wauplin Jun 2, 2026

Choose a reason for hiding this comment

Uh oh!

Wauplin Jun 2, 2026

Choose a reason for hiding this comment

Uh oh!

bot-ci-comment Bot commented May 29, 2026

Uh oh!

julien-c commented May 30, 2026

Uh oh!

julien-c commented May 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Wauplin Jun 1, 2026

Choose a reason for hiding this comment

Uh oh!

hanouticelina left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

huggingface-hub-bot Bot commented Jun 11, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Wauplin commented May 29, 2026 •

edited by cursor Bot

Loading

julien-c commented May 30, 2026 •

edited

Loading