Hugging Face Model Downloads

Hugging Face Model Downloads

Overview

Model weights run from a few gigabytes to hundreds of gigabytes, and anonymous transfers are slow enough to take days. Authenticated transfers are far faster, resumable single-file downloads survive interruptions, and multi-file snapshots need more care than a single call. Most failed downloads come from the environment rather than the network: a token pasted into a shell command, a download process tied to a chat turn that ends, a script written to a temporary folder that disappears, or a ~ that resolves to a different home directory.

When to Use

• Fetching a GGUF or MLX model repository, or one large weights file, from Hugging Face.
• A download is very slow, stalled at zero percent, or lost when the session ended.
• Setting up a machine that will pull models for local inference.

Features

• Token-authenticated transfers, with the token read from a private environment file.
• Resumable single-file download with curl, writing to a .part file that is renamed only when complete.
• Python hf_hub_download for individual files and snapshot_download for whole repositories.
• Persistent background runs through a user launch agent or a scheduled one-shot job.
• Progress checks from disk usage on the destination folder.

Benefits

• At about 300 KB/s, an 80 GB file takes several days. At 100 MB/s, the same file takes about 15 minutes.
• A .part file never looks like a finished model.
• Long downloads continue across chat-session boundaries and agent restarts.

Procedure

1. Store the token in a private environment file that only your account can read, for example <profile-dir>/.env, as HF_TOKEN=<token>. Read it into a variable when a command needs it. Never paste it into a command line or print it into a log:

   export HF_TOKEN="$(grep '^HF_TOKEN=' <env-file> | cut -d= -f2-)"

2. Check free space on the destination volume before starting:

   df -h <destination-volume>

3. Download one large file with resume support. The -C - flag continues from the existing byte offset, and the rename happens only after curl exits successfully:

   URL="https://huggingface.co/<org>/<repo>/resolve/main/<filename>"
   curl -# -L --fail -C - -H "Authorization: Bearer ${HF_TOKEN}" \
     -o "<dest>/<filename>.part" "$URL" \
     && mv "<dest>/<filename>.part" "<dest>/<filename>"

4. For multi-file repositories, write a small script in a persistent folder and run it from there, with absolute paths. Read the token from the environment, set the faster transfer variable, and call the hub library's single-file download once per file, passing the repository, the filename, the local directory, and the token as a parameter. Do not log in through the library, because that stores a credential in its cache. Download small files first, one at a time, so a failure is easy to locate and print the path after each file.

5. For multi-hour transfers, run the script as a persistent job, not as a process attached to a chat turn. A user launch agent works well. It needs RunAtLoad true and KeepAlive false, and it writes its output to a log:

   <key>ProgramArguments</key>
   <array>
     <string>/usr/bin/python3</string>
     <string><absolute-path-to-script>.py</string>
   </array>
   <key>RunAtLoad</key><true/>
   <key>KeepAlive</key><false/>
   <key>StandardOutPath</key><string><absolute-path-to-log></string>

   Load it with launchctl load <plist-path>. A scheduled one-shot job of the agent runtime is the other persistent option.

6. Monitor progress from disk usage and the log, not from the process list:

   du -sh <dest>/<repo-folder>
   tail -n 5 <absolute-path-to-log>

7. For a remote machine, run the download on the host that has the disk. Verify where a file actually landed with ssh <host> 'ls -l <path>', because an agent terminal can be attached to a different machine than the one you intended.

Pitfalls

• Never download without a token. Anonymous transfers are rate-limited to a few hundred KB/s, which turns a large file into a multi-day job.
• **Do not run inline Python with -c over SSH.** Shell quoting mangles token values. Write a .py file, copy it to the host, and run it.
• **Set HF_XET_HIGH_PERFORMANCE=1** to use the faster transfer path.
• **Resume with curl -C -.** A broken transfer continues from its byte offset instead of starting over.
• Snapshot calls with pattern filters can stall at zero percent on large multi-file repositories. Download the files one at a time with hf_hub_download instead.
• Keep scripts in a persistent folder. Temporary folders can be cleared between sessions, and a script written on one machine is not present on another.
• Use absolute paths in scripts. In agent sandboxes, ~ can resolve to a different home directory than your shell uses.
• A stalled progress indicator is a wedged transfer when disk usage has not grown for several minutes, the process is still alive, and the hub still responds. Stop the client and resume the same file with the resumable method.
• **Use the current hf command.** The older huggingface-cli is deprecated.

Verification

• The downloaded file size matches the size the hub reports for that file.
• No .part or .incomplete files remain in the destination folder.
• If the hub lists a SHA-256 for the file, shasum -a 256 <file> matches it.
• The model loads in its runtime, or its header is readable, before any other step depends on it.

Attribution

• Hugging Face Hub, the source of the model repositories and the huggingface_hub Python library: https://huggingface.co