← Todos os tutoriais

Como baixar um modelo do Hugging Face pela linha de comando

Instalar o comando hf, ver os arquivos de um repositório, simular o download, baixar só o que precisa e escolher a pasta de destino.

Nível
Começando
Você vai precisar
  • Windows 10 ou 11
  • Python 3 instalado
  • Espaço em disco para os arquivos escolhidos
Testado em
, Windows 11 Pro, Python 3.14.4 e huggingface_hub 2.4.0, sem conta no Hugging Face

Baixar modelo pelo navegador funciona até o primeiro arquivo de 10 GB que cai no meio. O comando hf, do próprio Hugging Face, mostra antes quanto o download vai ocupar, baixa só os arquivos que você escolher e deixa conferir depois se chegou tudo inteiro. Este passo a passo usa o repositório do Z-Image-Turbo como exemplo.

1. Instalar o comando hf

Com o Python instalado, abra o PowerShell numa pasta de trabalho e crie um ambiente separado, para não misturar com outros programas:

python -m venv venv
.\venv\Scripts\python -m pip install huggingface_hub
.\venv\Scripts\hf --version

No teste, o último comando respondeu 2.4.0. Nos exemplos abaixo o comando aparece como .\venv\Scripts\hf; se você ativar o ambiente ou instalar de outro jeito, basta hf.

2. Ver o que existe no repositório

O nome do repositório é o que aparece no endereço da página do modelo, depois de huggingface.co/. Para listar todos os arquivos com o tamanho de cada um:

.\venv\Scripts\hf models ls Tongyi-MAI/Z-Image-Turbo -R

Trecho da resposta (tamanho em bytes, data, caminho):

  3957900840  2025-11-25 15:15:09  text_encoder/model-00001-of-00003.safetensors
  3987450520  2025-11-25 15:15:09  text_encoder/model-00002-of-00003.safetensors
    99630640  2025-11-25 15:15:09  text_encoder/model-00003-of-00003.safetensors
  9973693184  2025-11-25 15:15:09  transformer/diffusion_pytorch_model-00001-of-00003.safetensors
  9973714824  2025-11-25 15:15:09  transformer/diffusion_pytorch_model-00002-of-00003.safetensors
  4672282880  2025-11-25 15:15:09  transformer/diffusion_pytorch_model-00003-of-00003.safetensors
         805  2025-11-25 15:15:09  vae/config.json
   167666902  2025-11-25 15:15:09  vae/diffusion_pytorch_model.safetensors

Um repositório costuma trazer várias peças (o modelo principal, o codificador de texto, o VAE) e nem sempre você precisa de todas.

3. Simular antes de baixar

A opção --dry-run mostra o que seria baixado e quanto ocupa, sem baixar nada:

.\venv\Scripts\hf download Tongyi-MAI/Z-Image-Turbo --dry-run
[dry-run] Will download 31 files (out of 32) totalling 32.7G.

O repositório inteiro soma 32,7 GB. Para simular um arquivo só, ponha o caminho dele depois do nome do repositório:

.\venv\Scripts\hf download Tongyi-MAI/Z-Image-Turbo vae/diffusion_pytorch_model.safetensors --dry-run
[dry-run] Will download 1 files (out of 1) totalling 167.7M.

4. Baixar para uma pasta escolhida

Com --local-dir os arquivos vão para a pasta que você indicar, mantendo as subpastas do repositório. Dá para pedir mais de um arquivo de uma vez:

.\venv\Scripts\hf download Tongyi-MAI/Z-Image-Turbo vae/diffusion_pytorch_model.safetensors vae/config.json --local-dir .\modelos\z-image-turbo

Resultado no teste:

modelos\z-image-turbo\vae\config.json
modelos\z-image-turbo\vae\diffusion_pytorch_model.safetensors
modelos\z-image-turbo\.cache\huggingface\...

A pasta .cache\huggingface criada ali dentro guarda só anotações do download, usadas pelo próprio comando. Pode ficar onde está.

O download de 167,7 MB levou cerca de 11 segundos no teste; o tempo depende da sua conexão.

5. Ou deixar no cache padrão

Sem --local-dir, o arquivo vai para o cache do Hugging Face, que no Windows fica em C:\Users\SEU_USUARIO\.cache\huggingface\hub. O comando .\venv\Scripts\hf env mostra o caminho exato na linha HF_HUB_CACHE. Lá dentro a estrutura é esta:

hub\models--Tongyi-MAI--Z-Image-Turbo\snapshots\f332072aa78be7aecdf3ee76d5c247082da564a6\vae\diffusion_pytorch_model.safetensors

Programas feitos em Python que usam as bibliotecas do Hugging Face procuram os modelos nesse cache sozinhos. Programas com pasta própria de modelos pedem o arquivo na pasta deles, e aí o --local-dir é o caminho.

Para ver o que está no cache e quanto ocupa:

.\venv\Scripts\hf cache ls
id	size	last_accessed	last_modified	refs
model/Tongyi-MAI/Z-Image-Turbo	167.7M	a few seconds ago	a few seconds ago	['main']

E para apagar um repositório do cache e liberar o espaço:

.\venv\Scripts\hf cache rm model/Tongyi-MAI/Z-Image-Turbo

O comando mostra o que vai apagar e pede confirmação. No teste ele liberou os 167,7 MB.

Se o disco C: for pequeno, defina a variável de ambiente HF_HOME com uma pasta de outro disco antes de baixar. No teste, com HF_HOME apontando para outra pasta, o cache inteiro foi criado lá.

Avisos que aparecem e o que significam

  • "cache-system uses symlinks by default... your machine does not support them": no Windows comum o cache não consegue criar atalhos internos. Continua funcionando, mas pode ocupar mais disco quando o mesmo arquivo aparece em mais de uma versão. Segundo o próprio aviso, ativar o Modo de Desenvolvedor do Windows resolve, e a variável HF_HUB_DISABLE_SYMLINKS_WARNING só esconde a mensagem.
  • "You are sending unauthenticated requests to the HF Hub": você está baixando sem conta. Para modelos públicos funciona, só com limites mais baixos de velocidade e de quantidade de pedidos.

O que este teste não cobriu

  • O download do repositório inteiro (32,7 GB) foi só simulado com --dry-run.
  • Modelos de acesso restrito, que pedem aceitar os termos na página e entrar com uma conta, ficaram de fora.
  • Em qual pasta cada programa espera o arquivo depende do programa. A ficha de cada modelo aponta para o exemplo oficial quando ele existe.

Depois de baixar, vale conferir se o arquivo chegou inteiro.

Modelos citados

Fontes