Hugging Face Git LFS "smudge filter failed" cloning a model repo in CI

Model weights on the Hub are stored with Git LFS. Cloning without LFS (or hitting an LFS error) leaves small pointer files instead of the real weights, and later reads fail. For CI, downloading with huggingface_hub avoids raw git LFS entirely.

What this error means

A git clone of a model repo fails with "Encountered N file(s) that should have been pointers, but weren't" or "smudge filter lfs failed", or the checkout has tiny files where weights should be.

Downloading model.safetensors (440 MB)
Error downloading object: model.safetensors: Smudge error: Error downloading ...
error: external filter 'git-lfs filter-process' failed
fatal: model.safetensors: smudge filter lfs failed

Common causes

LFS content was not pulled or failed to fetch

Without git-lfs installed or with a transient LFS fetch error, the clone leaves pointer files, not the weights.

Raw git clone of a large model repo

Cloning big model repos with git is fragile in CI; the Hub download APIs are built for it.

How to fix it

Download with huggingface_hub instead of git

Use snapshot_download so the Hub client fetches real files with resume and no LFS smudge step.

python -c "from huggingface_hub import snapshot_download; snapshot_download('org/model')"

Install and pull LFS if you must use git

Initialize git-lfs and pull so pointers are replaced by real content.

git lfs install
git clone https://huggingface.co/org/model
cd model && git lfs pull

How to prevent it

• Prefer snapshot_download over git clone for model weights in CI.
• Install git-lfs before cloning any LFS-backed repo.
• Enable hf_transfer for reliable large-file downloads.

Related guides