Install & Compatibility
Where this runs
tested against v1.6.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.000s · 30.2MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 1.9s · import 0.000s · 30MB
28MB installed
● package 28MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
No direct imports for end-users
✓ hf-xet is primarily an internal dependency of huggingface_hub. Users interact through huggingface_hub's API.
hf-xet provides Python bindings to Rust code and is designed to be used implicitly by `huggingface_hub` for optimized data transfer, rather than through direct imports in user code.
This quickstart demonstrates how `hf-xet` is utilized implicitly by the `huggingface_hub` library for efficient large file transfers. While `hf-xet` is not directly imported, operations like `snapshot_download` or `upload_file` from `huggingface_hub` will leverage `hf-xet`'s chunk-based deduplication and optimized transfer protocols for Xet-enabled repositories.
import os
from huggingface_hub import snapshot_download
# Ensure you have a Hugging Face token set as an environment variable (HF_TOKEN)
# For example: os.environ['HF_TOKEN'] = 'hf_YOUR_TOKEN_HERE'
# You can generate a token at: https://huggingface.co/settings/tokens
# hf-xet is used implicitly by huggingface_hub for large file transfers.
# This example downloads a small model, but the benefits of Xet become apparent
# with very large models or datasets that leverage its chunk-based deduplication.
try:
# Downloading a model using huggingface_hub, which leverages hf-xet internally
# for Xet-enabled repositories.
model_path = snapshot_download(
repo_id="google/fnet-tokenizer", # A small, example repo
allow_patterns=["tokenizer.json"],
local_dir="./fnet-tokenizer-local",
token=os.environ.get('HF_TOKEN', None) # Pass token if set as env var
)
print(f"Model downloaded to: {model_path}")
print("hf-xet was leveraged by huggingface_hub for efficient transfer.")
except Exception as e:
print(f"An error occurred during download: {e}")
print("Please ensure you have an active internet connection and a valid Hugging Face token if the repo is private or requires auth.")
Debug
Known issues
gotchahf-xet is an underlying dependency for `huggingface_hub` and is not designed for direct user interaction or import in typical Python code. All functionalities, including optimized large file transfers, are exposed through the `huggingface_hub` API.fixInteract with Hugging Face Hub repositories via the `huggingface_hub` library (e.g., `huggingface_hub.snapshot_download`, `huggingface_hub.upload_file`). Ensure `huggingface_hub` version is >=0.32.0 for automatic `hf-xet` integration.
affects: All versions
breakingInstalling `hf-xet` via `pip install --no-binary hf-xet` or in non-standard environments (like Termux) could fail due to `maturin` (Rust-Python binding) build issues, particularly with older versions (e.g., 1.0.3). This might manifest as 'Failed to normalize python source path `python`' errors.fixPrefer installing `hf-xet` via pre-built wheels (`pip install hf-xet`). If building from source is necessary and issues arise, check `huggingface/xet-core` GitHub issues for workarounds or try upgrading `maturin` and Python toolchains. For Termux, local cloning and installation might be required.
affects: <1.4.0 (and potentially specific environments with newer versions if not pre-built wheels are available)
gotchaWhile `hf-xet` aims to improve performance, some users have reported occasional 503 errors, silent hangs at 90-99%, or issues resuming downloads with `xet` compared to conventional `hub` downloads, particularly in early versions or specific network conditions.fixAdaptive concurrency has been enabled to address some stability issues. For persistent download issues, environment variables like `HF_XET_HIGH_PERFORMANCE=1`, `HF_XET_CHUNK_CACHE_SIZE_BYTES=0`, and specific cache path settings might help, or consider using `huggingface_hub.snapshot_download` with a valid `HF_TOKEN`.
affects: Early versions of xet integration within huggingface_hub, potentially specific network environments
breakingThe `huggingface_hub` library (which depends on `hf-xet`) updated its minimum Python version to 3.9 from 3.8 starting with `huggingface_hub` v1.0. While `hf-xet` itself lists `>=3.8`, using it with a modern `huggingface_hub` version implies the higher Python requirement.fixEnsure your Python environment is running Python 3.9 or newer when working with recent versions of `huggingface_hub` and its dependencies, including `hf-xet`.
affects: huggingface_hub >=1.0, indirectly affecting hf-xet usage.
breakingThe `huggingface_hub` library is a fundamental dependency for interacting with the Hugging Face Hub. A `ModuleNotFoundError` indicates that the package is not installed or not accessible in the current Python environment.fixEnsure `huggingface_hub` is installed in your Python environment by running `pip install huggingface_hub` before attempting to import or use it.
affects: All versions of `huggingface_hub` (if not installed)
breakingThe 'huggingface_hub' package was not found in the Python environment, resulting in a 'ModuleNotFoundError'. This typically occurs when the package has not been installed or is not accessible in the current Python interpreter.fixEnsure 'huggingface_hub' is properly installed in your Python environment by running `pip install huggingface_hub` before attempting to import or use it. Verify that the correct Python environment is active when running your script.
affects: All versions (if not installed)
Upgrade
Version history
1.6.0latest on PyPI · released Aug 3, 2026
Audit
Dependencies
huggingface_hubrequiredhf-xet acts as a backend for huggingface_hub for efficient large file transfers. huggingface_hub >=0.32.0 automatically installs hf-xet as a dependency.