Hub Python Library documentation
환경 변수
환경 변수
huggingface_hub는 환경 변수를 사용하여 구성할 수 있습니다.
환경 변수에 익숙하지 않다면, macOS와 Linux 및 Windows에 대한 일반적인 아티클을 참고하세요.
이 페이지에서는 huggingface_hub에 특화된 모든 환경 변수와 그 의미를 안내합니다.
모든 환경 변수는
huggingface_hub가 import될 때 읽힙니다. 이후에 이루어지는 변경 사항은 반영되지 않습니다.huggingface_hub를 import하기 전에 환경 변수를 설정했는지 확인하세요.
일반
HF_INFERENCE_ENDPOINT
추론 API 기본 URL을 구성합니다. 조직이 추론 API가 아닌 API 게이트웨이를 가리키도록 설정한 경우 이 변수를 설정할 수 있습니다.
"https://huggingface.co/proxy/api-inference.huggingface.co"가 기본값입니다.
HF_HOME
huggingface_hub가 데이터를 로컬에 저장할 위치를 설정합니다. 특히, 토큰과 캐시가 이 폴더에 저장됩니다.
XDG_CACHE_HOME가 설정되지 않은 경우 기본값은 "~/.cache/huggingface"입니다.
HF_HUB_CACHE
Hub의 저장소(모델, 데이터셋, 스페이스)가 로컬에 캐시되는 위치를 구성합니다.
기본값은 "$HF_HOME/hub"입니다(기본적으로 "~/.cache/huggingface/hub").
HF_XET_CACHE
Xet이 로컬에 샤드 캐시와 업로드 스테이징 데이터를 저장할 위치를 구성합니다. 자세한 내용은 Xet 캐싱을 참조하세요.
기본값은 "$HF_HOME/xet"입니다(기본적으로 "~/.cache/huggingface/xet").
HF_ASSETS_CACHE
다운스트림 라이브러리가 생성한 assets가 로컬에 캐시될 위치를 설정합니다. 해당 assets에는 전처리된 데이터, GitHub에서 다운로드한 파일, 로그 등이 포함될 수 있습니다.
기본값은 "$HF_HOME/assets"입니다 (기본적으로 "~/.cache/huggingface/assets").
HF_TOKEN
Hub 인증을 위한 User Access Token을 구성합니다. 이 값이 설정된 경우, 해당 값은 머신에 저장된 토큰($HF_TOKEN_PATH 또는 전자가 설정되지 않은 경우 "$HF_HOME/token")을 덮어씁니다.
인증에 대한 자세한 내용은 이 섹션을 확인하세요.
HF_TOKEN_PATH
huggingface_hub이 User Access Token을 저장할 위치를 설정합니다. 기본값은 "$HF_HOME/token"입니다(기본적으로 ~/.cache/huggingface/token).
HF_HUB_VERBOSITY
huggingface_hub 로거의 상세 수준을 설정합니다. {"debug", "info", "warning", "error", "critical"} 중 하나여야 합니다.
기본값은 "warning"입니다.
자세한 내용은 로깅 참조를 참조하세요.
HF_HUB_ETAG_TIMEOUT
리포지토리에서 파일을 다운로드하기 전에 최신 메타데이터를 가져올 때 서버 응답을 기다릴 초수를 정의하는 정수 값입니다. 요청이 시간 초과되면 huggingface_hub는 기본적으로 로컬에 캐시된 파일을 사용합니다. 이미 파일이 캐시된 느린 연결의 머신에서 더 낮은 값을 설정하면 워크플로가 빨라집니다. 더 높은 값은 메타데이터 호출이 더 많은 경우에서 성공하도록 보장합니다. 기본값은 10초입니다.
HF_HUB_DOWNLOAD_TIMEOUT
파일 다운로드 시 서버 응답을 기다릴 초 수를 정의하는 정수 값입니다. 요청이 시간 초과되면 TimeoutError가 발생하며, 연결 속도가 느린 머신에서는 더 높은 값을 설정하는 것이 유리합니다. 네트워크가 완전히 중단된 경우, 더 작은 값은 프로세스가 더 빠르게 실패하도록 만듭니다. 기본값은 10초입니다.
Xet
기타 Xet 환경 변수
HF_XET_CHUNK_CACHE_SIZE_BYTES
이 변수는 더 이상 효과가 없습니다. hf_xet는 더 이상 다운로드에 로컬 청크 캐시를 사용하지 않으며, 이 변수를 설정해도 로컬 청크 캐시를 활성화하지 않습니다. 자세한 내용은 xet-core#715를 참조하세요.
HF_XET_SHARD_CACHE_SIZE_LIMIT
로컬에서 Xet 샤드 캐시의 크기를 설정합니다. 이 값을 증가시키면 캐시된 샤드 파일에 참조된 청크가 다시 업로드되지 않으므로 업로드 효율이 향상됩니다. 대부분의 워크로드에는 기본 소프트 제한이 충분할 가능성이 높다는 점을 참고하세요.
기본값은 16000000000(16GB)입니다.
HF_XET_NUM_CONCURRENT_RANGE_GETS
이 변수는 더 이상 사용되지 않습니다. hf_xet 1.3.0부터 다운로드 동시성은 적응적으로 제어됩니다.
부울 값
다음 환경 변수는 boolean 값을 기대합니다. 변수의 값이 {"1", "ON", "YES", "TRUE"} 중 하나(대소문자 구분 없음)인 경우 True로 간주됩니다. 그 외의 값(또는 정의되지 않은 경우)은 False로 간주됩니다.
HF_DEBUG
설정된 경우, huggingface_hub 로거의 로그 수준이 DEBUG로 설정됩니다. 또한, HF 라이브러리가 수행하는 모든 요청은 디버깅 및 재현성을 쉽게 하기 위해 동등한 cURL 명령으로 기록됩니다.
HF_HUB_OFFLINE
설정된 경우, Hugging Face Hub에 HTTP 호출이 수행되지 않습니다. 파일을 다운로드하려고 하면 캐시된 파일만 접근됩니다. 캐시 파일이 감지되지 않으면 오류가 발생합니다. 네트워크가 느리고 파일의 최신 버전이 필요하지 않은 경우에 유용합니다.
HF_HUB_OFFLINE=1이 환경 변수로 설정되어 있고 HfApi의 어떤 메서드를 호출하면 OfflineModeIsEnabled 예외가 발생합니다.
참고: 파일의 최신 버전이 캐시에 저장되어 있더라도 hf_hub_download을 호출하면 새 버전이 없는지 확인하기 위해 HTTP 요청이 전송됩니다. HF_HUB_OFFLINE=1을 설정하면 이 호출이 건너뛰어져 로딩 시간이 단축됩니다.
오프라인 모드가 활성화되어 있는지 확인하려면 is_offline_mode() 헬퍼를 사용할 수 있습니다.
HF_HUB_DISABLE_IMPLICIT_TOKEN
Hub에 대한 모든 요청에서 인증이 필수적인 것은 아닙니다. 예를 들어, "gpt2" 모델에 대한 세부 정보를 요청하는 경우 인증이 필요하지 않습니다. 그러나 사용자가 로그인된 상태라면, 개인 또는 게이트된 저장소에 접근할 때 사용자 경험을 향상시키기 위해(HTTP 401 Unauthorized 오류가 발생하지 않도록) 기본적으로 토큰을 항상 전송합니다. 프라이버시를 위해 이 동작을 비활성화하려면 HF_HUB_DISABLE_IMPLICIT_TOKEN=1을 설정할 수 있습니다. 이 경우 토큰은 “쓰기 접근” 호출(예: 커밋 생성)에만 전송됩니다.
참고: 토큰의 암시적 전송을 비활성화하면 예상치 못한 부작용이 발생할 수 있습니다. 예를 들어, Hub의 모든 모델을 나열하려고 할 경우 개인 모델이 목록에 표시되지 않습니다. 이 경우 스크립트에서 token=True 인수를 명시적으로 전달해야 합니다.
HF_HUB_DISABLE_PROGRESS_BARS
시간이 오래 걸리는 작업의 경우, huggingface_hub은 기본적으로 진행률 표시줄을 표시합니다(tqdm 사용). HF_HUB_DISABLE_PROGRESS_BARS=1을 설정하면 모든 진행률 표시줄을 한 번에 비활성화할 수 있습니다.
HF_HUB_DISABLE_SYMLINKS
설정된 경우, huggingface_hub는 캐시에 심볼릭 링크를 절대 생성하지 않습니다. 대신 파일이 중복되거나 스냅샷 디렉터리로 직접 이동됩니다. 이는 고급 사용자용 기능으로, 캐시 디렉터리가 하드 드라이브에 대용량 파일이 중복 저장되는 열화된 모드로 작동하게 만듭니다.
예를 들어, 서로 다른 운영 체제를 실행하는 여러 머신에서 공유 네트워크 드라이브(예: NAS)를 HF_HUB_CACHE로 사용하는 경우가 있습니다. Linux에서 생성된 심볼릭 링크는 Windows에서 항상 접근할 수 있는 것이 아니므로 오류가 발생할 수 있습니다. HF_HUB_DISABLE_SYMLINKS=1을 설정하면 디스크 공간 중복 제거 기능이 비활성화되는 단점이 있지만 이 문제를 방지할 수 있습니다.
HF_HUB_DISABLE_SYMLINKS_WARNING
Windows 머신을 사용하는 경우 개발자 모드를 활성화하거나 huggingface_hub를 관리자 모드로 실행하는 것이 권장됩니다. 그렇지 않으면 huggingface_hub가 캐시 시스템에 심볼릭 링크를 생성할 수 없습니다. 모든 스크립트를 실행할 수는 있지만, 일부 대용량 파일이 하드 드라이브에 중복 저장되어 사용자 경험이 저하될 수 있습니다. 이러한 동작에 대해 경고 메시지가 표시됩니다. 이 경고를 비활성화하려면 HF_HUB_DISABLE_SYMLINKS_WARNING=1을 설정하세요.
자세한 내용은 캐시 제한을 참조하세요.
HF_HUB_DISABLE_EXPERIMENTAL_WARNING
huggingface_hub의 일부 기능은 실험적입니다. 이는 해당 기능을 사용할 수 있지만, 향후 유지보수가 보장되지 않음을 의미합니다. 특히, 이러한 기능의 API나 동작 방식을 비권장(deprecation) 주기와 관계없이 업데이트할 수 있습니다. 실험적 기능을 사용할 때 이를 알리는 경고 메시지가 표시됩니다. 실험적 기능 사용으로 인해 발생할 수 있는 문제를 디버깅하는 데 문제가 없다면, HF_HUB_DISABLE_EXPERIMENTAL_WARNING=1을 설정하여 경고를 비활성화할 수 있습니다.
실험적 기능을 사용 중이시라면 알려 주세요! 여러분의 피드백은 해당 기능의 설계 및 개선에 도움이 됩니다.
HF_HUB_DISABLE_TELEMETRY
기본적으로 HF 라이브러리(transformers, datasets, gradio,..)는 사용량 모니터링, 문제 디버깅, 기능 우선순위 설정을 위해 일부 데이터를 수집합니다.
각 라이브러리는 자체 정책(모니터링할 사용량 등)을 정의하지만, 핵심 구현은 huggingface_hub에서 수행됩니다(send_telemetry 참조).
환경 변수로 HF_HUB_DISABLE_TELEMETRY=1을 설정하면 텔레메트리를 전역적으로 비활성화할 수 있습니다.
HF_HUB_DISABLE_UPDATE_CHECK
기본적으로 hf CLI는 시작 시 PyPI에서 더 새로운 릴리스가 있는지 확인합니다(최대 24시간에 한 번). 새로운 버전이 있으면 stderr에 hf update를 제안하는 한 줄의 노란색 경고를 출력합니다. 개발 버전과 사전 릴리스 버전에서는 이 확인이 이미 no-op입니다.
또한 hf-cli 스킬이 설치되어 있고 현재 실행 중인 버전에서 생성되었는지 확인합니다(최대 24시간에 한 번, 완전히 로컬에서). 그렇지 않으면 hf skills add / hf skills update를 제안합니다. 이 확인은 힌트만 출력할 뿐, 스킬 디렉터리에 절대 영향을 주지 않습니다.
설치된 CLI 확장을 실행하기 전에, GitHub에서 더 새로운 커밋이 있는지 확인합니다(확장 기능당 최대 24시간에 한 번). 더 새로운 커밋이 있으면 hf extensions update <name>을 제안합니다. hf extensions list도 LATEST 열에 동일한 확인을 사용합니다.
HF_HUB_DISABLE_UPDATE_CHECK=1을 설정하면 이러한 요청을 건너뛰고 모든 힌트를 비활성화할 수 있습니다. 오프라인 CI 환경이나 더 조용한 셸 출력을 선호하는 경우에 유용합니다.
HF_HUB_DISABLE_XET
hf-xet 사용 비활성화를 설정합니다. Python 환경에 hf-xet가 설치되어 있더라도 이를 비활성화할 수 있습니다. hf-xet는 환경에서 감지되면 자동으로 사용되므로, 이 설정을 통해 명시적으로 사용을 비활성화할 수 있습니다. Xet을 비활성화하는 경우, Xet이 작동하지 않는 이유를 파악하는 데 도움이 되도록 이슈를 등록하고 진단 정보를 포함해 주시기 바랍니다.
HF_HUB_ENABLE_HF_TRANSFER
이것은 더 이상 사용되지 않는 환경 변수입니다. Hugging Face Hub가 Xet 스토리지 백엔드로 완전히 전환됨에 따라, 모든 파일 전송은
hf-xet바이너리 패키지를 통해 이루어집니다. 이 패키지는 청크 기반 중복 제거 전략을 사용하여 효율적인 전송을 제공하며,huggingface_hub와 원활하게 통합됩니다. 즉,hf_transfer는 더 이상 사용할 수 없습니다. 더 높은 성능에 관심이 있다면HF_XET_HIGH_PERFORMANCE섹션을 확인해 보세요.
HF_HUB_DISABLE_SHARED_BLOBS
캐시 전체의 공유 blob 스토어를 비활성화하려면 1로 설정합니다. 기본적으로 성공적으로 다운로드된 Xet 파일은 <CACHE_DIR>/blobs/<prefix>/<xet_hash>에 저장되고 리포지토리 캐시로 심볼릭 링크되며, 동일한 파일이 여러 리포지토리에 걸쳐 디스크에 한 번만 저장되어 다시 가져오지 않고 재사용할 수 있습니다. 이 최적화는 기본적으로 활성화되어 있지만, Xet를 사용할 수 없는 경우(예: HF_HUB_DISABLE_XET=1가 설정된 경우)나 로컬에서 심볼릭 링크가 지원되지 않는 경우 비활성화됩니다. 이러한 경우 리포지토리 로컬 저장소로 조용히 폴백됩니다. 자세한 내용은 캐싱 가이드를 참조하세요.
HF_XET_HIGH_PERFORMANCE
hf-xet을 증가된 설정으로 작동하도록 설정하여 해당 머신의 네트워크 및 디스크 리소스를 최대한 활용합니다. 고성능 모드를 활성화하면 이 머신의 네트워크 대역폭을 포화 상태로 유지하고, 병렬 업로드/다운로드 작업을 위해 모든 CPU 코어를 활용하려고 시도합니다.
이것은 레거시 HF_HUB_ENABLE_HF_TRANSFER=1 환경 변수와 유사하지만 hf-xet에 적용되는 것으로 생각할 수 있습니다.
Xet 스토리지와 hf_xet의 이점에 대해 자세히 알아보려면 이 섹션을 참고하세요.
HF_XET_RECONSTRUCT_WRITE_SEQUENTIALLY
이 변수는 더 이상 사용되지 않습니다. hf_xet 1.3.0부터 파일은 항상 로컬 디스크에 순차적으로 기록됩니다(v1.3.0의 파일 작성기 참고).
Deprecated environment variables
Hugging Face 생태계 내 모든 환경 변수를 표준화하기 위해 일부 변수가 비권장(deprecated)으로 표시되었습니다. 여전히 기능은 유지되지만, 더 이상 대체 변수보다 우선하지 않습니다. 다음 표는 비권장 변수와 해당 대체 변수를 보여줍니다:
| Deprecated Variable | 교체 |
|---|---|
HUGGINGFACE_HUB_CACHE | HF_HUB_CACHE |
HUGGINGFACE_ASSETS_CACHE | HF_ASSETS_CACHE |
HUGGING_FACE_HUB_TOKEN | HF_TOKEN |
외부 도구에서
일부 환경 변수는 huggingface_hub에 특화되어 있지 않지만, 설정되어 있으면 여전히 고려됩니다.
DO_NOT_TRACK
Boolean 값입니다. HF_HUB_DISABLE_TELEMETRY와 동일합니다. true로 설정하면 Hugging Face Python 생태계(transformers, diffusers, gradio 등)에서 텔레메트리가 전역적으로 비활성화됩니다. 자세한 내용은 https://donottrack.sh/를 참조하세요.
NO_COLOR
Boolean 값. 설정되면 hf CLI는 ANSI 색상을 출력하지 않습니다.
no-color.org를 참조하세요.
XDG_CACHE_HOME
HF_HOME가 설정되지 않은 경우에만 사용됩니다!
Linux 머신에서 사용자별 비필수(캐시) 데이터가 저장될 위치를 설정하는 기본 방법입니다.
HF_HOME가 설정되지 않은 경우, 기본 홈은 "~/.cache/huggingface" 대신 "$XDG_CACHE_HOME/huggingface"가 됩니다.