# Variáveis de ambiente `huggingface_hub` pode ser configurado usando variáveis de ambiente. Se você não está familiarizado com variáveis de ambiente, aqui estão artigos genéricos sobre elas [no macOS e Linux](https://linuxize.com/post/how-to-set-and-list-environment-variables-in-linux/) e no [Windows](https://phoenixnap.com/kb/windows-set-environment-variable). Esta página o guiará por todas as variáveis de ambiente específicas do `huggingface_hub` e seu significado. > [!TIP] > Todas as variáveis de ambiente são lidas no momento da importação de `huggingface_hub`. Qualquer modificação feita posteriormente não será levada em consideração. Certifique-se de definir suas variáveis de ambiente antes de importar `huggingface_hub`. ## Genérico ### HF_INFERENCE_ENDPOINT Para configurar a URL base da API de inferência. Você pode querer definir esta variável se a sua organização estiver apontando para um API Gateway em vez de diretamente para a API de inferência. Padrão é `"https://api-inference.huggingface.co"`. ### HF_HOME Para configurar onde `huggingface_hub` armazenará os dados localmente. Em particular, seu token e o cache serão armazenados nesta pasta. Padrão é `"~/.cache/huggingface"`, a menos que [XDG_CACHE_HOME](#xdgcachehome) esteja definido. ### HF_HUB_CACHE Para configurar onde os repositórios do Hub serão armazenados em cache localmente (modelos, conjuntos de dados e espaços). Padrão é `"$HF_HOME/hub"` (por exemplo, `"~/.cache/huggingface/hub"` por padrão). ### HF_XET_CACHE Para configurar onde o Xet armazena o cache de shards e os dados de staging de upload localmente. Consulte [Xet caching](../guides/manage-cache#xet-caching) para mais detalhes. Padrão é `"$HF_HOME/xet"` (por exemplo, `"~/.cache/huggingface/xet"` por padrão). ### HF_ASSETS_CACHE Para configurar onde os [assets](../guides/manage-cache#caching-assets) criados por bibliotecas de nível inferior serão armazenados em cache localmente. Esses assets podem ser dados pré-processados, arquivos baixados do GitHub, logs, etc. Padrão é `"$HF_HOME/assets"` (por exemplo, `"~/.cache/huggingface/assets"` por padrão). ### HF_TOKEN Para configurar o User Access Token para autenticar no Hub. Se definido, este valor substituirá o token armazenado na máquina (em `$HF_TOKEN_PATH` ou `"$HF_HOME/token"`, se o primeiro não estiver definido). Para mais detalhes sobre autenticação, consulte [esta seção](../quick-start#authentication). ### HF_TOKEN_PATH Para configurar onde `huggingface_hub` deve armazenar o User Access Token. O padrão é `"$HF_HOME/token"` (por exemplo, `~/.cache/huggingface/token` por padrão). ### HF_HUB_VERBOSITY Defina o nível de verbosidade do logger do `huggingface_hub`. Deve ser um dos valores `{"debug", "info", "warning", "error", "critical"}`. Padrão é `"warning"`. Para mais detalhes, consulte a [referência de registro](../package_reference/utilities#huggingface_hub.utils.logging.get_verbosity). ### HF_HUB_ETAG_TIMEOUT Valor inteiro para definir o número de segundos a aguardar pela resposta do servidor ao buscar os metadados mais recentes de um repositório antes de baixar um arquivo. Se a solicitação expirar, o `huggingface_hub` usará os arquivos em cache local por padrão. Definir um valor menor acelera o fluxo de trabalho para máquinas com conexão lenta que já possuem arquivos em cache. Um valor maior garante que a chamada de metadados tenha sucesso em mais casos. O padrão é 10s. ### HF_HUB_DOWNLOAD_TIMEOUT Valor inteiro para definir o número de segundos a aguardar pela resposta do servidor ao baixar um arquivo. Se a solicitação exceder o tempo limite, um TimeoutError será lançado. Definir um valor maior é benéfico em máquinas com conexão lenta. Um valor menor faz com que o processo falhe mais rapidamente em caso de interrupção total da rede. O valor padrão é de 10s. ## Xet ### Outras variáveis de ambiente do Xet * [`HF_HUB_DISABLE_XET`](../package_reference/environment_variables#hfhubdisablexet) * [`HF_XET_CACHE`](../package_reference/environment_variables#hfxetcache) * [`HF_XET_HIGH_PERFORMANCE`](../package_reference/environment_variables#hfxethighperformance) * [`HF_XET_RECONSTRUCT_WRITE_SEQUENTIALLY`](../package_reference/environment_variables#hfxetreconstructwritesequentially) ### HF_XET_CHUNK_CACHE_SIZE_BYTES Esta variável não tem mais nenhum efeito. `hf_xet` não usa mais um cache local de chunks para downloads, e definir esta variável não o habilita. Consulte [xet-core#715](https://github.com/huggingface/xet-core/issues/715) para mais detalhes. ### HF_XET_SHARD_CACHE_SIZE_LIMIT Para definir o tamanho do cache de shards do Xet localmente. Aumentar esse valor melhora a eficiência do upload, pois os chunks referenciados em arquivos de shard em cache não são reenviados. Observe que o limite suave padrão provavelmente é suficiente para a maioria das cargas de trabalho. Padrão é `16000000000` (16GB). ### HF_XET_NUM_CONCURRENT_RANGE_GETS Esta variável não é mais usada. Desde a versão 1.3.0 do `hf_xet`, a concorrência de download é controlada de forma adaptativa. ## Valores booleanos As variáveis de ambiente a seguir esperam um valor booleano. A variável será considerada como `True` se seu valor for um dos `{"1", "ON", "YES", "TRUE"}` (sem distinção entre maiúsculas e minúsculas). Qualquer outro valor (ou indefinido) será considerado como `False`. ### HF_DEBUG Se definido, o nível de log do logger `huggingface_hub` é definido como DEBUG. Além disso, todas as solicitações feitas pelas bibliotecas da HF serão registradas como comandos cURL equivalentes para facilitar a depuração e a reprodutibilidade. ### HF_HUB_OFFLINE Se definido, nenhuma chamada HTTP será feita ao Hugging Face Hub. Se você tentar baixar arquivos, apenas os arquivos em cache serão acessados. Se nenhum arquivo em cache for detectado, um erro será lançado. Isso é útil caso sua rede esteja lenta e você não se importe em ter a versão mais recente de um arquivo. Se `HF_HUB_OFFLINE=1` estiver definido como variável de ambiente e você chamar qualquer método de [HfApi](/docs/huggingface_hub/main/pt/package_reference/hf_api#huggingface_hub.HfApi), uma exceção [OfflineModeIsEnabled](/docs/huggingface_hub/main/pt/package_reference/utilities#huggingface_hub.errors.OfflineModeIsEnabled) será lançada. **Observação:** mesmo que a versão mais recente de um arquivo esteja em cache, a chamada de `hf_hub_download` ainda dispara uma requisição HTTP para verificar se uma nova versão não está disponível. Definir `HF_HUB_OFFLINE=1` ignora essa chamada, o que acelera o tempo de carregamento. Se você deseja verificar se o modo offline está ativado ou não, pode usar o auxiliar [is_offline_mode()](/docs/huggingface_hub/main/pt/package_reference/utilities#huggingface_hub.is_offline_mode). ### HF_HUB_DISABLE_IMPLICIT_TOKEN A autenticação não é obrigatória para todas as solicitações ao Hub. Por exemplo, solicitar detalhes sobre o modelo `"gpt2"` não requer autenticação. No entanto, se um usuário estiver [conectado](../package_reference/login), o comportamento padrão será enviar o token sempre, a fim de facilitar a experiência do usuário (nunca receber um HTTP 401 Unauthorized) ao acessar repositórios privados ou com acesso restrito. Por privacidade, você pode desabilitar esse comportamento definindo `HF_HUB_DISABLE_IMPLICIT_TOKEN=1`. Nesse caso, o token será enviado apenas para chamadas com "write-access" (exemplo: criar um commit). **Observação:** desabilitar o envio implícito do token pode ter efeitos colaterais inesperados. Por exemplo, se você quiser listar todos os modelos no Hub, seus modelos privados não serão listados. Você precisará passar explicitamente o argumento `token=True` no seu script. ### HF_HUB_DISABLE_PROGRESS_BARS Para tarefas demoradas, `huggingface_hub` exibe uma barra de progresso por padrão (usando tqdm). Você pode desativar todas as barras de progresso de uma vez definindo `HF_HUB_DISABLE_PROGRESS_BARS=1`. ### HF_HUB_DISABLE_SYMLINKS Se definido, o `huggingface_hub` nunca criará links simbólicos no cache. Em vez disso, os arquivos serão duplicados ou movidos diretamente para os diretórios de snapshot. Este é um recurso para usuários avançados que faz o diretório de cache operar em um modo degradado, no qual arquivos enormes acabam sendo duplicados no seu disco rígido. Um caso de uso é quando uma unidade de rede compartilhada (por exemplo, NAS) é usada como `HF_HUB_CACHE` entre máquinas que executam diferentes sistemas operacionais. Links simbólicos criados no Linux nem sempre são acessíveis no Windows, o que leva a erros. Definir `HF_HUB_DISABLE_SYMLINKS=1` evita esse problema, com o custo da deduplicação de espaço em disco. ### HF_HUB_DISABLE_SYMLINKS_WARNING Se você está em uma máquina Windows, é recomendável ativar o modo de desenvolvedor ou executar `huggingface_hub` em modo de administrador. Caso contrário, `huggingface_hub` não será capaz de criar links simbólicos no seu sistema de cache. Você poderá executar qualquer script, mas sua experiência de usuário será degradada, pois alguns arquivos grandes podem acabar duplicados no seu disco rígido. Uma mensagem de aviso é acionada para alertá-lo sobre esse comportamento. Defina `HF_HUB_DISABLE_SYMLINKS_WARNING=1` para desativar esse aviso. Para mais detalhes, consulte [limitações de cache](../guides/manage-cache#limitations). ### HF_HUB_DISABLE_EXPERIMENTAL_WARNING Algumas funcionalidades do `huggingface_hub` são experimentais. Isso significa que você pode usá-las, mas não garantimos que serão mantidas no futuro. Em particular, podemos atualizar a API ou o comportamento dessas funcionalidades sem nenhum ciclo de depreciação. Uma mensagem de aviso é exibida ao usar uma funcionalidade experimental para alertá-lo sobre isso. Se você estiver confortável para depurar possíveis problemas ao usar uma funcionalidade experimental, pode definir `HF_HUB_DISABLE_EXPERIMENTAL_WARNING=1` para desativar o aviso. Se você estiver usando um recurso experimental, por favor, nos avise! Seu feedback pode nos ajudar a projetá-lo e melhorá-lo. ### HF_HUB_DISABLE_TELEMETRY Por padrão, alguns dados são coletados pelas bibliotecas da HF (`transformers`, `datasets`, `gradio`,..) para monitorar o uso, depurar problemas e ajudar a priorizar recursos. Cada biblioteca define sua própria política (ou seja, qual uso monitorar), mas a implementação central ocorre em `huggingface_hub` (veja `send_telemetry`). Você pode definir `HF_HUB_DISABLE_TELEMETRY=1` como variável de ambiente para desativar a telemetria globalmente. ### HF_HUB_DISABLE_UPDATE_CHECK Por padrão, o CLI `hf` verifica no PyPI se há uma nova versão disponível na inicialização (no máximo uma vez a cada 24 horas) e exibe um aviso de uma linha em amarelo no stderr quando uma versão está disponível, sugerindo `hf update`. A verificação já é um no-op em versões de desenvolvimento e pré-lançamento. Ele também verifica (no máximo uma vez a cada 24 horas, puramente localmente) se a skill `hf-cli` está instalada e gerada pela versão em execução, e sugere `hf skills add` / `hf skills update` caso contrário. A verificação apenas exibe uma dica, nunca altera seus diretórios de skills. Antes de executar uma [extensão de CLI](../guides/cli-extensions) instalada, ela verifica (no máximo uma vez a cada 24 horas por extensão) se um commit mais recente está disponível no GitHub e sugere `hf extensions update ` em caso afirmativo. `hf extensions list` usa a mesma verificação para sua coluna `LATEST`. Defina `HF_HUB_DISABLE_UPDATE_CHECK=1` para ignorar essas solicitações e silenciar todas essas dicas. Útil em ambientes de CI offline ou quando você prefere uma saída de shell mais silenciosa. ### HF_HUB_DISABLE_XET Defina para desabilitar o uso de `hf-xet`, mesmo que ele esteja disponível no seu ambiente Python. Isso ocorre porque o `hf-xet` será usado automaticamente se for encontrado, e isso permite desabilitar explicitamente seu uso. Se você estiver desabilitando o Xet, considere [abrir uma issue e incluir as informações de diagnóstico](https://github.com/huggingface/xet-core?tab=readme-ov-file#issues-diagnostics--debugging) para nos ajudar a entender por que o Xet não está funcionando para você. ### HF_HUB_ENABLE_HF_TRANSFER > [!WARNING] > Esta é uma variável de ambiente obsoleta. Agora que o Hugging Face Hub é totalmente operado pelo backend de armazenamento Xet, todas as transferências de arquivos passam pelo pacote binário `hf-xet`. Ele fornece transferências eficientes usando uma estratégia de deduplicação baseada em blocos e se integra perfeitamente ao `huggingface_hub`. Isso significa que o `hf_transfer` não pode mais ser usado. Se você estiver interessado em maior desempenho, confira a [seção `HF_XET_HIGH_PERFORMANCE`](#hf_xet_high_performance) ### HF_HUB_DISABLE_SHARED_BLOBS Defina como `1` para desabilitar o armazenamento de blobs compartilhado em todo o cache. Por padrão, os arquivos Xet baixados com sucesso são armazenados em `/blobs//` e vinculados por symlink aos caches dos repositórios, de modo que arquivos idênticos são armazenados no disco apenas uma vez entre os repositórios e podem ser reutilizados sem necessidade de novo download. Essa otimização é habilitada por padrão, mas é desabilitada se o Xet não estiver disponível (por exemplo, se `HF_HUB_DISABLE_XET=1` estiver definido) ou se os symlinks não forem suportados localmente. Nesses casos, o sistema recorre silenciosamente ao armazenamento local regular do repositório. Consulte o [guia de cache](../guides/manage-cache#shared-blobs-across-repos) para mais detalhes. ### HF_XET_HIGH_PERFORMANCE Defina `hf-xet` para operar com configurações aumentadas, a fim de maximizar os recursos de rede e disco na máquina. A ativação do modo de alto desempenho tentará saturar a largura de banda de rede desta máquina e utilizar todos os núcleos de CPU para atividade paralela de upload/download. Considere isso como análogo à variável de ambiente legada `HF_HUB_ENABLE_HF_TRANSFER=1`, mas aplicada ao `hf-xet`. Para saber mais sobre os benefícios do armazenamento Xet e do `hf_xet`, consulte esta [seção](https://huggingface.co/docs/hub/xet/index). ### HF_XET_RECONSTRUCT_WRITE_SEQUENTIALLY Esta variável não é mais usada. Desde a versão 1.3.0 do `hf_xet`, os arquivos são sempre gravados no disco local de forma sequencial (veja o [gravador de arquivos na v1.3.0](https://github.com/huggingface/xet-core/blob/v1.3.0/file_reconstruction/src/data_writer/data_writer.rs#L76-L91)). ## Variáveis de ambiente obsoletas Para padronizar todas as variáveis de ambiente no ecossistema do Hugging Face, algumas variáveis foram marcadas como descontinuadas. Embora continuem funcionais, elas não têm mais precedência sobre suas substitutas. A tabela a seguir detalha as variáveis descontinuadas e suas respectivas alternativas: | Variável Obsoleta | Substituição | | --------------------------- | ------------------ | | `HUGGINGFACE_HUB_CACHE` | `HF_HUB_CACHE` | | `HUGGINGFACE_ASSETS_CACHE` | `HF_ASSETS_CACHE` | | `HUGGING_FACE_HUB_TOKEN` | `HF_TOKEN` | ## De ferramentas externas Algumas variáveis de ambiente não são específicas do `huggingface_hub`, mas ainda assim são levadas em consideração quando definidas. ### DO_NOT_TRACK Valor booleano. Equivalente a `HF_HUB_DISABLE_TELEMETRY`. Quando definido como true, a telemetria é desativada globalmente no ecossistema Python do Hugging Face (`transformers`, `diffusers`, `gradio`, etc.). Veja https://donottrack.sh/ para mais detalhes. ### NO_COLOR Valor booleano. Quando definido, o CLI `hf` não exibirá nenhuma cor ANSI. Consulte [no-color.org](https://no-color.org/). ### XDG_CACHE_HOME Usado apenas quando `HF_HOME` não está definido! Esta é a forma padrão de configurar onde [dados não essenciais (em cache) específicos do usuário devem ser gravados](https://wiki.archlinux.org/title/XDG_Base_Directory) em máquinas linux. Se `HF_HOME` não estiver definido, o diretório padrão será `"$XDG_CACHE_HOME/huggingface"` em vez de `"~/.cache/huggingface"`.