Instalación

Antes de comenzar, deberá configurar su entorno instalando los paquetes adecuados.

huggingface_hub se prueba en Python 3.10+.

Instalar con pip

Se recomienda encarecidamente instalar huggingface_hub en un entorno virtual. Si no estás familiarizado con los entornos virtuales de Python, echa un vistazo a esta guía. Un entorno virtual facilita la gestión de diferentes proyectos y evita problemas de compatibilidad entre dependencias.

Comience creando un entorno virtual en el directorio de su proyecto:

python -m venv .venv

Active el entorno virtual. En Linux y macOS:

source .venv/bin/activate

Activar el entorno virtual en Windows:

.venv/Scripts/activate

Ahora está listo para instalar huggingface_hub desde el registro de PyPi:

pip install --upgrade huggingface_hub

Una vez finalizado, verifica la instalación para asegurarte de que funciona correctamente.

Instalar dependencias opcionales

Algunas dependencias de huggingface_hub son opcionales porque no son necesarias para ejecutar las funciones principales de huggingface_hub. Sin embargo, algunas funciones de huggingface_hub pueden no estar disponibles si no se instalan las dependencias opcionales.

Puedes instalar dependencias opcionales mediante pip:

# Install dependencies for both torch-specific and MCP-specific features.
pip install 'huggingface_hub[mcp,torch]'

Esta es la lista de dependencias opcionales en huggingface_hub:

• fastai, torch: dependencias para ejecutar funciones específicas del framework.
• dev: dependencias para contribuir a la librería. Incluye testing (para ejecutar pruebas), typing (para ejecutar el comprobador de tipos) y quality (para ejecutar linters).

Instalar desde el código fuente

En algunos casos, es interesante instalar huggingface_hub directamente desde el código fuente. Esto permite utilizar la versión de vanguardia de main en lugar de la última versión estable. La versión main es útil para mantenerse al día con los últimos avances, por ejemplo, si un error se corrigió desde la última publicación oficial pero aún no se ha lanzado una nueva versión.

Sin embargo, esto significa que la versión main no siempre puede ser estable. Nos esforzamos por mantener la versión main operativa, y la mayoría de los problemas suelen resolverse en unas pocas horas o un día. Si te encuentras con un problema, abre un Issue para que podamos solucionarlo aún más rápido.

pip install git+https://github.com/huggingface/huggingface_hub

Al instalar desde el código fuente, también puedes especificar una rama específica. Esto es útil si quieres probar una nueva función o una nueva corrección de errores que aún no se ha fusionado:

pip install git+https://github.com/huggingface/huggingface_hub@my-feature-branch

Una vez finalizado, verifica la instalación para asegurarte de que funciona correctamente.

Instalación editable

La instalación desde el código fuente permite configurar una instalación editable. Esta es una instalación más avanzada si planeas contribuir a huggingface_hub y necesitas probar cambios en el código. Debes clonar una copia local de huggingface_hub en tu máquina.

# First, clone repo locally
git clone https://github.com/huggingface/huggingface_hub.git

# Then, install with -e flag
cd huggingface_hub
pip install -e .

Estos comandos vincularán la carpeta donde clonaste el repositorio con las rutas de tu biblioteca de Python. Ahora Python buscará dentro de la carpeta clonada además de las rutas de biblioteca habituales. Por ejemplo, si tus paquetes de Python suelen instalarse en ./.venv/lib/python3.13/site-packages/, Python también buscará en la carpeta donde clonaste ./huggingface_hub/.

Instala la CLI de Hugging Face

Usa nuestros instaladores de una sola línea para configurar la CLI hf sin tocar tu entorno de Python:

En macOS y Linux:

curl -LsSf https://hf.co/cli/install.sh | bash

En Windows:

powershell -ExecutionPolicy ByPass -c "irm https://hf.co/cli/install.ps1 | iex"

Para actualizar una instalación existente, ejecute hf update: detecta cómo se instaló hf (instalador independiente, Homebrew o pip) y ejecuta el comando correspondiente.

Instalar con conda

Si estás más familiarizado con él, puedes instalar huggingface_hub usando el canal conda-forge:

conda install -c conda-forge huggingface_hub

Una vez finalizado, verifica la instalación para asegurarte de que funciona correctamente.

Comprobar la instalación

Una vez instalado, comprueba que huggingface_hub funciona correctamente ejecutando el siguiente comando:

python -c "from huggingface_hub import model_info; print(model_info('gpt2'))"

Este comando obtendrá información del Hub sobre el modelo gpt2. La salida debería ser así:

Model Name: gpt2
Tags: ['pytorch', 'tf', 'jax', 'tflite', 'rust', 'safetensors', 'gpt2', 'text-generation', 'en', 'doi:10.57967/hf/0039', 'transformers', 'exbert', 'license:mit', 'has_space']
Task: text-generation

Limitaciones de Windows

Con nuestro objetivo de democratizar el buen ML en todas partes, construimos huggingface_hub para ser una biblioteca multiplataforma y, en particular, para funcionar correctamente tanto en sistemas basados en Unix como en Windows. Sin embargo, hay algunos casos en los que huggingface_hub tiene ciertas limitaciones cuando se ejecuta en Windows. Aquí hay una lista exhaustiva de los problemas conocidos. Por favor, infórmenos si se encuentra con algún problema no documentado abriendo un issue en Github.

• El sistema de caché de huggingface_hub se basa en enlaces simbólicos para almacenar de forma eficiente los archivos descargados del Hub. En Windows, debes activar el modo de desarrollador o ejecutar tu script como administrador para habilitar los enlaces simbólicos. Si no están activados, el sistema de caché sigue funcionando, pero de manera no optimizada. Consulta la sección limitaciones de la caché para más detalles.
• Las rutas de archivo en el Hub pueden contener caracteres especiales (p. ej. "path/to?/my/file"). Windows es más restrictivo con los caracteres especiales, lo que hace imposible descargar esos archivos en Windows. Esperemos que este sea un caso poco frecuente. Si crees que se trata de un error, ponte en contacto con el propietario del repositorio o con nosotros para encontrar una solución.

Próximos pasos

Una vez que huggingface_hub esté instalado correctamente en tu máquina, es posible que quieras configurar variables de entorno o consultar una de nuestras guías para empezar.