# Téléchargement de fichiers

## Télécharger un fichier unique

### hf_hub_download[[huggingface_hub.hf_hub_download]]

#### huggingface_hub.hf_hub_download[[huggingface_hub.hf_hub_download]]

```python
huggingface_hub.hf_hub_download(repo_id: str, filename: str, subfolder: str | None = None, repo_type: str | None = None, revision: str | None = None, library_name: str | None = None, library_version: str | None = None, cache_dir: str | pathlib.Path | None = None, local_dir: str | pathlib.Path | None = None, user_agent: dict | str | None = None, force_download: bool = False, etag_timeout: float = 10, token: bool | str | None = None, local_files_only: bool = False, headers: dict[str, str] | None = None, endpoint: str | None = None, tqdm_class: type[tqdm.std.tqdm] | None = None, dry_run: bool = False)
```

[Source](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/file_download.py#L855)

**Paramètres :**

repo_id (`str`) : le nom d'un utilisateur ou d'une organisation et le nom d'un dépôt, séparés par un `/`.

filename (`str`) : Le nom du fichier dans le dépôt.

subfolder (`str`, *facultatif*) : une valeur facultative correspondant à un dossier dans le dépôt du modèle.

repo_type (`str`, *facultatif*) : À définir sur `"dataset"`, `"space"` ou `"kernel"` si le téléchargement provient d’un dépôt de jeu de données, d’espace ou de noyau, `None` ou `"model"` si le téléchargement provient d’un modèle. La valeur par défaut est `None`.

revision (`str`, *facultatif*) : identifiant de révision Git facultatif, qui peut être un nom de branche, un tag ou un hash de commit.

library_name (`str`, *facultatif*) : Le nom de la bibliothèque à laquelle correspond l'objet.

library_version (`str`, *facultatif*) : La version de la bibliothèque.

cache_dir (`str`, `Path`, *facultatif*) : Chemin vers le dossier où les fichiers en cache sont stockés.

local_dir (`str` ou `Path`, *facultatif*) : Si fourni, le fichier téléchargé sera placé sous ce répertoire.

user_agent (`dict`, `str`, *facultatif*) : Les informations de l'agent utilisateur, sous forme de dictionnaire ou de chaîne de caractères.

force_download (`bool`, *facultatif*, par défaut `False`) : Indique si le fichier doit être téléchargé même s'il existe déjà dans le cache local.

etag_timeout (`float`, *facultatif*, par défaut `10`) : Lors de la récupération de l'ETag, nombre de secondes à attendre que le serveur envoie des données avant d'abandonner, valeur transmise à `httpx2.request`.

token (`str`, `bool`, *facultatif*) : Jeton à utiliser pour le téléchargement. - Si `True`, le jeton est lu depuis le dossier de configuration HuggingFace. - S'il s'agit d'une chaîne de caractères, elle est utilisée comme jeton d'authentification.

local_files_only (`bool`, *facultatif*, valeur par défaut `False`) : Si `True`, évite de télécharger le fichier et renvoie le chemin du fichier en cache local s'il existe.

headers (`dict`, *facultatif*) : En-têtes supplémentaires à envoyer avec la requête.

endpoint (`str`, *facultatif*) : L'endpoint du Hub vers lequel envoyer la requête. Par défaut, la valeur de `HF_ENDPOINT`.

tqdm_class (`tqdm`, *facultatif*) : Si fourni, remplace le comportement par défaut de la barre de progression. L'argument transmis doit hériter de `tqdm.auto.tqdm` ou au moins imiter son comportement. Par défaut, la barre de progression personnalisée de HF est utilisée, et peut être désactivée en définissant la variable d'environnement `HF_HUB_DISABLE_PROGRESS_BARS`.

dry_run (`bool`, *facultatif*, par défaut `False`) : Si `True`, effectue une simulation sans réellement télécharger le fichier. Renvoie un objet [DryRunFileInfo](/docs/huggingface_hub/main/fr/package_reference/hf_api#huggingface_hub.DryRunFileInfo) contenant des informations sur ce qui serait téléchargé.

**Retourne :** `str` ou [DryRunFileInfo](/docs/huggingface_hub/main/fr/package_reference/hf_api#huggingface_hub.DryRunFileInfo)

- Si `dry_run=False` : chemin local du fichier ou, si le réseau est désactivé, dernière version du fichier mise en cache sur le disque.
- Si `dry_run=True` : un objet [DryRunFileInfo](/docs/huggingface_hub/main/fr/package_reference/hf_api#huggingface_hub.DryRunFileInfo) contenant les informations de téléchargement.

**Exceptions levées :** [RepositoryNotFoundError](/docs/huggingface_hub/main/fr/package_reference/utilities#huggingface_hub.errors.RepositoryNotFoundError) ou [RevisionNotFoundError](/docs/huggingface_hub/main/fr/package_reference/utilities#huggingface_hub.errors.RevisionNotFoundError) ou `~utils.RemoteEntryNotFoundError` ou [LocalEntryNotFoundError](/docs/huggingface_hub/main/fr/package_reference/utilities#huggingface_hub.errors.LocalEntryNotFoundError) ou ``EnvironmentError`` ou ``OSError`` ou ``ValueError``

- [RepositoryNotFoundError](/docs/huggingface_hub/main/fr/package_reference/utilities#huggingface_hub.errors.RepositoryNotFoundError) -- Si le dépôt à partir duquel le téléchargement doit être effectué n'est pas trouvé. Cela peut être dû au fait qu'il n'existe pas, ou qu'il est défini comme `private` et que vous n'y avez pas accès.
- [RevisionNotFoundError](/docs/huggingface_hub/main/fr/package_reference/utilities#huggingface_hub.errors.RevisionNotFoundError) -- Si la révision à télécharger n'est pas trouvée.
- `~utils.RemoteEntryNotFoundError` -- Si le fichier à télécharger est introuvable.
- [LocalEntryNotFoundError](/docs/huggingface_hub/main/fr/package_reference/utilities#huggingface_hub.errors.LocalEntryNotFoundError) -- Si le réseau est désactivé ou indisponible et que le fichier n'est pas trouvé dans le cache.
- [`EnvironmentError`](https://docs.python.org/3/library/exceptions.html#EnvironmentError) -- Si `token=True` mais que le jeton ne peut pas être trouvé.
- [`OSError`](https://docs.python.org/3/library/exceptions.html#OSError) -- Si l'ETag ne peut pas être déterminé.
- [`ValueError`](https://docs.python.org/3/library/exceptions.html#ValueError) -- Si la valeur d'un paramètre est invalide.

Télécharger un fichier donné s'il n'est pas déjà présent dans le cache local.

La nouvelle disposition du fichier de cache est la suivante :
- Le répertoire de cache contient un sous-dossier par repo_id (namespaced by repo type)
- dans chaque dossier de dépôt :
  - refs est une liste des dernières paires de révision => commit_hash connues
  - blobs contient les blobs de fichiers réels (identifiés par leur git-sha ou sha256, selon qu'il s'agisse ou non de fichiers LFS)
  - snapshots contient un sous-dossier par commit, chaque "commit" contenant le sous-ensemble des fichiers résolus à ce commit particulier. Chaque nom de fichier est un lien symbolique vers le blob à ce commit particulier.

```
[  96]  .
└── [ 160]  models--julien-c--EsperBERTo-small
    ├── [ 160]  blobs
    │   ├── [321M]  403450e234d65943a7dcf7e05a771ce3c92faa84dd07db4ac20f592037a1e4bd
    │   ├── [ 398]  7cb18dc9bafbfcf74629a4b760af1b160957a83e
    │   └── [1.4K]  d7edf6bd2a681fb0175f7735299831ee1b22b812
    ├── [  96]  refs
    │   └── [  40]  main
    └── [ 128]  snapshots
        ├── [ 128]  2439f60ef33a0d46d85da5001d52aeda5b00ce9f
        │   ├── [  52]  README.md -> ../../blobs/d7edf6bd2a681fb0175f7735299831ee1b22b812
        │   └── [  76]  pytorch_model.bin -> ../../blobs/403450e234d65943a7dcf7e05a771ce3c92faa84dd07db4ac20f592037a1e4bd
        └── [ 128]  bbc77c8132af1cc5cf678da3f1ddf2de43606d48
            ├── [  52]  README.md -> ../../blobs/7cb18dc9bafbfcf74629a4b760af1b160957a83e
            └── [  76]  pytorch_model.bin -> ../../blobs/403450e234d65943a7dcf7e05a771ce3c92faa84dd07db4ac20f592037a1e4bd
```

Si `local_dir` est fourni, la structure de fichiers du dépôt sera répliquée à cet emplacement. Lors de l'utilisation de cette option, le `cache_dir` ne sera pas utilisé et un dossier `.cache/huggingface/` sera créé à la racine de `local_dir` pour stocker certaines métadonnées liées aux fichiers téléchargés. Bien que ce mécanisme ne soit pas aussi robuste que le système de cache principal, il est optimisé pour récupérer régulièrement la dernière version d'un dépôt.

### hf_hub_url[[huggingface_hub.hf_hub_url]]

#### huggingface_hub.hf_hub_url[[huggingface_hub.hf_hub_url]]

```python
huggingface_hub.hf_hub_url(repo_id: str, filename: str, subfolder: str | None = None, repo_type: str | None = None, revision: str | None = None, endpoint: str | None = None)
```

[Source](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/file_download.py#L210)

**Paramètres :**

repo_id (`str`) : Le nom d'un espace de noms (utilisateur ou organisation) et le nom d'un dépôt, séparés par un `/`.

filename (`str`) : Le nom du fichier dans le dépôt.

subfolder (`str`, *facultatif*) : une valeur facultative correspondant à un dossier dans le dépôt.

repo_type (`str`, *facultatif*) : À définir sur `"dataset"`, `"space"` ou `"kernel"` si le téléchargement provient d’un dépôt de jeu de données, d’espace ou de noyau, `None` ou `"model"` si le téléchargement provient d’un modèle. La valeur par défaut est `None`.

revision (`str`, *facultatif*) : identifiant de révision Git facultatif, qui peut être un nom de branche, un tag ou un hash de commit.

endpoint (`str`, *facultatif*) : L'endpoint du Hub vers lequel envoyer la requête. Par défaut, la valeur de `HF_ENDPOINT`.

Construire l’URL d’un fichier à partir des informations fournies.

L'adresse résolue peut être soit une URL hébergée sur huggingface.co, soit un lien vers Cloudfront (un réseau de diffusion de contenu, ou CDN) pour les fichiers volumineux dépassant quelques Mo.

Exemple :

```python
>>> from huggingface_hub import hf_hub_url

>>> hf_hub_url(
...     repo_id="julien-c/EsperBERTo-small", filename="pytorch_model.bin"
... )
'https://huggingface.co/julien-c/EsperBERTo-small/resolve/main/pytorch_model.bin'
```

> [!TIP]
> Remarques :
>
> Cloudfront est répliqué à l’échelle mondiale, ce qui rend les téléchargements beaucoup plus rapides pour l’utilisateur final (et réduit également nos coûts de bande passante).
>
> Cloudfront met en cache les fichiers de manière agressive par défaut (TTL par défaut de 24 heures), mais ce n'est pas un problème ici car nous implémentons un système de versionnement basé sur git sur huggingface.co, ce qui signifie que nous stockons les fichiers sur S3/Cloudfront de manière adressable par contenu (c'est-à-dire que le nom du fichier est son hachage). L'utilisation de noms de fichiers adressables par contenu signifie que le cache ne peut jamais être obsolète.
>
> En ce qui concerne la mise en cache côté client par cette bibliothèque, notre cache est basé sur l'entité tag (`ETag`) des objets, qui est un identifiant d'une version spécifique d'une ressource [1]_. L'ETag d'un objet est : son git-sha1 s'il est stocké dans git, ou son sha256 s'il est stocké dans git-lfs.

Références :

-  [1] https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/ETag

## Télécharger un instantané du dépôt[[huggingface_hub.snapshot_download]]

#### huggingface_hub.snapshot_download[[huggingface_hub.snapshot_download]]

```python
huggingface_hub.snapshot_download(repo_id: str, repo_type: str | None = None, revision: str | None = None, cache_dir: str | pathlib.Path | None = None, local_dir: str | pathlib.Path | None = None, library_name: str | None = None, library_version: str | None = None, user_agent: dict | str | None = None, etag_timeout: float = 10, force_download: bool = False, token: bool | str | None = None, local_files_only: bool = False, allow_patterns: list[str] | str | None = None, ignore_patterns: list[str] | str | None = None, max_workers: int = 8, tqdm_class: type[tqdm.asyncio.tqdm_asyncio] | None = None, headers: dict[str, str] | None = None, endpoint: str | None = None, dry_run: bool = False)
```

[Source](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/_snapshot_download.py#L121)

**Paramètres :**

repo_id (`str`) : le nom d'un utilisateur ou d'une organisation et le nom d'un dépôt, séparés par un `/`.

repo_type (`str`, *facultatif*) : À définir sur `"dataset"`, `"space"` ou `"kernel"` si le téléchargement provient d’un dépôt de jeu de données, d’espace ou de noyau, `None` ou `"model"` si le téléchargement provient d’un modèle. La valeur par défaut est `None`.

revision (`str`, *facultatif*) : identifiant de révision Git facultatif, qui peut être un nom de branche, un tag ou un hachage de commit.

cache_dir (`str`, `Path`, *facultatif*) : Chemin vers le dossier où les fichiers en cache sont stockés.

local_dir (`str` ou `Path`, *facultatif*) : Si fourni, les fichiers téléchargés seront placés sous ce répertoire.

library_name (`str`, *facultatif*) : Le nom de la bibliothèque à laquelle correspond l'objet.

library_version (`str`, *facultatif*) : La version de la bibliothèque.

user_agent (`str`, `dict`, *facultatif*) : Les informations de l'agent utilisateur, sous forme de dictionnaire ou de chaîne de caractères.

etag_timeout (`float`, *facultatif*, par défaut `10`) : Lors de la récupération de l'ETag, nombre de secondes à attendre que le serveur envoie des données avant d'abandonner, valeur transmise à `httpx2.request`.

force_download (`bool`, *facultatif*, par défaut `False`) : Indique si le fichier doit être téléchargé même s'il existe déjà dans le cache local.

token (`str`, `bool`, *facultatif*) : Jeton à utiliser pour le téléchargement. - Si `True`, le jeton est lu depuis le dossier de configuration HuggingFace. - S'il s'agit d'une chaîne de caractères, elle est utilisée comme jeton d'authentification.

headers (`dict`, *facultatif*) : En-têtes supplémentaires à inclure dans la requête. Ces en-têtes ont la priorité sur les autres.

endpoint (`str`, *facultatif*) : L'endpoint du Hub vers lequel envoyer la requête. Par défaut, la valeur de `HF_ENDPOINT`.

local_files_only (`bool`, *facultatif*, valeur par défaut `False`) : Si `True`, ne télécharge aucun fichier, même s'ils ne sont pas dans `cache_dir` ou `local_dir`.

allow_patterns (`list[str]` ou `str`, *facultatif*) : Si fourni, seuls les fichiers correspondant à au moins un motif sont téléchargés.

ignore_patterns (`list[str]` ou `str`, *facultatif*) : Si fourni, les fichiers correspondant à l'un des motifs ne sont pas téléchargés.

max_workers (`int`, *facultatif*) : Nombre de threads simultanés pour le téléchargement des fichiers (1 thread = 1 téléchargement de fichier). Valeur par défaut : 8.

tqdm_class (`tqdm`, *facultatif*) : Si fourni, remplace le comportement par défaut de la barre de progression. L’argument transmis doit hériter de `tqdm.auto.tqdm` ou au moins imiter son comportement. Notez que `tqdm_class` n’est pas transmis à chaque téléchargement individuel. Par défaut, la barre de progression personnalisée de HF est utilisée, et peut être désactivée en définissant la variable d’environnement `HF_HUB_DISABLE_PROGRESS_BARS`.

dry_run (`bool`, *facultatif*, par défaut `False`) : Si `True`, effectue une simulation sans réellement télécharger les fichiers. Renvoie une liste d'objets [DryRunFileInfo](/docs/huggingface_hub/main/fr/package_reference/hf_api#huggingface_hub.DryRunFileInfo) contenant des informations sur ce qui serait téléchargé.

**Retourne :** `str` ou liste de [DryRunFileInfo](/docs/huggingface_hub/main/fr/package_reference/hf_api#huggingface_hub.DryRunFileInfo)

- Si `dry_run=False` : chemin local de l'instantané.
- Si `dry_run=True` : une liste d'objets [DryRunFileInfo](/docs/huggingface_hub/main/fr/package_reference/hf_api#huggingface_hub.DryRunFileInfo) contenant les informations de téléchargement.

**Exceptions levées :** [RepositoryNotFoundError](/docs/huggingface_hub/main/fr/package_reference/utilities#huggingface_hub.errors.RepositoryNotFoundError) ou [RevisionNotFoundError](/docs/huggingface_hub/main/fr/package_reference/utilities#huggingface_hub.errors.RevisionNotFoundError) ou [IncompleteSnapshotError](/docs/huggingface_hub/main/fr/package_reference/utilities#huggingface_hub.errors.IncompleteSnapshotError) ou ``EnvironmentError`` ou ``OSError`` ou ``ValueError``

- [RepositoryNotFoundError](/docs/huggingface_hub/main/fr/package_reference/utilities#huggingface_hub.errors.RepositoryNotFoundError) -- Si le dépôt à partir duquel le téléchargement doit être effectué n'est pas trouvé. Cela peut être dû au fait qu'il n'existe pas ou qu'il est défini comme `private` et que vous n'y avez pas accès.
- [RevisionNotFoundError](/docs/huggingface_hub/main/fr/package_reference/utilities#huggingface_hub.errors.RevisionNotFoundError) -- Si la révision à télécharger n'est pas trouvée.
- [IncompleteSnapshotError](/docs/huggingface_hub/main/fr/package_reference/utilities#huggingface_hub.errors.IncompleteSnapshotError) -- Si le Hub est inaccessible (hors ligne, problème de connexion ou `local_files_only=True`) et que l’aperçu en cache ne contient pas certains des fichiers demandés.
- [`EnvironmentError`](https://docs.python.org/3/library/exceptions.html#EnvironmentError) -- Si `token=True` et que le jeton ne peut pas être trouvé.
- [`OSError`](https://docs.python.org/3/library/exceptions.html#OSError) -- si l'ETag ne peut pas être déterminé.
- [`ValueError`](https://docs.python.org/3/library/exceptions.html#ValueError) -- Si la valeur d'un paramètre est invalide.

Télécharger les fichiers du dépôt.

Téléchargez l’ensemble des fichiers d’un dépôt à la révision spécifiée. Cette opération est utile lorsque vous souhaitez tous les fichiers d’un dépôt, car vous ne savez pas à l’avance lesquels vous seront nécessaires _a priori_. Tous les fichiers sont imbriqués dans un dossier afin de conserver leur chemin et leur nom de fichier relatifs à ce dossier. Vous pouvez également filtrer les fichiers à télécharger en utilisant `allow_patterns` et `ignore_patterns`.

Si `local_dir` est fourni, la structure de fichiers du dépôt sera répliquée à cet emplacement. Lors de l'utilisation de cette option, le `cache_dir` ne sera pas utilisé, et un dossier `.cache/huggingface/` sera créé à la racine de `local_dir` pour stocker certaines métadonnées liées aux fichiers téléchargés. Bien que ce mécanisme ne soit pas aussi robuste que le système de cache principal, il est optimisé pour récupérer régulièrement la dernière version d'un dépôt.

Une alternative consisterait à cloner le dépôt, mais cela nécessite que git et git-lfs soient installés et correctement configurés. Il est également impossible de filtrer les fichiers à télécharger lors du clonage d'un dépôt à l'aide de git.

## Lire l'arborescence du dépôt mise en cache[[huggingface_hub.get_cached_repo_tree]]

#### huggingface_hub.get_cached_repo_tree[[huggingface_hub.get_cached_repo_tree]]

```python
huggingface_hub.get_cached_repo_tree(repo_id: str, repo_type: str | None = None, revision: str | None = None, cache_dir: str | pathlib.Path | None = None, local_dir: str | pathlib.Path | None = None)
```

[Source](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/_snapshot_download.py#L603)

**Paramètres :**

repo_id (`str`) : le nom d'un utilisateur ou d'une organisation et le nom d'un dépôt, séparés par un `/`.

repo_type (`str`, *facultatif*) : À définir sur `"dataset"`, `"space"` ou `"kernel"` si la liste provient d’un dépôt de jeu de données, d’espace ou de noyau, `None` ou `"model"` si elle provient d’un modèle. La valeur par défaut est `None`.

revision (`str`, *facultatif*) : identifiant de révision Git facultatif, qui peut être un nom de branche, un tag ou un hash de commit. Par défaut, la branche par défaut est utilisée. Les noms de branche/tag sont résolus en hash de commit à l’aide du cache local (`refs/`).

cache_dir (`str`, `Path`, *facultatif*) : Chemin vers le dossier où les fichiers en cache sont stockés. Par défaut, la valeur de `HF_HUB_CACHE`.

local_dir (`str` ou `Path`, *facultatif*) : Si fourni, lit la liste de l’arborescence mise en cache par un téléchargement `local_dir` (depuis `local_dir/.cache/huggingface/`) au lieu du cache principal. Les révisions de branche/étiquette sont toujours résolues vers un hachage de commit en utilisant le cache principal (`cache_dir`).

**Retourne :** `list[RepoFile]`

La liste des objets [RepoFile](/docs/huggingface_hub/main/fr/package_reference/hf_api#huggingface_hub.RepoFile) mis en cache pour cette révision.

**Levée :** [CachedRepoTreeNotFoundError](/docs/huggingface_hub/main/fr/package_reference/utilities#huggingface_hub.errors.CachedRepoTreeNotFoundError)

- [CachedRepoTreeNotFoundError](/docs/huggingface_hub/main/fr/package_reference/utilities#huggingface_hub.errors.CachedRepoTreeNotFoundError) -- Si aucun arborescence mise en cache n'existe pour la révision demandée (par exemple, le dépôt n'a jamais été téléchargé à cette révision).

Retourne la liste en cache des fichiers d'un dépôt à une révision donnée, sans aucun appel réseau.

La liste d’arborescence est l’ensemble des fichiers (avec leurs métadonnées de téléchargement) d’un dépôt à un commit donné. Elle est créée sur le disque comme effet secondaire de [snapshot_download()](/docs/huggingface_hub/main/fr/package_reference/file_download#huggingface_hub.snapshot_download) (voir les fichiers de cache `trees/<commit_hash>.json`) et sert à éviter les appels réseau lors des téléchargements suivants. Cette fonction expose directement ce cache.

Si vous avez besoin de la liste actuelle de l'arborescence d'un dépôt sur le Hub, utilisez plutôt [list_repo_tree()](/docs/huggingface_hub/main/fr/package_reference/hf_api#huggingface_hub.HfApi.list_repo_tree).

Exemple :
```py
>>> from huggingface_hub import get_cached_repo_tree
>>> files = get_cached_repo_tree("openai-community/gpt2")
>>> [f.path for f in files]
['.gitattributes', 'config.json', 'model.safetensors', ...]
```

## Résoudre une révision

Résolvez un nom de branche/étiquette en hachage de commit une seule fois, puis transmettez le résultat pour épingler tous les téléchargements au même commit. Consultez [HfApi.resolve_revision()](/docs/huggingface_hub/main/fr/package_reference/hf_api#huggingface_hub.HfApi.resolve_revision) et le [guide du système de cache](../guides/manage-cache#pin-a-revision-advanced).

### ResolvedRevision[[huggingface_hub.ResolvedRevision]]

#### huggingface_hub.ResolvedRevision[[huggingface_hub.ResolvedRevision]]

```python
huggingface_hub.ResolvedRevision(resolved: str, initial: str | None = None, repo_id: str | None = None, repo_type: str | None = None)
```

[Source](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/_revision.py#L4)

**Paramètres :**

initial (`str` ou `None`) : La révision initialement demandée par l'utilisateur. Si `None`, la valeur par défaut de la chaîne est `"main"`.

resolved (`str`) : Le hash de commit auquel `initial` se résout.

Une révision git qui a déjà été résolue en hachage de commit.

`ResolvedRevision` est une sous-classe de `str`, il peut donc être transmis à toute méthode de `huggingface_hub` acceptant un argument `revision`. Sa valeur en chaîne de caractères correspond à la révision initialement demandée par l'utilisateur (par exemple `"main"`, `"refs/pr/4"`), ce qui permet de conserver des URL et des messages d'erreur lisibles, tandis que `.resolved` contient l'empreinte de commit vers laquelle elle pointe.

Les instances sont construites par [HfApi.resolve_revision()](/docs/huggingface_hub/main/fr/package_reference/hf_api#huggingface_hub.HfApi.resolve_revision), qui met également en cache la correspondance `revision` -> `commit hash` dans le cache local (dossier `refs/`).

Un hash de commit n’a de sens que pour le dépôt auquel il a été résolu, une instance mémorise donc également ce dépôt. Le résoudre à nouveau pour un autre dépôt n’est pas une erreur : la révision initialement demandée est résolue à nouveau (voir [HfApi.resolve_revision()](/docs/huggingface_hub/main/fr/package_reference/hf_api#huggingface_hub.HfApi.resolve_revision)).

Exemple :
```python
>>> from huggingface_hub import resolve_revision
>>> revision = resolve_revision("openai-community/gpt2")
>>> revision
ResolvedRevision(initial=None, resolved='607a30d783dfa663caf39e06633721c8d4cfcd7e')
>>> revision == "main"  # it's a string
True
>>> revision.resolved
'607a30d783dfa663caf39e06633721c8d4cfcd7e'
```

## Obtenir les métadonnées d'un fichier

### get_hf_file_metadata[[huggingface_hub.get_hf_file_metadata]]

#### huggingface_hub.get_hf_file_metadata[[huggingface_hub.get_hf_file_metadata]]

```python
huggingface_hub.get_hf_file_metadata(url: str, token: bool | str | None = None, timeout: float | None = 10, library_name: str | None = None, library_version: str | None = None, user_agent: dict | str | None = None, headers: dict[str, str] | None = None, endpoint: str | None = None, retry_on_errors: bool = False)
```

[Source](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/file_download.py#L1617)

**Paramètres :**

url (`str`) : URL du fichier, par exemple renvoyée par [hf_hub_url()](/docs/huggingface_hub/main/fr/package_reference/file_download#huggingface_hub.hf_hub_url).

token (`str` ou `bool`, *facultatif*) : Un jeton à utiliser pour le téléchargement. - Si `True`, le jeton est lu depuis le dossier de configuration HuggingFace. - Si `False` ou `None`, aucun jeton n'est fourni. - S'il s'agit d'une chaîne de caractères, elle est utilisée comme jeton d'authentification.

timeout (`float`, *facultatif*, par défaut 10) : Nombre de secondes à attendre avant d'abandonner si le serveur n'a pas envoyé les métadonnées.

library_name (`str`, *facultatif*) : Le nom de la bibliothèque à laquelle correspond l'objet.

library_version (`str`, *facultatif*) : La version de la bibliothèque.

user_agent (`dict`, `str`, *facultatif*) : Les informations de l'agent utilisateur, sous forme de dictionnaire ou de chaîne de caractères.

headers (`dict`, *facultatif*) : En-têtes supplémentaires à envoyer avec la requête.

endpoint (`str`, *facultatif*) : Point de terminaison du Hub. Valeur par défaut : .

retry_on_errors (`bool`, *facultatif*, valeur par défaut `False`) : Indique s'il faut réessayer en cas d'erreurs (429, 5xx, dépassement de délai, erreurs réseau). Si False, aucune nouvelle tentative pour un retour rapide au cache local.

**Retourne :**

Un objet [HfFileMetadata](/docs/huggingface_hub/main/fr/package_reference/file_download#huggingface_hub.HfFileMetadata) contenant des métadonnées telles que l'emplacement, l'etag, la taille et le commit_hash.

Récupérer les métadonnées d'un fichier versionné sur le Hub pour une URL donnée.

### HfFileMetadata[[huggingface_hub.HfFileMetadata]]

#### huggingface_hub.HfFileMetadata[[huggingface_hub.HfFileMetadata]]

```python
huggingface_hub.HfFileMetadata(commit_hash: str | None, etag: str | None, location: str, size: int | None, xet_file_data: huggingface_hub.utils._xet.XetFileData | None)
```

[Source](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/file_download.py#L155)

**Paramètres :**

commit_hash (`str`, *facultatif*) : Le commit_hash associé au fichier.

etag (`str`, *facultatif*) : Etag du fichier sur le serveur.

location (`str`) : Emplacement où télécharger le fichier. Peut être une URL du Hub ou non (CDN).

size (`size`) : Taille du fichier. Dans le cas d'un fichier LFS, contient la taille du fichier LFS réel, et non celle du pointeur.

xet_file_data (`XetFileData`, *facultatif*) : informations Xet relatives au fichier. Ce champ n’est défini que si le fichier est stocké à l’aide du stockage Xet.

Structure de données contenant des informations sur un fichier versionné sur le Hub.

Retourné par [get_hf_file_metadata()](/docs/huggingface_hub/main/fr/package_reference/file_download#huggingface_hub.get_hf_file_metadata) sur la base d'une URL.

## Mise en cache

Les méthodes affichées ci-dessus sont conçues pour fonctionner avec un système de cache qui empêche le téléchargement à nouveau des fichiers. Le système de cache a été mis à jour dans la v0.8.0 pour devenir le système de cache central partagé entre les bibliothèques qui dépendent du Hub.

Consultez le [guide du système de cache](../guides/manage-cache) pour une présentation détaillée de la mise en cache sur HF.

