Now that we have a single centralized parser for hf:// URIs (parse_hf_uri), this PR teaches it to also understand the web URLs you copy-paste from the website, so pasting a link straight into the CLI or the library "just works". It also adds the reverse direction: HfUri.to_url().

Allows using URLs in the CLI:

$ hf cp https://huggingface.co/nvidia/LocateAnything-3B/blob/main/config.json - | jq '.architectures'
[
  "LocateAnythingForConditionalGeneration"
]

Summary

• parse_hf_uri(...) now accepts Hugging Face web URLs (with or without scheme, http:// and https://) and normalizes them to the canonical hf:// form before reusing the exact same parsing/validation path.
• Recognized hosts: huggingface.co, hf.co, the staging host, and the host of a custom HF_ENDPOINT. Query strings (?download=true) and fragments (#L10) are dropped.
• Added HfUri.to_url(endpoint=None) — renders the browsable web URL (the inverse of parsing one).
• is_hf_uri(...) benefits for free (returns True for recognized URLs, still False for local paths).
• The parser stays strict: ambiguous or non-location URLs are rejected, never guessed.

Supported URL formats

Only the URL path is shown (the part after the host, e.g. huggingface.co); the recognized host is implied.

Special refs (refs/pr/N, refs/convert/...) are matched eagerly even though they contain /; other branch/tag names with / must be URL-encoded (feature%2Ffoo).

Deliberately rejected (ambiguous / not a Hub location)

Single-segment URLs (user/org pages, canonical repos like /gpt2), listing pages (/datasets), commit/commits/discussions/settings routes, /collections/..., and non-HF hosts. As soon as a URL is ambiguous, we don't parse it.

Examples

>>> from huggingface_hub import parse_hf_uri

>>> parse_hf_uri("https://huggingface.co/openai/gpt-oss-20b")
HfUri(type='model', id='openai/gpt-oss-20b', revision=None, path_in_repo='')

>>> parse_hf_uri("https://huggingface.co/datasets/HuggingFaceFW/fineweb/blob/main/README.md")
HfUri(type='dataset', id='HuggingFaceFW/fineweb', revision='main', path_in_repo='README.md')

>>> parse_hf_uri("https://huggingface.co/datasets/foo/bar/resolve/refs/pr/3/data/train.csv")
HfUri(type='dataset', id='foo/bar', revision='refs/pr/3', path_in_repo='data/train.csv')

>>> parse_hf_uri("https://huggingface.co/buckets/my-org/my-bucket/resolve/checkpoints/model.safetensors")
HfUri(type='bucket', id='my-org/my-bucket', revision=None, path_in_repo='checkpoints/model.safetensors')

And the reverse direction:

>>> parse_hf_uri("hf://datasets/my-org/my-dataset@v1/train.csv").to_url()
'https://huggingface.co/datasets/my-org/my-dataset/blob/v1/train.csv'

to_url() points at the repo/bucket landing page when there's no path or revision, the folder viewer (/tree/<rev>) when only a revision is set, the file viewer (/blob/<rev>/<path>, revision defaulting to main) for repo files, and the tree route (/tree/<path>) for bucket files (buckets are not versioned).

Notes / decisions

• I implemented URL support by normalizing URLs into the canonical hf:// body and feeding it back through the existing parser, so all validation (repo id, revision splitting, empty-segment checks, special refs) is shared between the two entry points — no duplicated logic.
• URL formats were cross-checked against the Hub server router (moon-landing server.ts).
• Edge case: a canonical-repo file URL like .../datasets/squad/blob/main/file.json reads squad/blob as the id and is then rejected ("unsupported route"). Still rejected — canonical repos aren't supported anyway.

Tests & docs

• Added URL_SUCCESS_CASES, URL_FAILURE_CASES and TO_URL_CASES (+ tests) to tests/test_utils_hf_uris.py.
• Updated docs/source/en/package_reference/hf_uris.md with "Web URLs" (supported + rejected tables) and "Rendering a web URL" sections.

🤖 Generated with Claude Code