# 환경 변수

`huggingface_hub`는 환경 변수를 사용하여 구성할 수 있습니다.

환경 변수에 익숙하지 않다면, [macOS와 Linux](https://linuxize.com/post/how-to-set-and-list-environment-variables-in-linux/) 및 [Windows](https://phoenixnap.com/kb/windows-set-environment-variable)에 대한 일반적인 아티클을 참고하세요.

이 페이지에서는 `huggingface_hub`에 특화된 모든 환경 변수와 그 의미를 안내합니다.

> [!TIP]
> 모든 환경 변수는 `huggingface_hub`가 import될 때 읽힙니다. 이후에 이루어지는 변경 사항은 반영되지 않습니다. `huggingface_hub`를 import하기 전에 환경 변수를 설정했는지 확인하세요.

## 일반

### HF_INFERENCE_ENDPOINT

추론 API 기본 URL을 구성합니다. 조직이 추론 API가 아닌 API 게이트웨이를 가리키도록 설정한 경우 이 변수를 설정할 수 있습니다.

`"https://api-inference.huggingface.co"`가 기본값입니다.

### HF_HOME

`huggingface_hub`가 데이터를 로컬에 저장할 위치를 설정합니다. 특히, 토큰과 캐시가 이 폴더에 저장됩니다.

[XDG_CACHE_HOME](#xdgcachehome)가 설정되지 않은 경우 기본값은 `"~/.cache/huggingface"`입니다.

### HF_HUB_CACHE

Hub의 저장소(모델, 데이터셋, 스페이스)가 로컬에 캐시되는 위치를 구성합니다.

기본값은 `"$HF_HOME/hub"`입니다(기본적으로 `"~/.cache/huggingface/hub"`).

### HF_XET_CACHE

Xet이 로컬에 샤드 캐시와 업로드 스테이징 데이터를 저장할 위치를 구성합니다. 자세한 내용은 [Xet 캐싱](../guides/manage-cache#xet-caching)을 참조하세요.

기본값은 `"$HF_HOME/xet"`입니다(기본적으로 `"~/.cache/huggingface/xet"`).

### HF_ASSETS_CACHE

다운스트림 라이브러리가 생성한 [assets](../guides/manage-cache#caching-assets)가 로컬에 캐시될 위치를 설정합니다. 해당 assets에는 전처리된 데이터, GitHub에서 다운로드한 파일, 로그 등이 포함될 수 있습니다.

기본값은 `"$HF_HOME/assets"`입니다 (기본적으로 `"~/.cache/huggingface/assets"`).

### HF_TOKEN

Hub 인증을 위한 User Access Token을 구성합니다. 이 값이 설정된 경우, 해당 값은 머신에 저장된 토큰(전자가 설정되지 않은 경우 `$HF_TOKEN_PATH` 또는 `"$HF_HOME/token"`)을 덮어씁니다.

인증에 대한 자세한 내용은 [이 섹션](../quick-start#authentication)을 확인하세요.

### 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"`입니다.

자세한 내용은 [로깅 참조](../package_reference/utilities#huggingface_hub.utils.logging.get_verbosity)를 참조하세요.

### HF_HUB_ETAG_TIMEOUT

리포지토리에서 파일을 다운로드하기 전에 최신 메타데이터를 가져올 때 서버 응답을 기다릴 초수를 정의하는 정수 값입니다. 요청이 시간 초과되면 `huggingface_hub`는 기본적으로 로컬에 캐시된 파일을 사용합니다. 이미 파일이 캐시된 느린 연결의 머신에서 더 낮은 값을 설정하면 워크플로가 빨라집니다. 더 높은 값은 메타데이터 호출이 더 많은 경우에서 성공하도록 보장합니다. 기본값은 10초입니다.

### HF_HUB_DOWNLOAD_TIMEOUT

파일 다운로드 시 서버 응답을 기다릴 초 수를 정의하는 정수 값입니다. 요청이 시간 초과되면 TimeoutError가 발생하며, 연결 속도가 느린 머신에서는 더 높은 값을 설정하는 것이 유리합니다. 네트워크가 완전히 중단된 경우, 더 작은 값은 프로세스가 더 빠르게 실패하도록 만듭니다. 기본값은 10초입니다.

## Xet 

### 기타 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

이 변수는 더 이상 효과가 없습니다. `hf_xet`는 더 이상 다운로드에 로컬 청크 캐시를 사용하지 않으며, 이 변수를 설정해도 로컬 청크 캐시를 활성화하지 않습니다. 자세한 내용은 [xet-core#715](https://github.com/huggingface/xet-core/issues/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](/docs/huggingface_hub/main/ko/package_reference/hf_api#huggingface_hub.HfApi)의 어떤 메서드를 호출하면 [OfflineModeIsEnabled](/docs/huggingface_hub/main/ko/package_reference/utilities#huggingface_hub.errors.OfflineModeIsEnabled) 예외가 발생합니다.

**참고:** 파일의 최신 버전이 캐시에 저장되어 있더라도 `hf_hub_download`을 호출하면 새 버전이 없는지 확인하기 위해 HTTP 요청이 전송됩니다. `HF_HUB_OFFLINE=1`을 설정하면 이 호출이 건너뛰어져 로딩 시간이 단축됩니다.

오프라인 모드가 활성화되어 있는지 확인하려면 [is_offline_mode()](/docs/huggingface_hub/main/ko/package_reference/utilities#huggingface_hub.is_offline_mode) 헬퍼를 사용할 수 있습니다.

### HF_HUB_DISABLE_IMPLICIT_TOKEN

Hub에 대한 모든 요청에서 인증이 필수적인 것은 아닙니다. 예를 들어, `"gpt2"` 모델의 세부 정보를 요청하는 경우 인증이 필요하지 않습니다. 그러나 사용자가 [로그인](../package_reference/login)된 상태라면, 개인용 또는 게이트된 저장소에 접근할 때 사용자 경험을 향상시키기 위해(HTTP 401 Unauthorized 오류가 발생하지 않도록) 기본적으로 토큰을 항상 전송합니다. 프라이버시를 위해 이 동작을 비활성화하려면 `HF_HUB_DISABLE_IMPLICIT_TOKEN=1`을 설정할 수 있습니다. 이 경우 토큰은 "write-access" 호출(예: 커밋 생성)에만 전송됩니다.

**참고:** 토큰의 암시적 전송을 비활성화하면 의도하지 않은 부수 효과가 발생할 수 있습니다. 예를 들어, 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`을 설정하세요.

자세한 내용은 [캐시 제한](../guides/manage-cache#limitations)을 참조하세요.

### 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 확장](../guides/cli-extensions)을 실행하기 전에, 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이 작동하지 않는 이유를 파악하는 데 도움이 되도록 [이슈를 등록하고 진단 정보를 포함](https://github.com/huggingface/xet-core?tab=readme-ov-file#issues-diagnostics--debugging)해 주시기 바랍니다.

### HF_HUB_ENABLE_HF_TRANSFER

> [!WARNING]
> 이것은 더 이상 사용되지 않는 환경 변수입니다. Hugging Face Hub가 Xet 스토리지 백엔드로 완전히 전환됨에 따라 모든 파일 전송은 `hf-xet` 바이너리 패키지를 통해 이루어집니다. 이 패키지는 청크 기반 중복 제거 전략을 사용하여 효율적인 전송을 제공하며 `huggingface_hub`와 원활하게 통합됩니다. 따라서 `hf_transfer`는 더 이상 사용할 수 없습니다. 더 높은 성능에 관심이 있다면 [`HF_XET_HIGH_PERFORMANCE` 섹션](#hf_xet_high_performance)을 확인해 보세요.

### HF_HUB_DISABLE_SHARED_BLOBS

캐시 전체의 공유 blob 스토어를 비활성화하려면 `1`로 설정합니다. 기본적으로 성공적으로 다운로드된 Xet 파일은 `<CACHE_DIR>/blobs/<prefix>/<xet_hash>`에 저장되고 리포지토리 캐시로 심볼릭 링크되며, 동일한 파일이 여러 리포지토리에 걸쳐 디스크에 한 번만 저장되어 다시 가져오지 않고 재사용할 수 있습니다. 이 최적화는 기본적으로 활성화되어 있지만, Xet를 사용할 수 없는 경우(예: `HF_HUB_DISABLE_XET=1`가 설정된 경우)나 로컬에서 심볼릭 링크가 지원되지 않는 경우 비활성화됩니다. 이러한 경우 리포지토리 로컬 저장소로 조용히 폴백됩니다. 자세한 내용은 [캐싱 가이드](../guides/manage-cache#shared-blobs-across-repos)를 참조하세요.

### HF_XET_HIGH_PERFORMANCE

`hf-xet`을 증가된 설정으로 작동하도록 설정하여 해당 머신의 네트워크 및 디스크 리소스를 최대한 활용합니다. 고성능 모드를 활성화하면 이 머신의 네트워크 대역폭을 포화 상태로 유지하고, 병렬 업로드/다운로드 작업을 위해 모든 CPU 코어를 활용하려고 시도합니다.

이것은 레거시 `HF_HUB_ENABLE_HF_TRANSFER=1` 환경 변수와 유사하지만 `hf-xet`에 적용되는 것으로 생각할 수 있습니다.

Xet 스토리지와 `hf_xet`의 이점에 대해 자세히 알아보려면 이 [섹션](https://huggingface.co/docs/hub/xet/index)을 참고하세요.

### HF_XET_RECONSTRUCT_WRITE_SEQUENTIALLY

이 변수는 더 이상 사용되지 않습니다. `hf_xet` 1.3.0부터 파일은 항상 로컬 디스크에 순차적으로 기록됩니다([v1.3.0의 파일 작성기](https://github.com/huggingface/xet-core/blob/v1.3.0/file_reconstruction/src/data_writer/data_writer.rs#L76-L91) 참고).

## 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](https://no-color.org/)를 참조하세요.

### XDG_CACHE_HOME

`HF_HOME`가 설정되지 않은 경우에만 사용됩니다!

Linux 머신에서 [사용자별 비필수(캐시) 데이터가 저장될 위치](https://wiki.archlinux.org/title/XDG_Base_Directory)를 설정하는 기본 방법입니다.

`HF_HOME`가 설정되지 않은 경우, 기본 홈은 `"~/.cache/huggingface"` 대신 `"$XDG_CACHE_HOME/huggingface"`가 됩니다.