Fixing Windows 'Filename too long' Errors: LongPathsEnabled Registry, Git Core.longpaths & Hub Symlinks

💥 Windows classic pain point: MAX_PATH 260 limit

When downloading large models through the command line or Python in Windows 10/11 or Windows Server environments, many developers will encounter errors such as Filename too long, OSError: [Errno 22] Invalid argument or Git checkout-index: unable to create file.

This is due to the system-wide constant MAX_PATH = 260 character limit left over from the MS-DOS days of the 1980s.

The default cache structure of Hugging Face includes the organization name, warehouse name, complete 40-bit SHA-1 commit hash, and volume file name. The path length can easily exceed the 260 character limit:

C:\Users\Administrator\.cache\huggingface\hub\models--meta-llama--Llama-3.3-70B-Instruct\snapshots\a7569e0618ff9f4b3bf59c3a37d6e6a17b8f9e01\model-00028-of-00030.safetensors (Total 274 characters, exceeds 260 limit)

🛠️ Four steps to completely solve the problem of too long Windows paths

📌 Step 1: Unlock the system registry LongPathsEnabled

In Windows 10 (version 1607 and above) and Windows 11, Microsoft has built-in long path support natively, but it is turned off by default. Run PowerShell as Administrator and execute:

PowerShell Unlock Registry

New-ItemProperty -Path "HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem" `
  -Name "LongPathsEnabled" -Value 1 -PropertyType DWORD -Force

Write-Host "System-wide long path support activated!" -ForegroundColor Green

📌 Step 2: Configure Git global longpaths support

The Git for Windows client has its own independent path truncation strategy, which needs to be executed separately:

Git turns on long path support

git config --system core.longpaths true

📌 Step 3: Redirect HF_HOME to the root directory of the drive (the most immediate trick)

Do not cache models deep in the C:\Users\username\... directory. Set HF_HOME to a concise root path (such as D:\hf_cache) in the Windows environment variable. Not only will the path length be directly reduced by 60 characters, but it will also prevent the C drive system disk from filling up:

PowerShell one-click configuration of system-level environment variables

# Temporarily take effect in PowerShell or write system environment variables
[System.Environment]::SetEnvironmentVariable('HF_HOME', 'D:\hf_cache', [System.EnvironmentVariableTarget]::User)
[System.Environment]::SetEnvironmentVariable('HF_ENDPOINT', 'https://hf-mirror.net', [System.EnvironmentVariableTarget]::User)

Write-Host "The model home directory has been directed to D:\hf_cache and mirror source acceleration has been configured!" -ForegroundColor Cyan

📌 Step 4: \?\ expansion prefix in Python code

If you are writing low-level Python scripts that read and write weights, you can use the Windows extended path prefix \\?\, which explicitly bypasses all Win32 path normalization layers and supports a maximum length of 32,767 characters:

Python wrapper compatible with Windows ultra-long paths

import os

def safe_open_path(path_str):
    # Convert standard absolute paths to Windows extended long paths
    abs_path = os.path.abspath(path_str)
    if os.name == 'nt' and not abs_path.startswith('\\\\?\\'):
        return '\\\\?\\' + abs_path
    return abs_path