HF URIs

A HF URI is a URI-like string that identifies a location on the Hugging Face Hub. Throughout the library and the CLI, hf://... strings are used to point at:

• a model, dataset, space or kernel repository (optionally pinned at a revision);
• a file or sub-folder inside such a repository;
• a bucket or a sub-folder inside a bucket.

A HF mount wraps a HF URI with a local mount path and an optional :ro / :rw flag, used by Spaces and Jobs volumes.

This page documents the canonical syntax of HF URIs and HF mounts. The same parser is used everywhere in the library, so a URI that is valid in one context (e.g. HfFileSystem) is parsed identically in another.

parse_hf_uri() also accepts Hugging Face web URLs (e.g. https://huggingface.co/datasets/my-org/my-dataset/blob/main/train.csv) so you can copy-paste a link from the website. See Web URLs below.

HF URI syntax

hf://[<TYPE>/]<ID>[@<REVISION>][/<PATH>]

HF mount syntax

hf://[<TYPE>/]<ID>[@<REVISION>][/<PATH>]:<MOUNT_PATH>[:ro|:rw]

A mount is a HF URI followed by :<MOUNT_PATH> and an optional :ro / :rw flag.

What is a HF URI

The following are all valid HF URIs:

# Models (type prefix is optional, but the id is always 'namespace/name')
hf://my-org/my-model                            # implicit type prefix
hf://models/my-org/my-model                     # explicit type prefix
hf://models/my-org/my-model/config.json         # file inside a model repo
hf://models/my-org/my-model@v1.0/config.json    # pinned to a revision

# Datasets, Spaces, Kernels (type prefix is required)
hf://datasets/my-org/my-dataset
hf://datasets/my-org/my-dataset@dev/train.csv
hf://spaces/my-user/my-space
hf://kernels/my-org/my-kernel

# Special revisions (preserved as-is)
hf://datasets/my-org/my-dataset@refs/pr/10/data.csv
hf://datasets/my-org/my-dataset@refs/convert/parquet/data.parquet

# Buckets (always 'namespace/name', no revision)
hf://buckets/my-org/my-bucket
hf://buckets/my-org/my-bucket/sub/folder

The following are valid HF mounts (volume specifications):

hf://my-org/my-model:/data
hf://datasets/my-org/my-dataset:/mnt:ro
hf://datasets/my-org/my-dataset/train:/mnt:rw    # mount a sub-folder
hf://buckets/my-org/my-bucket:/storage:rw

What is not a HF URI

The parser is strict on purpose. The following are rejected:

Web URLs

For convenience, parse_hf_uri() also accepts Hugging Face web URLs that you copy-paste from your browser. They are normalized to the canonical hf:// form, so you can paste a URL straight into the CLI or the library and “it just works”:

>>> from huggingface_hub import parse_hf_uri
>>> parse_hf_uri("https://huggingface.co/datasets/my-org/my-dataset/blob/main/train.csv")
HfUri(type='dataset', id='my-org/my-dataset', revision='main', path_in_repo='train.csv')

URLs from huggingface.co (and its hf.co short domain, the staging host, and the host of a custom HF_ENDPOINT) are recognized, with or without the https:// scheme. Query strings (?download=true) and fragments (#L10) are ignored.

Supported URL formats

The table below lists the supported routes. For brevity, only the URL path is shown (the part after the host, e.g. huggingface.co); the recognized host is implied.

The revision is taken from the single segment right after blob/resolve/raw/tree/blame. Special refs (refs/pr/N, refs/convert/...) are matched eagerly even though they contain /; any other branch/tag name containing / must be URL-encoded (feature%2Ffoo).

URLs that are not parsed

When a URL is ambiguous or does not point at a concrete Hub location, it is rejected (it is never guessed):

Paths below are again shown without the host, except for the last row where the host itself is the reason for rejection.

Rendering a web URL

HfUri.to_url() is the inverse of parsing a URL: it renders the browsable web URL for a HF URI.

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

It points at the repository / bucket landing page when no path or revision is set, at the folder viewer (/tree/<rev>) when only a revision is set, at the file viewer (/blob/<rev>/<path>, revision defaulting to main) for repository files, and at the tree route (/tree/<path>) for bucket files. Special characters in the path (spaces, #, …) are percent-encoded. Pass endpoint=... to target a custom host.

Parsing in Python

Parsing URIs

parse_hf_uri() is the centralized URI parser. It is a pure string parser (no network calls) and returns a frozen HfUri dataclass.

>>> from huggingface_hub import parse_hf_uri
>>> parse_hf_uri("hf://datasets/my-org/my-dataset@refs/pr/3/train.json")
HfUri(type='dataset', id='my-org/my-dataset', revision='refs/pr/3', path_in_repo='train.json')

HfUri is round-trippable via HfUri.to_uri(), which always emits the canonical form (with an explicit type prefix):

>>> uri = parse_hf_uri("hf://my-org/my-model@v1/config.json")
>>> uri.to_uri()
'hf://models/my-org/my-model@v1/config.json'

Use the type and id fields directly. The boolean properties is_repo and is_bucket disambiguate between repository URIs and bucket URIs when needed.

Parsing mounts

parse_hf_mount parses a mount specification (a HF URI with a local mount path and optional :ro/:rw flag) and returns a frozen HfMount dataclass. It uses parse_hf_uri() under the hood.

>>> from huggingface_hub import parse_hf_mount
>>> parse_hf_mount("hf://buckets/my-org/my-bucket/sub/dir:/mnt:ro")
HfMount(source=HfUri(type='bucket', id='my-org/my-bucket', revision=None, path_in_repo='sub/dir'), mount_path='/mnt', read_only=True)

HfMount is round-trippable via HfMount.to_uri:

>>> mount = parse_hf_mount("hf://my-org/my-model:/data:ro")
>>> mount.to_uri()
'hf://models/my-org/my-model:/data:ro'

Reference

>>> from huggingface_hub import parse_hf_uri
>>> 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'

hf://[<TYPE>/]<ID>[@<REVISION>][/<PATH>]

>>> from huggingface_hub.utils import parse_hf_uri
>>> parse_hf_uri("hf://my-org/my-model")
HfUri(type='model', id='my-org/my-model', revision=None, path_in_repo='')
>>> parse_hf_uri("hf://datasets/my-org/my-dataset@refs/pr/3/train.json")
HfUri(type='dataset', id='my-org/my-dataset', revision='refs/pr/3', path_in_repo='train.json')
>>> parse_hf_uri("https://huggingface.co/datasets/my-org/my-dataset/blob/main/train.csv")
HfUri(type='dataset', id='my-org/my-dataset', revision='main', path_in_repo='train.csv')

hf://[<TYPE>/]<ID>[@<REVISION>][/<PATH>]:<MOUNT_PATH>[:ro|:rw]

hf://[<TYPE>/]<ID>[@<REVISION>][/<PATH>]:<MOUNT_PATH>[:ro|:rw]

>>> from huggingface_hub.utils import parse_hf_mount
>>> parse_hf_mount("hf://my-org/my-model:/data:ro")
HfMount(source=HfUri(type='model', id='my-org/my-model', revision=None, path_in_repo=''), mount_path='/data', read_only=True)
>>> parse_hf_mount("hf://buckets/my-org/my-bucket/sub/dir:/mnt:rw")
HfMount(source=HfUri(type='bucket', id='my-org/my-bucket', revision=None, path_in_repo='sub/dir'), mount_path='/mnt', read_only=False)