---
name: hf_snapshot_download
kind: function
lang: py
domain: ml
version: "1.0.0"
purity: impure
signature: "def hf_snapshot_download(repo_id: str, allow_patterns: list[str] | None = None, ignore_patterns: list[str] | None = None, local_dir: str | None = None, token: str | None = None) -> str"
description: "Descarga un snapshot de un repo HuggingFace Hub (completo o filtrado por patrones glob). Wrapper de huggingface_hub.snapshot_download con ImportError descriptivo. Soporta repos privados/gated via token. Retorna path local del snapshot."
tags: [huggingface, hf, download, snapshot, model, weights, safetensors, ml, hub, pendiente-usar]
uses_functions: []
uses_types: []
returns: []
returns_optional: false
error_type: "error_go_core"
imports: [huggingface_hub]
params:
  - name: repo_id
    desc: "identificador del repo en HuggingFace Hub en formato 'owner/name' (ej: 'runwayml/stable-diffusion-v1-5')"
  - name: allow_patterns
    desc: "lista opcional de patrones glob para incluir solo ciertos archivos (ej: ['*.safetensors', 'config.json']). None descarga todo."
  - name: ignore_patterns
    desc: "lista opcional de patrones glob para excluir archivos (ej: ['*.bin', 'flax_*', 'tf_*']). Util para descargar solo safetensors y evitar duplicados en otro formato."
  - name: local_dir
    desc: "directorio local de destino. Si None, usa el cache global de HuggingFace (~/.cache/huggingface/hub/)."
  - name: token
    desc: "token de acceso HuggingFace para repos privados o gated (Llama, Gemma, etc.). Si None, usa la variable de entorno HF_TOKEN."
output: "string: path absoluto al directorio local donde quedo almacenado el snapshot"
tested: true
tests:
  - "repo_id se pasa correctamente a snapshot_download"
  - "retorna string (la ruta local)"
  - "allow_patterns se incluye en los kwargs si se especifica"
  - "ignore_patterns se incluye en los kwargs si se especifica"
  - "local_dir se incluye en los kwargs si se especifica"
  - "token se incluye en los kwargs si se especifica"
  - "args opcionales None no se incluyen en kwargs"
  - "ImportError descriptivo si huggingface_hub no esta instalado"
test_file_path: "python/functions/ml/tests/test_hf_snapshot_download.py"
file_path: "python/functions/ml/hf_snapshot_download.py"
---

## Ejemplo

```python
from ml.hf_snapshot_download import hf_snapshot_download

# Descargar solo safetensors y JSONs de SD v1.5 (evita el .bin de 4 GB)
path = hf_snapshot_download(
    repo_id="runwayml/stable-diffusion-v1-5",
    allow_patterns=["*.safetensors", "*.json", "*.txt"],
    ignore_patterns=["*.bin"],
    local_dir=".local/models/sd-v1-5",
)
# path = "$HOME/fn_registry/.local/models/sd-v1-5"

# Descargar un modelo gated (Llama) con token
path = hf_snapshot_download(
    repo_id="meta-llama/Llama-2-7b-hf",
    ignore_patterns=["*.bin"],
    local_dir=".local/models/llama-2-7b",
    token="hf_xxxxxxxxxxxxxxxxxxxxxxxx",
)

# Descargar al cache global (sin local_dir)
path = hf_snapshot_download("BAAI/bge-m3")
# path = "/home/lucas/.cache/huggingface/hub/models--BAAI--bge-m3/snapshots/..."
```

## Notas

- El wrapper es minimo: no reimplementa logica de descarga, solo asegura que
  `huggingface_hub` no sea requerido en tiempo de indexacion del registry.
- `snapshot_download` es idempotente: si el snapshot ya existe en el cache/local_dir
  con los mismos hashes, no vuelve a descargar.
- `allow_patterns` y `ignore_patterns` usan la semantica de `fnmatch`.
  Tienen precedencia: si un archivo coincide con ambos, `ignore_patterns` gana.
- Para repos grandes (>10 GB), conviene usar `ignore_patterns=["*.bin"]` si el
  repo ofrece safetensors (formato mas seguro, sin pickle, y soporta mmap).
- El token puede ponerse tambien en `~/.cache/huggingface/token` via
  `huggingface-cli login` para no pasarlo inline.
- impure: hace I/O de red, escribe en disco, depende de disponibilidad del Hub.