Como revisar e limpar o cache do Hugging Face no Mac
Equipe AskClean · Atualizado 2026-09-29
Localize o cache realmente usado pelo app, examine-o com hf cache ls e confira um alvo específico com hf cache rm --dry-run. Preserve modelos necessários offline e seu próprio trabalho. Não exclua blobs compartilhados manualmente nem apague todo HF_HOME.
Localizar o cache e proteger seu trabalho
O caminho habitual é ~/.cache/huggingface/hub. HF_HUB_CACHE define o cache dos repositórios; HF_HOME abrange mais dados. Sem HF_HOME, XDG_CACHE_HOME pode influenciar o padrão, e cache_dir pode escolher outro local. Confira separadamente apps gráficos, terminal e notebook. HF_HOME pode conter autenticação: não apague tudo nem publique seu conteúdo.
Checkpoints ajustados, adapters, alterações de tokenizer, conversões, dados privados e configurações podem não ser baixados novamente. Valide o backup: algumas ferramentas ignoram caches marcados com CACHEDIR.TAG. Preserve o que não souber restaurar e não decida apenas pela data do último acesso.
Exibir IDs completos e avisos
Pare os apps, downloads e tarefas que usam o cache. Execute hf cache ls --no-truncate e depois hf cache ls --revisions --no-truncate --show-warnings. A versão testada oculta avisos detalhados por padrão. Use o mesmo --cache-dir em todos os comandos para um cache personalizado. Investigue erros de leitura ou estrutura, registre uso e espaço livre e não divulgue listas de repositórios privados.
Revisar o alcance antes de confirmar
hf cache rm recebe o ID completo da CLI. Mantenha model/ para repositórios de modelos; não use o nome de uma pasta que começa com models--. Para uma revisão, use o hash completo e confira o repositório. Comece com --dry-run. A saída resume alvos e espaço estimado, não cada arquivo. Selecionar um repositório abrange todas as revisões dele em cache.
Após conferir, retire --dry-run mantendo alvo, caminho e pedido de confirmação. Se a seleção mudar ou a prévia falhar, interrompa a exclusão e investigue. Arquivos são excluídos diretamente, sem Lixeira; a restauração precisa de backup ou novo acesso ao download. Snapshots, e em alguns formatos repositórios, compartilham blobs. Deixe o gerenciador tratar as referências e não some simplesmente os tamanhos exibidos.
Distinguir prune dos outros caches
Na versão 2.0.0 testada, hf cache prune --dry-run mostra revisões detached e downloads incompletos. Mesmo sem referência nomeada, um projeto pode fixar uma revisão exata. Confira cada alvo e pare downloads ativos. Comece por um único item bem identificado.
Dados gerados em HF_DATASETS_CACHE são diferentes dos downloads do Hub. Verifique transferências Xet e saídas local_dir separadamente, preservando alterações locais. Apagar HF_HOME não substitui essa análise.
Carregar os modelos preservados
Repita as medições, carregue os modelos e revisões necessários e execute uma tarefa pequena com resultado conhecido. Importar uma biblioteca Python não basta. Teste o uso offline com a rede realmente desconectada. Em caso de falha, pare a limpeza e confira ambiente, caminhos, arquivos, acesso e espaço antes de restaurar. Baixar repetidamente um modelo necessário indica que é preciso rever a seleção ou a capacidade.
Ao mover para um disco externo, confira espaço, permissões e suporte a links simbólicos. Copie os links e seus destinos, configure cada app e teste seus modelos antes de retirar o original. Mantenha o disco conectado durante o uso.
O que foi verificado
Em 2026-09-29, caches sintéticos temporários foram testados offline com huggingface_hub 2.0.0: listagem, IDs completos, avisos e dry-run. Prévias não mudaram arquivos; remover uma revisão antiga preservou a atual e os dados compartilhados. Não foram validados inferência real, caches de usuários, limpeza de blobs entre repositórios ou migração de disco. Não há promessa de espaço fixo. Confira sua versão com hf cache --help.
O que verificar antes de excluir
Confirme o local, a finalidade e como recuperar cada item. A tabela não é uma lista de exclusão automática nem garante um volume fixo de espaço livre.
| Item | Onde verificar | Consequências e condições |
|---|---|---|
| Repositório ou revisão | hf cache ls --revisions | Confirme o alcance exato e o acesso para novos downloads. |
| Dados compartilhados | blob / snapshot | Deixe as referências com o gerenciador e não some os tamanhos. |
| Revisão detached | hf cache prune --dry-run | Um projeto ainda pode depender exatamente dessa revisão. |
| Dados gerados | HF_DATASETS_CACHE | Recriar exige dados de origem e tempo de processamento. |
| Modelos e trabalho próprios | checkpoint / adapter | Guarde os originais e confira o conteúdo real dos backups. |
| Diretório principal Hugging Face | HF_HOME | Pode conter dados de autenticação; não exclua a pasta inteira. |
Perguntas frequentes
Uma revisão detached não é mais usada?
Não necessariamente. Um projeto pode fixar a revisão exata mesmo sem referência nomeada. Verifique as dependências primeiro.
hf cache rm pode apagar meu modelo ajustado?
Sim, se estiver dentro do alvo escolhido. Preserve-o fora da seleção e valide seu backup. O nome cache não torna seu trabalho descartável.
Fontes