Downloading Models

Downloading Models

hk pull fetches a model from the Hugging Face Hub straight into a .hk file.

hk pull Qwen/Qwen3-0.6B                          # a safetensors repository
hk pull bartowski/SmolLM2-135M-Instruct-GGUF     # a GGUF repository, best default quant
hk pull bartowski/SmolLM2-135M-Instruct-GGUF:Q8_0
hk pull owner/name --revision some-branch --force

What it does

A GGUF or safetensors file is never saved as such. The bytes are converted while they arrive and written once, as .hk, so the disk use is the size of the result and the memory use is a few megabytes whatever the model size. The download is hashed as it streams, and the hash is compared with the SHA-256 the Hub lists before the file is moved into place. A wrong hash, a truncated body or any other error deletes the partial file; nothing half written is ever left in the cache.

• Resume. A dropped connection continues from the last byte with a range request.
• Retries. Rate limits (429) and server errors are retried with backoff, then reported.
• Sharded repositories. Safetensors repositories split over several files are converted shard by shard. If the Hub does not list a checksum for a shard, the summary says "no checksum available" instead of "checksum verified".
• Authentication. Set HF_TOKEN (or HUGGING_FACE_HUB_TOKEN, or log in with the Hugging Face tools, which write ~/.cache/huggingface/token). The token is sent only to the Hub's own host and is dropped when a download is redirected to another host.
• Choosing a file. With a GGUF repository, a :selector picks the file whose name contains it (Q8_0, IQ4_XS, or an exact name). Without one, the first of Q4_K_M, Q4_K_S, Q5_K_M, Q5_K_S, Q6_K, Q8_0, Q4_0, Q3_K_M, IQ4_XS, Q2_K that exists is used.

Safetensors repositories need config.json and a byte level BPE tokenizer.json. A repository with a SentencePiece or Unigram tokenizer is refused with a message; its GGUF version works.

Where models go

$HK_HOME, else $XDG_CACHE_HOME/hk, else ~/.cache/hk, in models/<owner>--<name>/.

hk list                       # what is cached
hk rm Qwen/Qwen3-0.6B         # delete it
hk search qwen3 --limit 10    # search the Hub (GGUF repositories by default, --all for everything)

Environment variables

Variable	Effect
HK_HOME	cache directory
HF_TOKEN, HUGGING_FACE_HUB_TOKEN	Hub access token
HF_ENDPOINT	use another Hub, for example a mirror or a test server
HK_HTTP_BACKOFF_MS	base delay between retries

Not done yet

• Split GGUF files (-00001-of-00003.gguf) are refused with a clear message.
• An interrupted conversion starts over. The download resumes; the conversion does not.

The downloader is tested against a mock Hub that injects wrong checksums, dropped and truncated connections, rate limits, redirects to other hosts and missing authorization (tests/hub_tests.zig).