Instalação

Antes de começar, você precisará configurar seu ambiente instalando os pacotes apropriados.

huggingface_hub é testado no Python 3.10+.

Instale com pip

É altamente recomendável instalar o huggingface_hub em um ambiente virtual. Se você não está familiarizado com ambientes virtuais do Python, confira este guia. Um ambiente virtual facilita a gestão de diferentes projetos e evita problemas de compatibilidade entre dependências.

Comece criando um ambiente virtual no diretório do seu projeto:

python -m venv .venv

Ative o ambiente virtual. No Linux e no macOS:

source .venv/bin/activate

Ative o ambiente virtual no Windows:

.venv/Scripts/activate

Agora você está pronto para instalar o huggingface_hub a partir do registro PyPi:

pip install --upgrade huggingface_hub

Ao concluir, verifique se o check installation está funcionando corretamente.

Instale as dependências opcionais

Algumas dependências do huggingface_hub são opcionais porque não são necessárias para executar os recursos principais do huggingface_hub. No entanto, alguns recursos do huggingface_hub podem não estar disponíveis se as dependências opcionais não estiverem instaladas.

Você pode instalar dependências opcionais via pip:

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

Aqui está a lista de dependências opcionais em huggingface_hub:

• fastai, torch: dependências para executar recursos específicos do framework.
• dev: dependências para contribuir com a lib. Inclui testing (para executar testes), typing (para executar o verificador de tipos) e quality (para executar linters).

Instalar a partir do código-fonte

Em alguns casos, é interessante instalar o huggingface_hub diretamente do código-fonte. Isso permite usar a versão mais recente do main, em vez da versão estável mais recente. A versão main é útil para acompanhar os desenvolvimentos mais recentes, por exemplo, se um bug foi corrigido desde o último lançamento oficial, mas um novo lançamento ainda não foi disponibilizado.

No entanto, isso significa que a versão main pode não ser sempre estável. Esforçamo-nos para manter a versão main operacional, e a maioria dos problemas geralmente é resolvida em poucas horas ou em um dia. Se você encontrar um problema, abra uma Issue para que possamos corrigi-lo ainda mais rápido!

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

Ao instalar a partir do código-fonte, você também pode especificar um branch específico. Isso é útil se você quiser testar um novo recurso ou uma nova correção de bug que ainda não foi mesclada:

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

Ao concluir, verifique se o check installation está funcionando corretamente.

Instalação editável

A instalação a partir do código-fonte permite configurar uma instalação editável. Esta é uma instalação mais avançada, caso você planeje contribuir para o huggingface_hub e precise testar alterações no código. É necessário clonar uma cópia local do huggingface_hub na sua 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 .

Esses comandos vinculam a pasta para a qual você clonou o repositório aos caminhos da sua biblioteca Python. Agora, o Python procurará dentro da pasta clonada, além dos caminhos de biblioteca normais. Por exemplo, se seus pacotes Python são normalmente instalados em ./.venv/lib/python3.13/site-packages/, o Python também buscará na pasta que você clonou ./huggingface_hub/.

Instale o CLI do Hugging Face

Use nossos instaladores de uma linha para configurar o CLI hf sem tocar no seu ambiente Python:

No macOS e no Linux:

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

No Windows:

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

Para atualizar uma instalação existente, execute hf update — ele detecta como o hf foi instalado (instalador standalone, Homebrew ou pip) e executa o comando correspondente.

Instale com conda

Se você é mais familiarizado com ele, pode instalar o huggingface_hub usando o canal conda-forge:

conda install -c conda-forge huggingface_hub

Ao concluir, verifique se o check installation está funcionando corretamente.

Verifique a instalação

Depois de instalado, verifique se o huggingface_hub funciona corretamente executando o seguinte comando:

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

Este comando buscará informações sobre o modelo gpt2 no Hub. A saída deve ser semelhante a esta:

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

Limitações do Windows

Com o objetivo de democratizar um bom ML em qualquer lugar, criamos o huggingface_hub para ser uma biblioteca multiplataforma e, em particular, para funcionar corretamente tanto em sistemas baseados em Unix quanto em sistemas Windows. No entanto, existem alguns casos em que o huggingface_hub apresenta algumas limitações quando executado no Windows. Esta é uma lista exaustiva dos problemas conhecidos. Por favor, nos avise se encontrar algum problema não documentado abrindo uma issue no Github.

• O sistema de cache do huggingface_hub depende de links simbólicos para armazenar com eficiência os arquivos baixados do Hub. No Windows, você deve ativar o modo de desenvolvedor ou executar seu script como administrador para habilitar links simbólicos. Se eles não estiverem ativados, o sistema de cache ainda funciona, mas de uma maneira não otimizada. Leia a seção limitações do cache para mais detalhes.
• Os caminhos de arquivo no Hub podem conter caracteres especiais (por exemplo, "path/to?/my/file"). O Windows é mais restritivo em relação a caracteres especiais, o que torna impossível baixar esses arquivos no Windows. Espera-se que esse seja um caso raro. Entre em contato com o proprietário do repositório se você acredita que se trata de um erro ou conosco para encontrarmos uma solução.

Próximas etapas

Depois que o huggingface_hub estiver instalado corretamente na sua máquina, você pode querer configurar variáveis de ambiente ou consultar um dos nossos guias para começar.