# 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](https://docs.python.org/3/library/venv.html). Si no está familiarizado con los entornos virtuales de Python, consulte esta [guía](https://packaging.python.org/en/latest/guides/installing-using-pip-and-virtual-environments/). 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:

```bash
python -m venv .venv
```

Active el entorno virtual. En Linux y macOS:

```bash
source .venv/bin/activate
```

Activar el entorno virtual en Windows:

```bash
.venv/Scripts/activate
```

Ahora está listo para instalar `huggingface_hub` [desde el registro de PyPi](https://pypi.org/project/huggingface-hub/):

```bash
pip install --upgrade huggingface_hub
```

Una vez finalizado, [verifica la instalación](#check-installation) para asegurarte de que funciona correctamente.

### Instalar dependencias opcionales

Algunas dependencias de `huggingface_hub` son [opcionales](https://setuptools.pypa.io/en/latest/userguide/dependency_management.html#optional-dependencies) 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`:
```bash
# 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 el último lanzamiento oficial pero aún no se ha publicado 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.

```bash
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 deseas probar una nueva función o una nueva corrección de errores que aún no se ha fusionado:

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

Una vez finalizado, [verifica la instalación](#check-installation) para asegurarte de que funciona correctamente.

### Instalación editable

La instalación desde el código fuente permite configurar una [instalación editable](https://pip.pypa.io/en/stable/topics/local-project-installs/#editable-installs). 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.

```bash
# 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. Python buscará ahora 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 que 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:

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

En Windows:

```powershell
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](https://anaconda.org/conda-forge/huggingface_hub):

```bash
conda install -c conda-forge huggingface_hub
```

Una vez finalizado, [verifica la instalación](#check-installation) para asegurarte de que funciona correctamente.

## Comprobar la instalación

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

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

Este comando obtendrá información del Hub sobre el modelo [gpt2](https://huggingface.co/gpt2). La salida debería ser así:

```text
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` como una biblioteca multiplataforma y, en particular, para que funcione 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. A continuación, se presenta una lista exhaustiva de los problemas conocidos. Si te encuentras con algún problema no documentado, infórmalo abriendo [un issue en Github](https://github.com/huggingface/huggingface_hub/issues/new/choose).

- 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é](./guides/manage-cache#limitations) para más detalles.
- Las rutas de archivo en el Hub pueden tener caracteres especiales (p. ej., `"path/to?/my/file"`). Windows es
más restrictivo con los [caracteres especiales](https://learn.microsoft.com/en-us/windows/win32/intl/character-sets-used-in-file-names), lo que impide descargar esos archivos en Windows. Esperamos 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](package_reference/environment_variables) o [consultar una de nuestras guías](guides/overview) para empezar.