# Variabel lingkungan

`huggingface_hub` dapat dikonfigurasi menggunakan variabel lingkungan.

Jika Anda belum familiar dengan variabel lingkungan, berikut adalah artikel umum tentangnya [di macOS dan Linux](https://linuxize.com/post/how-to-set-and-list-environment-variables-in-linux/) serta di [Windows](https://phoenixnap.com/kb/windows-set-environment-variable).

Halaman ini akan memandu Anda melalui semua variabel lingkungan yang spesifik untuk `huggingface_hub` beserta artinya.

> [!TIP]
> Semua variabel lingkungan dibaca pada saat impor `huggingface_hub`. Setiap modifikasi yang dilakukan setelahnya tidak akan dipertimbangkan. Pastikan Anda mengatur variabel lingkungan Anda sebelum mengimpor `huggingface_hub`.

## Umum

### HF_INFERENCE_ENDPOINT

Untuk mengatur inference api base url. Anda mungkin ingin mengatur variabel ini jika organisasi Anda mengarah ke API Gateway alih-alih langsung ke inference api.

Bergaya default ke `"/static-proxy?url=https%3A%2F%2Fapi-inference.huggingface.co"`.

### HF_HOME

Untuk mengatur di mana `huggingface_hub` akan menyimpan data secara lokal. Secara khusus, token dan cache Anda akan disimpan di folder ini.

Bergaya default ke `"~/.cache/huggingface"` kecuali [XDG_CACHE_HOME](#xdgcachehome) disetel.

### HF_HUB_CACHE

Untuk mengatur di mana repositori dari Hub akan di-cache secara lokal (model, dataset, dan spaces).

Bergaya default ke `"$HF_HOME/hub"` (misalnya `"~/.cache/huggingface/hub"` secara default).

### HF_XET_CACHE

Untuk mengatur di mana Xet menyimpan cache shard dan data staging upload secara lokal. Lihat [penyimpanan cache Xet](../guides/manage-cache#xet-caching) untuk detail lebih lanjut.

Bergaya default ke `"$HF_HOME/xet"` (misalnya `"~/.cache/huggingface/xet"` secara default).

### HF_ASSETS_CACHE

Untuk mengatur di mana [aset](../guides/manage-cache#caching-assets) yang dibuat oleh pustaka hilir akan di-cache secara lokal. Aset tersebut dapat berupa data yang telah diproses, file yang diunduh dari GitHub, log, dan sebagainya.

Bergaya default ke `"$HF_HOME/assets"` (misalnya `"~/.cache/huggingface/assets"` secara default).

### HF_TOKEN

Untuk mengatur User Access Token guna autentikasi ke Hub. Jika diset, nilai ini akan menimpa token yang disimpan di mesin (di `$HF_TOKEN_PATH` atau `"$HF_HOME/token"` jika yang pertama tidak diset).

Untuk detail lebih lanjut tentang autentikasi, lihat [bagian ini](../quick-start#authentication).

### HF_TOKEN_PATH

Untuk mengatur di mana `huggingface_hub` harus menyimpan User Access Token. Secara default menggunakan `"$HF_HOME/token"` (misalnya `~/.cache/huggingface/token` secara default).

### HF_HUB_VERBOSITY

Atur tingkat kecermatan logger `huggingface_hub`. Harus salah satu dari `{"debug", "info", "warning", "error", "critical"}`.

Bawaan adalah `"warning"`.

Untuk detail lebih lanjut, lihat [referensi logging](../package_reference/utilities#huggingface_hub.utils.logging.get_verbosity).

### HF_HUB_ETAG_TIMEOUT

Nilai integer untuk mendefinisikan jumlah detik yang ditunggu untuk respons server saat mengambil metadata terbaru dari repo sebelum mengunduh file. Jika permintaan melebihi batas waktu, `huggingface_hub` akan menggunakan file yang di-cache secara lokal. Pengaturan nilai yang lebih rendah mempercepat alur kerja untuk mesin dengan koneksi lambat yang sudah memiliki file di cache. Nilai yang lebih tinggi menjamin pemanggilan metadata berhasil dalam lebih banyak kasus. Bawaan adalah 10 detik.

### HF_HUB_DOWNLOAD_TIMEOUT

Nilai integer untuk mendefinisikan jumlah detik yang ditunggu untuk respons server saat mengunduh file. Jika permintaan melebihi batas waktu, TimeoutError akan dilempar. Mengatur nilai yang lebih tinggi bermanfaat pada mesin dengan koneksi lambat. Nilai yang lebih kecil membuat proses gagal lebih cepat dalam kasus gangguan jaringan total. Bawaan adalah 10 detik.

## Xet 

### Variabel lingkungan Xet lainnya
* [`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

Variabel ini tidak lagi memiliki efek apa pun. `hf_xet` tidak lagi menggunakan cache chunk lokal untuk unduhan, dan mengatur variabel ini tidak akan mengaktifkannya. Lihat [xet-core#715](https://github.com/huggingface/xet-core/issues/715) untuk detailnya.

### HF_XET_SHARD_CACHE_SIZE_LIMIT

Untuk mengatur ukuran cache shard Xet secara lokal. Meningkatkan nilai ini akan meningkatkan efisiensi unggahan karena chunk yang dirujuk dalam file shard yang di-cache tidak diunggah ulang. Perhatikan bahwa batas lunak default kemungkinan sudah cukup untuk sebagian besar beban kerja.

Bawaan ke `16000000000` (16GB).

### HF_XET_NUM_CONCURRENT_RANGE_GETS

Variabel ini tidak lagi digunakan. Sejak `hf_xet` 1.3.0, konkurensi unduhan dikendalikan secara adaptif.

## Nilai Boolean

Variabel lingkungan berikut mengharapkan nilai boolean. Variabel akan dianggap sebagai `True` jika nilainya salah satu dari `{"1", "ON", "YES", "TRUE"}` (tidak membedakan huruf besar/kecil). Nilai lain (atau tidak terdefinisi) akan dianggap sebagai `False`.

### HF_DEBUG

Jika disetel, level log untuk logger `huggingface_hub` akan disetel ke DEBUG. Selain itu, semua permintaan yang dibuat oleh pustaka HF akan dicatat sebagai perintah cURL yang setara untuk memudahkan debugging dan reproduksibilitas.

### HF_HUB_OFFLINE

Jika disetel, tidak akan ada panggilan HTTP yang dibuat ke Hugging Face Hub. Jika Anda mencoba mengunduh file, hanya file yang sudah di-cache yang akan diakses. Jika tidak ada file cache yang terdeteksi, sebuah error akan dilempar. Hal ini berguna jika jaringan Anda lambat dan Anda tidak peduli untuk memiliki versi terbaru dari sebuah file.

Jika `HF_HUB_OFFLINE=1` diset sebagai variabel lingkungan dan Anda memanggil metode apa pun dari [HfApi](/docs/huggingface_hub/v2.4.0/id/package_reference/hf_api#huggingface_hub.HfApi), pengecualian [OfflineModeIsEnabled](/docs/huggingface_hub/v2.4.0/id/package_reference/utilities#huggingface_hub.errors.OfflineModeIsEnabled) akan dilempar.

**Catatan:** meskipun versi terbaru dari sebuah file sudah di-cache, pemanggilan `hf_hub_download` tetap memicu permintaan HTTP untuk memeriksa apakah versi baru tersedia. Pengaturan `HF_HUB_OFFLINE=1` akan melewati panggilan ini sehingga mempercepat waktu pemuatan Anda.

Jika Anda ingin memeriksa apakah mode offline diaktifkan atau tidak, Anda dapat menggunakan helper [is_offline_mode()](/docs/huggingface_hub/v2.4.0/id/package_reference/utilities#huggingface_hub.is_offline_mode).

### HF_HUB_DISABLE_IMPLICIT_TOKEN

Autentikasi tidak wajib untuk setiap permintaan ke Hub. Misalnya, meminta detail tentang model `"gpt2"` tidak memerlukan autentikasi. Namun, jika pengguna [telah masuk](../package_reference/login), perilaku default akan selalu mengirim token untuk memudahkan pengalaman pengguna (tidak pernah menerima HTTP 401 Unauthorized) saat mengakses repositori privat atau bergerbang. Demi privasi, Anda dapat menonaktifkan perilaku ini dengan mengatur `HF_HUB_DISABLE_IMPLICIT_TOKEN=1`. Dalam kasus ini, token hanya akan dikirim untuk panggilan "write-access" (contoh: membuat commit).

**Catatan:** menonaktifkan pengiriman token secara implisit dapat menimbulkan efek samping yang aneh. Misalnya, jika Anda ingin mendaftar semua model di Hub, model privat Anda tidak akan terdaftar. Anda perlu secara eksplisit melewatkan argumen `token=True` dalam skrip Anda.

### HF_HUB_DISABLE_PROGRESS_BARS

Untuk tugas yang memakan waktu lama, `huggingface_hub` menampilkan bilah progres secara default (menggunakan tqdm). Anda dapat menonaktifkan semua bilah progres sekaligus dengan mengatur `HF_HUB_DISABLE_PROGRESS_BARS=1`.

### HF_HUB_DISABLE_SYMLINKS

Jika disetel, `huggingface_hub` tidak akan pernah membuat symlink di cache. Sebagai gantinya, file akan diduplikasi atau dipindahkan langsung ke direktori snapshot. Ini adalah fitur untuk pengguna lanjutan yang membuat direktori cache berjalan dalam mode terdegradasi di mana file berukuran besar akhirnya diduplikasi di hard drive Anda.

Salah satu contoh kasus penggunaan adalah ketika drive jaringan bersama (misalnya NAS) digunakan sebagai `HF_HUB_CACHE` di antara mesin yang menjalankan sistem operasi berbeda. Symlink yang dibuat di Linux tidak selalu dapat dilintasi di Windows, yang menyebabkan error. Mengatur `HF_HUB_DISABLE_SYMLINKS=1` menghindari masalah ini dengan mengorbankan deduplikasi ruang disk.

### HF_HUB_DISABLE_SYMLINKS_WARNING

Jika Anda menggunakan mesin Windows, disarankan untuk mengaktifkan mode developer atau menjalankan `huggingface_hub` dalam mode admin. Jika tidak, `huggingface_hub` tidak akan dapat membuat symlink di sistem cache Anda. Anda tetap dapat menjalankan skrip apa pun, tetapi pengalaman pengguna Anda akan menurun karena beberapa file besar mungkin berakhir terduplikasi di hard drive Anda. Pesan peringatan akan muncul untuk memberi tahu Anda tentang perilaku ini. Atur `HF_HUB_DISABLE_SYMLINKS_WARNING=1` untuk menonaktifkan peringatan ini.

Untuk detail lebih lanjut, lihat [batasan cache](../guides/manage-cache#limitations).

### HF_HUB_DISABLE_EXPERIMENTAL_WARNING

Beberapa fitur `huggingface_hub` bersifat eksperimental. Artinya, Anda dapat menggunakannya, tetapi kami tidak menjamin bahwa fitur tersebut akan dipertahankan di masa depan. Secara khusus, kami mungkin memperbarui API atau perilaku fitur semacam itu tanpa siklus deprecation. Pesan peringatan akan muncul saat Anda menggunakan fitur eksperimental untuk memberi tahu Anda tentang hal ini. Jika Anda merasa nyaman dalam men-debug potensi masalah yang timbul dari penggunaan fitur eksperimental, Anda dapat mengatur `HF_HUB_DISABLE_EXPERIMENTAL_WARNING=1` untuk menonaktifkan peringatan tersebut.

Jika Anda menggunakan fitur eksperimental, silakan beri tahu kami! Umpan balik Anda dapat membantu kami merancang dan memperbaikinya.

### HF_HUB_DISABLE_TELEMETRY

Secara default, beberapa data dikumpulkan oleh pustaka HF (`transformers`, `datasets`, `gradio`,..) untuk memantau penggunaan, men-debug masalah, dan membantu memprioritaskan fitur. Setiap pustaka mendefinisikan kebijakan masing-masing (yaitu penggunaan apa yang dipantau) tetapi implementasi intinya terjadi di `huggingface_hub` (lihat `send_telemetry`).

Anda dapat mengatur `HF_HUB_DISABLE_TELEMETRY=1` sebagai variabel lingkungan untuk menonaktifkan telemetri secara global.

### HF_HUB_DISABLE_UPDATE_CHECK

Secara default, CLI `hf` memeriksa PyPI untuk rilis yang lebih baru saat startup (paling sering sekali setiap 24 jam) dan mencetak peringatan satu baris berwarna kuning ke stderr ketika tersedia, yang menyarankan `hf update`. Pemeriksaan ini sudah menjadi no-op pada versi dev dan pre-release.

Ini juga memeriksa (paling sering sekali setiap 24 jam, sepenuhnya secara lokal) apakah skill `hf-cli` terpasang dan dihasilkan oleh versi yang sedang berjalan, serta menyarankan `hf skills add` / `hf skills update` jika belum. Pemeriksaan ini hanya mencetak petunjuk, tidak pernah menyentuh direktori skill Anda.

Sebelum menjalankan [ekstensi CLI](../guides/cli-extensions) yang terpasang, sistem memeriksa (paling banyak sekali setiap 24 jam per ekstensi) apakah ada commit yang lebih baru di GitHub, dan menyarankan `hf extensions update <name>` jika ada. `hf extensions list` menggunakan pemeriksaan yang sama untuk kolom `LATEST`-nya.

Set `HF_HUB_DISABLE_UPDATE_CHECK=1` untuk melewati permintaan-permintaan ini dan membisukan semua petunjuk tersebut. Berguna di lingkungan CI offline atau ketika Anda lebih memilih output shell yang lebih tenang.

### HF_HUB_DISABLE_XET

Atur untuk menonaktifkan penggunaan `hf-xet`, meskipun tersedia di lingkungan Python Anda. Hal ini karena `hf-xet` akan digunakan secara otomatis jika ditemukan, sehingga pengaturan ini memungkinkan penonaktifan eksplisit. Jika Anda menonaktifkan Xet, pertimbangkan untuk [membuat laporan masalah dan menyertakan informasi diagnostik](https://github.com/huggingface/xet-core?tab=readme-ov-file#issues-diagnostics--debugging) untuk membantu kami memahami mengapa Xet tidak berfungsi bagi Anda.

### HF_HUB_ENABLE_HF_TRANSFER

> [!WARNING]
> Ini adalah variabel lingkungan yang sudah tidak digunakan. Sekarang, karena Hugging Face Hub sepenuhnya didukung oleh backend penyimpanan Xet, semua transfer file dilakukan melalui paket biner `hf-xet`. Paket ini menyediakan transfer yang efisien menggunakan strategi deduplikasi berbasis chunk dan terintegrasi dengan mulus dengan `huggingface_hub`. Artinya, `hf_transfer` tidak dapat digunakan lagi. Jika Anda tertarik dengan kinerja yang lebih tinggi, lihat bagian [`HF_XET_HIGH_PERFORMANCE`](#hf_xet_high_performance)

### HF_HUB_DISABLE_SHARED_BLOBS

Setel ke `1` untuk menonaktifkan blob store bersama di seluruh cache. Secara default, file Xet yang berhasil diunduh disimpan di `<CACHE_DIR>/blobs/<prefix>/<xet_hash>` dan dibuat symlink ke cache repo, sehingga file yang identik hanya disimpan sekali di disk di antara berbagai repo dan dapat digunakan kembali tanpa perlu mengambil ulang. Optimasi ini diaktifkan secara default, tetapi dinonaktifkan jika Xet tidak tersedia (misalnya jika `HF_HUB_DISABLE_XET=1` disetel) atau jika symlink tidak didukung secara lokal. Dalam kasus tersebut, sistem secara diam-diam kembali ke penyimpanan lokal repo biasa. Lihat [panduan caching](../guides/manage-cache#shared-blobs-across-repos) untuk detailnya.

### HF_XET_HIGH_PERFORMANCE

Setel `hf-xet` untuk beroperasi dengan pengaturan yang ditingkatkan guna memaksimalkan sumber daya jaringan dan disk pada mesin. Mengaktifkan mode kinerja tinggi akan mencoba menjenuhkan bandwidth jaringan mesin ini dan memanfaatkan semua core CPU untuk aktivitas unggah/unduh paralel.

Anggap ini serupa dengan variabel lingkungan `HF_HUB_ENABLE_HF_TRANSFER=1` lama, tetapi diterapkan pada `hf-xet`.

Untuk mempelajari lebih lanjut tentang manfaat penyimpanan Xet dan `hf_xet`, lihat [bagian](https://huggingface.co/docs/hub/xet/index) ini.

### HF_XET_RECONSTRUCT_WRITE_SEQUENTIALLY

Variabel ini tidak lagi digunakan. Sejak `hf_xet` 1.3.0, file selalu ditulis ke disk lokal secara berurutan (lihat [penulis file di v1.3.0](https://github.com/huggingface/xet-core/blob/v1.3.0/file_reconstruction/src/data_writer/data_writer.rs#L76-L91)).

## Variabel lingkungan yang tidak didukung lagi

Untuk menstandarkan semua variabel lingkungan dalam ekosistem Hugging Face, beberapa variabel telah ditandai sebagai tidak lagi didukung (deprecated). Meskipun masih berfungsi, variabel-variabel tersebut tidak lagi memiliki prioritas lebih tinggi dibandingkan penggantiannya. Tabel berikut merangkum variabel yang tidak lagi didukung beserta alternatifnya yang sesuai:

| Variabel yang Tidak Lagi Digunakan         | Penggantian        |
| --------------------------- | ------------------ |
| `HUGGINGFACE_HUB_CACHE`     | `HF_HUB_CACHE`     |
| `HUGGINGFACE_ASSETS_CACHE`  | `HF_ASSETS_CACHE`  |
| `HUGGING_FACE_HUB_TOKEN`    | `HF_TOKEN`         |

## Dari alat eksternal

Beberapa variabel lingkungan tidak spesifik untuk `huggingface_hub` tetapi tetap diperhitungkan saat disetel.

### DO_NOT_TRACK

Nilai Boolean. Setara dengan `HF_HUB_DISABLE_TELEMETRY`. Ketika diatur ke true, telemetri dinonaktifkan secara global di ekosistem Python Hugging Face (`transformers`, `diffusers`, `gradio`, dll.). Lihat https://donottrack.sh/ untuk detail lebih lanjut.

### NO_COLOR

Nilai Boolean. Saat diatur, CLI `hf` tidak akan mencetak warna ANSI apa pun. Lihat [no-color.org](https://no-color.org/).

### XDG_CACHE_HOME

Hanya digunakan ketika `HF_HOME` tidak disetel!

Ini adalah cara default untuk mengatur di mana [data non-esensial (ter-cache) yang spesifik pengguna harus ditulis](https://wiki.archlinux.org/title/XDG_Base_Directory) pada mesin linux.

Jika `HF_HOME` tidak disetel, home default akan menjadi `"$XDG_CACHE_HOME/huggingface"` alih-alih `"~/.cache/huggingface"`.