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_WARNINGsó 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.