Hugging Face "symlinks are not supported" cache warning in CI
The HF cache deduplicates blobs with symlinks. On Windows runners without Developer Mode, symlink creation is not permitted, so huggingface_hub warns and falls back to copying, using extra disk. It is a warning, not a hard failure, but noisy logs and doubled cache size follow.
What this error means
CI logs show "UserWarning: huggingface_hub cache-system uses symlinks by default ... your machine does not support them ... Caching files will still work but ... use more disk usage."
UserWarning: `huggingface_hub` cache-system uses symlinks by default to efficiently store
duplicated files but your machine does not support them in
C:\Users\runneradmin\.cache\huggingface\hub. Caching files will still work but in a degraded
version that might require more space on your disk.Common causes
Windows runner without symlink privilege
Creating symlinks on Windows needs Developer Mode or elevated rights, which CI runners usually lack.
A filesystem that does not support symlinks
Some mounted volumes cannot create symlinks, triggering the same fallback.
How to fix it
Silence the warning if the fallback is acceptable
Set the disable-warning variable so logs stay clean; caching still works via copies.
env:
HF_HUB_DISABLE_SYMLINKS_WARNING: '1'Enable symlink support to save disk
If you want dedup, enable Developer Mode on the Windows runner or use a Linux runner where symlinks work by default.
# Prefer a Linux runner for HF caching
runs-on: ubuntu-latestHow to prevent it
- Run HF cache-heavy jobs on Linux runners where symlinks work.
- Set
HF_HUB_DISABLE_SYMLINKS_WARNINGon Windows to quiet logs. - Account for extra disk when the copy fallback is used.