AskClean

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.

Ilustração conceitual de revisões de modelos ligadas a blocos de dados compartilhados, com arquivos de projeto mantidos à parte
Várias revisões podem compartilhar os mesmos arquivos. Guarde seus próprios checkpoints e o trabalho dos projetos separadamente. Ilustração conceitual.

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.

  1. Encerre os apps e tarefas que usam o cache candidato.
  2. Execute hf cache ls --no-truncate e depois hf cache ls --revisions --no-truncate --show-warnings no caminho de cache verificado.
  3. Confira se algum app ou projeto ainda precisa do repositório e da revisão escolhidos.
  4. 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.

ItemOnde verificarO que conferir antes de remover
Repositório ou revisão do Hubhf cache ls --revisionsConfira a seleção exata. Restaurar pode exigir um novo download e acesso ao mesmo repositório.
Blobs e snapshots compartilhadosCache do Hub verificadoUse o gerenciador de cache: revisões e, em alguns formatos, repositórios podem compartilhar os mesmos arquivos.
Revisões detachedhf cache prune --dry-runUm projeto ainda pode precisar de uma revisão exata, mesmo sem referência nomeada no cache.
Cache de datasets geradosHF_DATASETS_CACHE / controles de cache do DatasetsSeparado dos downloads do Hub; recriar pode exigir tempo de processamento e os dados de origem.
Checkpoints, adapters e código própriosSeu projeto e os locais de backupMantenha 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çãoHF_HOMENã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

Mais guias de armazenamento de modelos e de desenvolvimento