Fix compat with filelock < 3.10.0 by conditionally using mode= parameter

The `mode=` parameter was added in filelock 3.10.0. When an older version
is installed, skip the parameter and emit a warning suggesting to upgrade.

Fixes #3777

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: Wauplin

src/huggingface_hub/utils/_fixes.py

@@ -4,15 +4,18 @@
 import stat
 import tempfile
 import time
+import warnings
 from functools import partial
 from pathlib import Path
 from typing import Callable, Generator, Optional, Union
 
 import yaml
 from filelock import BaseFileLock, FileLock, SoftFileLock, Timeout
+from packaging import version as packaging_version
 
 from .. import constants
 from . import logging
+from ._runtime import get_filelock_version
 
 
 logger = logging.get_logger(__name__)
@@ -73,6 +76,32 @@ def _set_write_permission_and_retry(func, path, excinfo):
     func(path)
 
 
+# `mode=` parameter was added in filelock 3.10.0. We use it to create group-writable lock files (0o664).
+# If filelock is too old, we skip the `mode=` parameter and warn the user.
+_FILELOCK_SUPPORTS_MODE = packaging_version.parse(get_filelock_version()) >= packaging_version.parse("3.10.0")
+_FILELOCK_MODE_WARNING_EMITTED = False
+
+
+def _create_filelock(lock_cls: type, lock_file: Union[str, Path], **kwargs) -> BaseFileLock:
+    """Create a filelock instance, passing `mode=0o664` if supported by the installed filelock version."""
+    global _FILELOCK_MODE_WARNING_EMITTED
+    if _FILELOCK_SUPPORTS_MODE:
+        return lock_cls(lock_file, mode=0o664, **kwargs)
+    else:
+        if not _FILELOCK_MODE_WARNING_EMITTED:
+            warnings.warn(
+                f"filelock version {get_filelock_version()} does not support the `mode=` parameter. "
+                "Lock files will be created with the default mode. "
+                "Consider upgrading filelock to 3.10.0+ (`pip install -U filelock`) if you encounter "
+                "lock permission issues in a multi-user environment. "
+                "See https://github.com/huggingface/huggingface_hub/issues/3714 for more details.",
+                UserWarning,
+                stacklevel=3,
+            )
+            _FILELOCK_MODE_WARNING_EMITTED = True
+        return lock_cls(lock_file, **kwargs)
+
+
 @contextlib.contextmanager
 def WeakFileLock(
     lock_file: Union[str, Path], *, timeout: Optional[float] = None
@@ -89,7 +118,7 @@ def WeakFileLock(
     If a timeout is provided, a `filelock.Timeout` exception is raised if the lock is not acquired within the timeout.
     """
     log_interval = constants.FILELOCK_LOG_EVERY_SECONDS
-    lock = FileLock(lock_file, timeout=log_interval, mode=0o664)
+    lock = _create_filelock(FileLock, lock_file, timeout=log_interval)
     start_time = time.time()
 
     while True:
@@ -108,7 +137,7 @@ def WeakFileLock(
                 logger.warning(
                     "FileSystem does not appear to support flock. Falling back to SoftFileLock for %s", lock_file
                 )
-                lock = SoftFileLock(lock_file, timeout=log_interval)
+                lock = _create_filelock(SoftFileLock, lock_file, timeout=log_interval)
                 continue
         else:
             break

src/huggingface_hub/utils/_runtime.py

@@ -34,6 +34,7 @@
     "fastai": {"fastai"},
     "fastapi": {"fastapi"},
     "fastcore": {"fastcore"},
+    "filelock": {"filelock"},
     "gradio": {"gradio"},
     "graphviz": {"graphviz"},
     "hf_xet": {"hf_xet"},
@@ -126,6 +127,11 @@ def get_fastcore_version() -> str:
     return _get_version("fastcore")
 
 
+# Filelock
+def get_filelock_version() -> str:
+    return _get_version("filelock")
+
+
 # FastAI
 def is_gradio_available() -> bool:
     return is_package_available("gradio")