# URIs HF

Un *URI HF* est une chaîne de caractères de type URI qui identifie un emplacement sur le Hugging Face Hub. Tout au long de la bibliothèque et de l'interface en ligne de commande, les chaînes `hf://...` sont utilisées pour pointer vers :

- un dépôt de modèle, de jeu de données, d’espace ou de noyau (éventuellement épinglé à une révision) ;
- un fichier ou un sous-dossier à l'intérieur d'un tel dépôt ;
- un [bucket](../guides/buckets) ou un sous-dossier à l'intérieur d'un bucket.

Un *montage HF* encapsule un URI HF avec un chemin de montage local et un drapeau facultatif `:ro` / `:rw`, utilisé par les volumes de [Spaces](../guides/manage-spaces) et de [Jobs](../guides/jobs).

Cette page documente la syntaxe canonique des URI HF et des montages HF. Le même analyseur est utilisé partout dans la bibliothèque, de sorte qu'une URI valide dans un contexte (par exemple [HfFileSystem](/docs/huggingface_hub/v2.4.0/fr/package_reference/hf_file_system#huggingface_hub.HfFileSystem)) est analysée de manière identique dans un autre.

[parse_hf_uri()](/docs/huggingface_hub/v2.4.0/fr/package_reference/hf_uris#huggingface_hub.parse_hf_uri) accepte également les **URL web** de Hugging Face (par exemple `https://huggingface.co/datasets/my-org/my-dataset/blob/main/train.csv`) afin que vous puissiez copier-coller un lien depuis le site web. Consultez la section [URL web](#web-urls) ci-dessous.

## Syntaxe des URI HF

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

| Composant       | Requis | Valeurs autorisées                                                      |
| --------------- | -------- | ------------------------------------------------------------------- |
| `hf://`         | oui      | Préfixe de protocole littéral.                                            |
| `<TYPE>/`       | non       | `models/`, `datasets/`, `spaces/`, `kernels/`, `buckets/` (au pluriel). |
| `<ID>`          | oui      | `<namespace>/<name>`                                                |
| `@<REVISION>`   | non       | Branche, tag, SHA de commit ou référence spéciale (`refs/pr/N`, `refs/convert/...`). Uniquement pour les dépôts. |
| `/<PATH>`       | non       | Chemin dans le dépôt ou le bucket.                                     |

## Syntaxe de montage HF

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

Un montage est un URI HF suivi de `:<MOUNT_PATH>` et d'un drapeau facultatif `:ro` / `:rw`.

| Composant       | Requis | Valeurs autorisées                                                      |
| --------------- | -------- | ------------------------------------------------------------------- |
| `<MOUNT_PATH>`  | oui      | Chemin de montage absolu (doit commencer par `/`).                          |
| `:ro` / `:rw`   | non       | Indicateur en lecture seule / lecture-écriture.                                        |

## Qu'est-ce qu'un URI HF

Les éléments suivants sont **tous des URI HF valides** :

```text
# 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
```

Les éléments suivants sont des **montages HF valides** (spécifications de volume) :

```text
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
```

## Ce qui n'est **pas** une URI HF

L'analyseur est strict par conception. Les éléments suivants sont **rejetés** :

| URI invalide                                       | Raison                                                                  |
| ------------------------------------------------- | ----------------------------------------------------------------------- |
| `my-org/my-model`, `./local/path`                 | Préfixe `hf://` manquant et URL Hugging Face non reconnue.           |
| `hf://dataset/org/m`, `hf://model/org/m`          | Les formes de type singulier sont interdites, utilisez le pluriel (`datasets/`, ...).   |
| `hf://datasets`, `hf://buckets/`                  | Un préfixe de type seul ne constitue pas un URI valide, un `<ID>` est requis.          |
| `hf://gpt2`, `hf://datasets/squad`                | Les dépôts canoniques (sans espace de noms) ne sont pas pris en charge.                |
| `hf://buckets/single-segment`                     | Les buckets doivent toujours être au format `namespace/name`.                                |
| `hf://buckets/org/b@v1`                           | Les buckets ne prennent pas en charge un marqueur de révision.                               |
| `hf://org/m@`, `hf://datasets/foo/bar@/x`         | Révision vide après `@`.                                               |
| `hf://a/b/c@v1`                                   | Un identifiant de dépôt doit être au format `namespace/name` ; les segments supplémentaires sont des chemins.           |
| `hf://org/m:/`                                    | Le chemin de montage doit être un chemin absolu non vide.                           |

## URLs Web

Pour plus de commodité, [parse_hf_uri()](/docs/huggingface_hub/v2.4.0/fr/package_reference/hf_uris#huggingface_hub.parse_hf_uri) accepte également les URL web de Hugging Face que vous copiez-collez depuis votre navigateur. Elles sont normalisées sous la forme canonique `hf://`, ce qui vous permet de coller une URL directement dans le CLI ou la bibliothèque et « ça marche » :

```python
>>> 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')
```

Les URL issues de `huggingface.co` (ainsi que de son domaine court `hf.co`, de l’hôte de staging et de l’hôte d’un `HF_ENDPOINT` personnalisé) sont reconnues, avec ou sans le schéma `https://`. Les chaînes de requête (`?download=true`) et les fragments (`#L10`) sont ignorés.

Pour analyser une URL provenant d'un autre déploiement du Hub (par exemple un Hub auto-hébergé ou proxifié), passez son URL de base en tant que `endpoint`. Son hôte est alors reconnu en plus des hôtes par défaut, et un préfixe de chemin (par exemple `http://localhost:8080/hf`) est retiré avant l'analyse :

```python
>>> parse_hf_uri("https://hub.my-company.com/datasets/my-org/my-dataset", endpoint="https://hub.my-company.com")
HfUri(type='dataset', id='my-org/my-dataset', revision=None, path_in_repo='')
```

### Formats d'URL pris en charge

Le tableau ci-dessous répertorie les routes prises en charge. Pour des raisons de concision, seul le **chemin d’URL** est affiché (la partie située après l’hôte, par exemple `huggingface.co`) ; l’hôte reconnu est sous-entendu.

| Points vers                                                      | Chemin d'URL                                       |
| -------------------------------------------------------------- | ---------------------------------------------- |
| Dépôt de modèles                                               | `/<ns>/<name>`                                 |
| Dépôt de jeu de données (idem pour `spaces/`, `kernels/`, `models/`) | `/datasets/<ns>/<name>`                        |
| Dossier dans un dépôt, épinglé à `<rev>`                        | `/<ns>/<name>/tree/<rev>[/<path>]`             |
| Fichier dans un dépôt (route du visionneuse de fichiers)                         | `/<ns>/<name>/blob/<rev>/<path>`               |
| Fichier dans un dépôt (route de téléchargement)                            | `/<ns>/<name>/resolve/<rev>/<path>`            |
| Fichier dans un dépôt (route brute)                                 | `/<ns>/<name>/raw/<rev>/<path>`                |
| Fichier dans un dépôt (route blame)                               | `/<ns>/<name>/blame/<rev>/<path>`              |
| Seau                                                         | `/buckets/<ns>/<name>`                         |
| Fichier dans un bucket (les buckets ne sont pas versionnés)               | `/buckets/<ns>/<name>/resolve/<path>`          |
| Dossier dans un bucket                                         | `/buckets/<ns>/<name>/tree/<path>`             |

La révision est extraite du segment unique situé juste après `blob`/`resolve`/`raw`/`tree`/`blame`. Les références spéciales (`refs/pr/N`, `refs/convert/...`) sont correspondantes de manière immédiate, même si elles contiennent `/` ; tout autre nom de branche ou de tag contenant `/` doit être encodé en URL (`feature%2Ffoo`).

### Les URL qui ne sont **pas** analysées

Lorsqu’une URL est ambiguë ou ne pointe pas vers un emplacement concret du Hub, elle est **rejetée** (elle n’est jamais devinée) :

Les chemins ci-dessous sont à nouveau affichés sans l'hôte, à l'exception de la dernière ligne où l'hôte lui-même est la raison du rejet.

| Raison                                                                           | Chemin d'URL                                |
| -------------------------------------------------------------------------------- | --------------------------------------- |
| URL à segment unique : page user/org, page de liste ou dépôt canonique — ambigu. | `/<username>`                           |
| Page de liste, sans `<ns>/<name>`.                                                  | `/datasets`                             |
| Les dépôts canoniques (sans espace de noms) ne sont pas pris en charge.                         | `/gpt2`                                 |
| Emplacement de fichier/dossier (idem pour `commits`, `discussions`, `settings`, …).   | `/<ns>/<name>/commit/<rev>`             |
| Les collections ne sont pas des dépôts.                                                | `/collections/<ns>/<slug>`              |
| Host n'est pas un hôte Hugging Face reconnu.                                      | `https://example.com/<ns>/<name>`       |

## Affichage d'une URL web

[HfUri.to_url()](/docs/huggingface_hub/v2.4.0/fr/package_reference/hf_uris#huggingface_hub.HfUri.to_url) est l’inverse de l’analyse d’une URL : il génère l’URL web navigable correspondant à une URI HF.

```python
>>> 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'
```

Il pointe vers la page d’accueil du dépôt / du bucket lorsqu’aucun chemin ni révision n’est défini, vers le visualiseur de dossier (`/tree/<rev>`) lorsqu’une seule révision est définie, vers le visualiseur de fichier (`/blob/<rev>/<path>`, la révision étant par défaut `main`) pour les fichiers du dépôt, et vers la route d’arborescence (`/tree/<path>`) pour les fichiers du bucket. Les caractères spéciaux du chemin (espaces, `#`, ...) sont encodés en pourcentage. Passez `endpoint=...` pour cibler un hôte personnalisé.

## Analyse en Python

### Analyse des URI

[parse_hf_uri()](/docs/huggingface_hub/v2.4.0/fr/package_reference/hf_uris#huggingface_hub.parse_hf_uri) est le parseur de URI centralisé. Il s’agit d’un parseur de chaînes pur (aucun appel réseau) qui renvoie une dataclass [HfUri](/docs/huggingface_hub/v2.4.0/fr/package_reference/hf_uris#huggingface_hub.HfUri) figée.

```python
>>> 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](/docs/huggingface_hub/v2.4.0/fr/package_reference/hf_uris#huggingface_hub.HfUri) est réversible via [HfUri.to_uri()](/docs/huggingface_hub/v2.4.0/fr/package_reference/hf_uris#huggingface_hub.HfUri.to_uri), qui émet toujours la forme canonique (avec un préfixe de type explicite) :

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

Utilisez directement les champs `type` et `id`. Les propriétés booléennes `is_repo` et `is_bucket` permettent de distinguer les URI de dépôt des URI de bucket le cas échéant.

### Analyse des montages

`parse_hf_mount` analyse une spécification de montage (un URI HF avec un chemin de montage local et un drapeau facultatif `:ro`/`:rw`) et renvoie une dataclass `HfMount` figée. Elle utilise [parse_hf_uri()](/docs/huggingface_hub/v2.4.0/fr/package_reference/hf_uris#huggingface_hub.parse_hf_uri) en interne.

```python
>>> from huggingface_hub.utils 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` est réversible via `HfMount.to_uri` :

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

## Référence[[huggingface_hub.HfUri]]

#### huggingface_hub.HfUri[[huggingface_hub.HfUri]]

```python
huggingface_hub.HfUri(type: typing.Literal['model', 'dataset', 'space', 'kernel', 'bucket'], id: str, revision: str | None = None, path_in_repo: str = '', _raw: str | None = None)
```

[Source](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/utils/_hf_uris.py#L79)

**Paramètres :**

type (`str`) : L'un des éléments suivants : 'model', 'dataset', 'space', 'kernel' ou 'bucket'.

id (`str`) : l'identifiant du dépôt ('namespace/name', par exemple 'my-org/my-model') pour les URI de dépôt, ou l'identifiant du bucket ('namespace/name') pour les URI de bucket.

revision (`str`, *facultatif*) : La révision spécifiée après '@' dans l'URI, décodée en URL. 'None' si aucune révision n'a été spécifiée, ou pour les URI de bucket (qui ne portent jamais de révision). Les références spéciales comme 'refs/pr/10' et 'refs/convert/parquet' sont conservées telles quelles.

path_in_repo (`str`) : Le chemin à l'intérieur du dépôt ou du bucket. Chaîne vide si l'URI pointe vers la racine.

Représentation analysée d'une URI du Hugging Face Hub ('hf://...').

#### to_uri[[huggingface_hub.HfUri.to_uri]]

```python
to_uri()
```

[Source](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/utils/_hf_uris.py#L137)

Afficher l'URI sous forme de chaîne canonique 'hf://'.

Le préfixe de type est toujours écrit explicitement (par exemple 'hf://models/my-org/my-model').

#### to_url[[huggingface_hub.HfUri.to_url]]

```python
to_url(endpoint: str | None = None)
```

[Source](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/utils/_hf_uris.py#L155)

**Paramètres :**

endpoint (`str`, *facultatif*) : Point de terminaison de base à utiliser. Par défaut, 'constants.ENDPOINT' (c.-à-d. 'https://huggingface.co').

**Retourne :** `str`

l’URL du site web.

Affichez l'URI en tant qu'**URL web** Hugging Face (le type que vous ouvrez dans un navigateur).

Ceci est l'inverse de l'analyse d'une URL avec [parse_hf_uri()](/docs/huggingface_hub/v2.4.0/fr/package_reference/hf_uris#huggingface_hub.parse_hf_uri). L'URL renvoyée pointe vers :

- la page d'accueil du dépôt / du bucket lorsqu'aucun chemin ni aucune révision n'est défini ;
- l’afficheur de dossiers ('/tree/') lorsqu’une seule révision est définie ;
- le visionneuse de fichiers ('/blob//') pour les fichiers du dépôt (la révision par défaut est 'main') ;
- l'itinéraire de l'arborescence ('/tree/') pour les fichiers de bucket (les buckets ne sont pas versionnés).

Exemple :
```py
>>> 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'
```

#### huggingface_hub.parse_hf_uri[[huggingface_hub.parse_hf_uri]]

```python
huggingface_hub.parse_hf_uri(uri: str, endpoint: str | None = None)
```

**Paramètres :**

uri (`str`) : L'URI à analyser. Doit commencer par 'hf://', ou être une URL Hugging Face (par exemple 'https://huggingface.co/...').

endpoint (`str`, *facultatif*) : Un point de terminaison Hub personnalisé (par exemple, un Hub auto-hébergé ou proxifié comme 'https://hub.my-company.com' ou 'http://localhost:8080/hf'). S'il est fourni, les URL web sur ce point de terminaison sont reconnues en plus des hôtes Hugging Face par défaut. N'a aucun effet sur les URI 'hf://'.

**Retourne :** [HfUri](/docs/huggingface_hub/v2.4.0/fr/package_reference/hf_uris#huggingface_hub.HfUri)

l'URI analysée.

**Levée :** `HfUriError`

- `HfUriError` -- Si l'URI est mal formée (préfixe manquant, type invalide, identifiant manquant, route d'URL non prise en charge, etc.).

Analyser une URI du Hugging Face Hub ('hf://...') ou une URL web Hugging Face.

Une URI HF est une chaîne de caractères de type URI qui identifie un emplacement sur le Hugging Face Hub. La grammaire complète est la suivante :

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

Pour plus de commodité, les **URL web** de Hugging Face (celles que vous copiez-collez depuis le site web) sont également acceptées et normalisées sous la forme canonique 'hf://', par exemple 'https://huggingface.co/datasets/my-org/my-dataset/blob/main/train.csv'. Seules les URL non ambiguës (pages de dépôt / de bucket et routes du visualiseur de fichiers/dossiers) sont acceptées ; toute autre route est rejetée.

Voir docs/source/en/package_reference/hf_uris.md pour la spécification complète.

Exemples :
```py
>>> 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')
```

#### huggingface_hub.utils.HfMount[[huggingface_hub.utils.HfMount]]

```python
huggingface_hub.utils.HfMount(source: HfUri, mount_path: str, read_only: bool | None = None, _raw: str | None = None)
```

[Source](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/utils/_hf_uris.py#L207)

**Paramètres :**

source ([HfUri](/docs/huggingface_hub/v2.4.0/fr/package_reference/hf_uris#huggingface_hub.HfUri)) : l'URI HF analysée identifiant la ressource du Hub à monter.

mount_path (`str`) : Le chemin de montage local (commence toujours par '/').

read_only (`bool`, *facultatif*) : True si le montage se termine par ':ro', False s'il se termine par ':rw', 'None' si aucun drapeau n'a été fourni.

Un URI HF associé à un chemin de montage local et à un drapeau en lecture seule facultatif.

Utilisé par Spaces et Jobs pour décrire les montages de volumes. La syntaxe complète est :

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

#### to_uri[[huggingface_hub.utils.HfMount.to_uri]]

```python
to_uri()
```

[Source](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/utils/_hf_uris.py#L238)

Afficher le montage sous forme de chaîne « hf:// » canonique.

Exemple : 'hf://models/my-org/my-model:/data:ro'

#### huggingface_hub.utils.parse_hf_mount[[huggingface_hub.utils.parse_hf_mount]]

```python
huggingface_hub.utils.parse_hf_mount(mount_str: str)
```

[Source](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/utils/_hf_uris.py#L443)

**Paramètres :**

mount_str (`str`) : Chaîne de montage à analyser. Doit commencer par 'hf://' et contenir un segment ':'.

**Retourne :** `HfMount`

le montage analysé.

**Levée :** `HfUriError`

- `HfUriError` -- Si la chaîne de montage est mal formée (chemin de montage manquant, URI invalide, etc.).

Analyser une spécification de montage HF ('hf://...:[:ro|:rw]').

Une spécification de montage est un URI HF suivi d'un chemin de montage local et d'un drapeau facultatif en lecture seule/lecture-écriture.

La grammaire complète est :

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

Voir docs/source/en/package_reference/hf_uris.md pour la spécification complète.

Exemples :
```py
>>> 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)
```