Como limpar o cache do Hugging Face no Mac
Equipe AskClean · Atualizado 2026-11-02
Para recuperar o espaço do cache do Hugging Face no Mac, identifique o cache que o seu app realmente usa, examine-o com hf cache ls e veja a prévia da remoção de um repositório ou de uma revisão específica com hf cache rm --dry-run. Preserve os modelos de que você precisa offline e o seu próprio trabalho. Não apague às cegas blobs compartilhados nem a pasta HF_HOME inteira.

Localize o cache e proteja o seu trabalho
O cache do Hub costuma ficar em ~/.cache/huggingface/hub. A variável HF_HUB_CACHE escolhe diretamente o cache de repositórios do Hub; HF_HOME muda a pasta principal do Hugging Face, que abrange mais dados; sem HF_HOME definida, XDG_CACHE_HOME pode influenciar o padrão; e um argumento cache_dir no app pode escolher outro local. Confira separadamente apps gráficos, kernels de notebook e projetos de linha de comando, porque podem usar ambientes diferentes — uma pasta padrão vazia não quer dizer que não haja modelos no Mac. A pasta HF_HOME também pode conter dados de autenticação: não a apague inteira para limpar downloads de modelos e não inclua o conteúdo dela em pedidos de suporte.
Separe os downloads daquilo que você criou: checkpoints ajustados (fine-tuned), adapters, alterações de tokenizer, resultados de conversão, datasets privados, notebooks, prompts e configuração do projeto. Um modelo base baixado pode estar disponível de novo; um adapter local ou uma receita de conversão podem existir só neste Mac. Faça backup desse trabalho e confira se ele está mesmo no backup — algumas ferramentas pulam caches marcados com CACHEDIR.TAG. Se não souber como restaurar um item e fazer o app voltar a funcionar, mantenha-o por enquanto.
Verificamos estes comandos com o huggingface_hub 2.0.0 em 29/09/2026. Execute antes hf cache --help no seu ambiente; se a sua versão oferecer outros comandos ou opções, siga a documentação dela.
Liste repositórios e revisões antes de escolher
Comece com hf cache ls --no-truncate para ver os identificadores completos dos repositórios e depois execute hf cache ls --revisions --no-truncate --show-warnings para ver os hashes completos das revisões e eventuais problemas no cache; na versão testada, os avisos detalhados ficam ocultos por padrão. Num cache personalizado, passe o mesmo --cache-dir a todos os comandos. Investigue os avisos sobre entradas ilegíveis ou inconsistentes antes de remover algo e não divulgue listas de repositórios privados. O tamanho exibido de uma revisão pode ser maior do que o espaço que a remoção libera, porque snapshots compartilham dados; escolha um alvo específico, como um experimento abandonado, e não decida só pela idade.
- Encerre os apps e tarefas que usam o cache candidato.
- Execute hf cache ls --no-truncate e depois hf cache ls --revisions --no-truncate --show-warnings no caminho de cache verificado.
- Confira se algum app ou projeto ainda precisa do repositório e da revisão escolhidos.
- Anote o tamanho atual da pasta e o espaço livre em disco antes de mudar qualquer coisa.
Veja a prévia antes de confirmar a remoção
O hf cache rm recebe o ID completo de um repositório ou o hash de uma revisão tirados do seu inventário. Para repositórios de modelos, mantenha o prefixo model/ que a CLI mostra; o nome de uma pasta no disco que começa com models-- não é o mesmo identificador. Para uma revisão, use o hash completo e confira a qual repositório ela pertence. Execute primeiro com --dry-run: a prévia resume os alvos e o espaço estimado, mas não lista cada arquivo. Selecionar um repositório abrange todas as revisões dele em cache; para remover só uma, escolha a revisão.
Depois de conferir o alcance, repita o mesmo comando sem --dry-run, com o mesmo alvo e o mesmo diretório de cache, e mantenha o pedido de confirmação ativado. Se a lista mudar de forma inesperada ou a prévia falhar, pare e investigue. Deixe o gerenciador de cache do Hugging Face cuidar dos blobs compartilhados e das referências dos snapshots; apagar arquivos individuais no Finder pode afetar outras revisões que precisam deles.
A remoção do cache apaga os arquivos diretamente, sem passar pelo Lixo. Para restaurar uma revisão removida, você vai precisar de um backup funcional ou de um novo download. Mantenha o backup até as verificações passarem, principalmente no caso de modelos privados, com acesso restrito (gated), que não estão mais publicados, que foram modificados localmente ou que você usa offline.
Use o prune com cautela e separe os outros caches
Na versão 2.0.0 testada, hf cache prune --dry-run mostra revisões detached e downloads incompletos. Uma revisão detached não tem referência nomeada no cache, mas um projeto ainda pode pedir exatamente essa revisão; confira os seus projetos antes de aprovar a remoção. Na primeira limpeza, uma remoção explícita é mais fácil de avaliar do que uma varredura ampla. Se depois decidir usar o prune, aplique a mesma checagem a todos os candidatos e pare antes os downloads ativos: um arquivo incompleto pode ser de uma transferência que outro processo ainda está fazendo.
Os dados gerados pelo Hugging Face Datasets em HF_DATASETS_CACHE são diferentes dos downloads do Hub, e remover downloads do Hub não apaga necessariamente esses dados. Os downloads feitos com local_dir vão para uma pasta escolhida por você ou pelo app; trate-a à parte do cache compartilhado e preserve os scripts e as edições que você fez — um novo download não traz de volta suas alterações locais. O armazenamento de transferências do Xet também é separado. Se o uso de disco continuar alto, examine cada categoria restante por conta própria.
Confira se os modelos que ficaram ainda funcionam
Repita o inventário e as medições de disco, carregue um modelo e uma revisão que você quis manter e execute uma tarefa pequena com resultado conhecido; importar uma biblioteca Python não basta para testar os arquivos do modelo. Se precisar de acesso offline, teste com a rede realmente desconectada. Se a próxima execução baixar o mesmo modelo de novo, a limpeza pode ter removido dados de que o trabalho ainda precisa — reveja a seleção, a capacidade ou o local do cache em vez de apagar e baixar repetidamente.
Se uma verificação falhar, pause a limpeza: anote localmente o modelo, a revisão, o caminho do cache e o erro, confira se o app usa o ambiente que você examinou e restaure o backup ou baixe a revisão necessária depois de confirmar o acesso e o espaço livre. Resolva a falha antes de remover outra entrada. Se os modelos que você usa sempre não couberem no Mac, um disco externo pode ajudar: confira o espaço livre, as permissões e o suporte a links simbólicos, preserve esses links e os arquivos para onde eles apontam ao copiar, configure cada app para usar o novo local e teste os modelos ali antes de remover o original. Mantenha o disco conectado sempre que esses apps precisarem dele.
Como verificamos estes comandos
Em 29/09/2026, criamos offline um cache temporário no formato do Hub, com duas revisões sintéticas, um blob compartilhado e um blob exclusivo para cada revisão. Com o huggingface_hub 2.0.0, a listagem de revisões funcionou, as prévias de rm e de prune não alteraram os arquivos de teste, e remover a revisão antiga preservou a revisão atual e os dados compartilhados, apagando apenas o blob exclusivo antigo. Uma segunda verificação offline confirmou que --show-warnings revela uma entrada de cache malformada de propósito, que --no-truncate mantém o ID completo da revisão e que as prévias aceitam tanto um ID de repositório com prefixo de tipo quanto o hash completo de uma revisão.
Esses testes usaram arquivos sintéticos em pastas temporárias. Não testamos downloads reais de modelos, inferência, o cache de um usuário, migração para outro disco nem a limpeza de blobs compartilhados entre repositórios, e eles não indicam quantos gigabytes o seu Mac vai liberar. Investigue um cache danificado ou personalizado antes de remover entradas.
O AskClean ajuda a ver onde o espaço está sendo usado no Mac. A varredura e a prévia são gratuitas; a análise por IA e a limpeza exigem o Pro, e a limpeza de disco exclui permanentemente os itens confirmados. Use a CLI do Hugging Face para gerenciar as revisões em cache e os arquivos compartilhados, e deixe o trabalho original dos seus projetos fora da seleção de limpeza.
O que pode ser recriado e o que precisa ser mantido
Confira cada categoria separadamente. A tabela explica o que você precisa preservar ou restaurar; ela não marca arquivos para exclusão automática.
| Item | Onde verificar | O que conferir antes de remover |
|---|---|---|
| Repositório ou revisão do Hub | hf cache ls --revisions | Confira a seleção exata. Restaurar pode exigir um novo download e acesso ao mesmo repositório. |
| Blobs e snapshots compartilhados | Cache do Hub verificado | Use o gerenciador de cache: revisões e, em alguns formatos, repositórios podem compartilhar os mesmos arquivos. |
| Revisões detached | hf cache prune --dry-run | Um projeto ainda pode precisar de uma revisão exata, mesmo sem referência nomeada no cache. |
| Cache de datasets gerados | HF_DATASETS_CACHE / controles de cache do Datasets | Separado dos downloads do Hub; recriar pode exigir tempo de processamento e os dados de origem. |
| Checkpoints, adapters e código próprios | Seu projeto e os locais de backup | Mantenha o trabalho original e confirme que o backup o inclui, principalmente se ele estiver dentro de uma pasta de cache. |
| Pasta principal do Hugging Face e autenticação | HF_HOME | Não apague a pasta inteira para remover entradas do cache de modelos. |
O teste local usou um cache sintético minúsculo. O tamanho desse cache de teste não é um benchmark nem uma estimativa de economia real.
Perguntas frequentes
Posso apagar a pasta ~/.cache/huggingface no Mac?
Não trate a pasta inteira como descartável. Localize o cache do Hub ativo, preserve os dados de autenticação e o seu trabalho original e veja a prévia de repositórios ou revisões específicos com o hf cache instalado.
Por que remover uma revisão libera menos espaço que o tamanho exibido?
Revisões podem compartilhar arquivos e, em alguns formatos de cache, repositórios também. Confira a estimativa da prévia e compare o uso de disco e o espaço livre antes e depois. Somar os tamanhos exibidos das revisões pode contar os mesmos arquivos mais de uma vez.
Uma revisão detached quer dizer que nenhum app a usa?
Não. Um projeto pode fixar uma revisão exata mesmo sem referência nomeada no cache. Confira os requisitos do projeto antes de usar o prune.
Meus modelos vão funcionar offline depois da limpeza?
Só os arquivos em cache mantidos e completos atendem às tarefas que precisam deles. Teste o carregamento de um modelo representativo offline antes de apagar o backup ou de depender do Mac desconectado.
O hf cache rm pode apagar meu modelo ajustado?
Pode, se os seus arquivos estiverem dentro da entrada de cache escolhida. Mantenha checkpoints, adapters e arquivos modificados fora das entradas que pretende remover e confira os backups. Uma pasta chamada cache ainda pode guardar a única cópia de um trabalho importante.
Fontes