Add HF_HUB_DISABLE_SYMLINKS env variable to force no-symlink cache (#4032)

* Add `HF_HUB_DISABLE_SYMLINKS` env variable to force no-symlink cache

When a shared NAS is used as HF_HUB_CACHE across machines with different
OSes, symlinks created on Linux cannot be followed by Windows clients.
Setting `HF_HUB_DISABLE_SYMLINKS=1` makes `are_symlinks_supported()`
always return False, so files are copied instead of symlinked.

Closes #4022

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* add test + update markdown

* extra careful

---------

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: Wauplin

docs/source/en/package_reference/environment_variables.md

@@ -148,6 +148,13 @@ would need to explicitly pass `token=True` argument in your script.
 For time-consuming tasks, `huggingface_hub` displays a progress bar by default (using tqdm).
 You can disable all the progress bars at once by setting `HF_HUB_DISABLE_PROGRESS_BARS=1`.
 
+### HF_HUB_DISABLE_SYMLINKS
+
+If set, `huggingface_hub` will never create symlinks in the cache. Instead, files will be duplicated or moved directly into snapshot directories. This is a power-user feature making the cache directory run in a degraded mode where huge files ends-up duplicated on your hard-drive.
+
+An example use case is when a shared network drive (e.g. NAS) is used as `HF_HUB_CACHE` across machines running different operating
+systems. Symlinks created on Linux are not always traversable on Windows, leading to errors. Setting `HF_HUB_DISABLE_SYMLINKS=1` avoids this problem at the cost of disk-space deduplication.
+
 ### HF_HUB_DISABLE_SYMLINKS_WARNING
 
 If you are on a Windows machine, it is recommended to enable the developer mode or to run

src/huggingface_hub/constants.py

@@ -229,6 +229,9 @@ def list_files(repo_id: str):
     _is_true(__HF_HUB_DISABLE_PROGRESS_BARS) if __HF_HUB_DISABLE_PROGRESS_BARS is not None else None
 )
 
+# Disable symlinks in the cache (files are copied instead of symlinked)
+HF_HUB_DISABLE_SYMLINKS: bool = _is_true(os.environ.get("HF_HUB_DISABLE_SYMLINKS"))
+
 # Disable warning on machines that do not support symlinks (e.g. Windows non-developer)
 HF_HUB_DISABLE_SYMLINKS_WARNING: bool = _is_true(os.environ.get("HF_HUB_DISABLE_SYMLINKS_WARNING"))
 

src/huggingface_hub/file_download.py

@@ -94,6 +94,10 @@ def are_symlinks_supported(cache_dir: str | Path | None = None) -> bool:
         cache_dir = constants.HF_HUB_CACHE
     cache_dir = str(Path(cache_dir).expanduser().resolve())  # make it unique
 
+    # If symlinks are explicitly disabled by the user, always return False
+    if constants.HF_HUB_DISABLE_SYMLINKS:
+        return False
+
     # Check symlink compatibility only once (per cache directory) at first time use
     if cache_dir not in _are_symlinks_supported_in_dir:
         _are_symlinks_supported_in_dir[cache_dir] = True
@@ -640,7 +644,7 @@ def _create_symlink(src: str, dst: str, new_blob: bool = False) -> None:
     except ValueError:
         # Raised if src and dst are not on the same volume. Symlinks will still work on Linux/Macos.
         # See https://docs.python.org/3/library/os.path.html#os.path.commonpath
-        _support_symlinks = os.name != "nt"
+        _support_symlinks = os.name != "nt" and not constants.HF_HUB_DISABLE_SYMLINKS
     except PermissionError:
         # Permission error means src and dst are not in the same volume (e.g. destination path has been provided
         # by the user via `local_dir`. Let's test symlink support there)

src/huggingface_hub/utils/_runtime.py

@@ -427,6 +427,7 @@ def dump_environment_info() -> dict[str, Any]:
     info["HF_HUB_OFFLINE"] = constants.HF_HUB_OFFLINE
     info["HF_HUB_DISABLE_TELEMETRY"] = constants.HF_HUB_DISABLE_TELEMETRY
     info["HF_HUB_DISABLE_PROGRESS_BARS"] = constants.HF_HUB_DISABLE_PROGRESS_BARS
+    info["HF_HUB_DISABLE_SYMLINKS"] = constants.HF_HUB_DISABLE_SYMLINKS
     info["HF_HUB_DISABLE_SYMLINKS_WARNING"] = constants.HF_HUB_DISABLE_SYMLINKS_WARNING
     info["HF_HUB_DISABLE_EXPERIMENTAL_WARNING"] = constants.HF_HUB_DISABLE_EXPERIMENTAL_WARNING
     info["HF_HUB_DISABLE_IMPLICIT_TOKEN"] = constants.HF_HUB_DISABLE_IMPLICIT_TOKEN

tests/test_cache_no_symlinks.py

@@ -24,6 +24,12 @@ class TestCacheLayoutIfSymlinksNotSupported(unittest.TestCase):
     def test_are_symlinks_supported_default(self) -> None:
         self.assertTrue(are_symlinks_supported())
 
+    @patch("huggingface_hub.file_download.constants.HF_HUB_DISABLE_SYMLINKS", True)
+    @patch("huggingface_hub.file_download._are_symlinks_supported_in_dir", {HF_HUB_CACHE: True})
+    def test_are_symlinks_supported_disabled_by_env(self) -> None:
+        """Setting HF_HUB_DISABLE_SYMLINKS=1 forces are_symlinks_supported() to return False."""
+        self.assertFalse(are_symlinks_supported())
+
     @patch("huggingface_hub.file_download.os.symlink")
     @patch("huggingface_hub.file_download._are_symlinks_supported_in_dir", {})
     def test_are_symlinks_supported_windows_specific_dir(self, mock_symlink: Mock) -> None: