fix snapshot download behavior in offline mode when downloading to a local dir

src/huggingface_hub/_snapshot_download.py

@@ -200,12 +200,13 @@ def snapshot_download(
                     commit_hash = f.read()
 
         # Try to locate snapshot folder for this commit hash
-        if commit_hash is not None:
+        if commit_hash is not None and local_dir is None:
             snapshot_folder = os.path.join(storage_folder, "snapshots", commit_hash)
             if os.path.exists(snapshot_folder):
                 # Snapshot folder exists => let's return it
                 # (but we can't check if all the files are actually there)
                 return snapshot_folder
+
         # If local_dir is not None, return it if it exists and is not empty
         if local_dir is not None:
             local_dir = Path(local_dir)
@@ -214,6 +215,12 @@ def snapshot_download(
                     f"Returning existing local_dir `{local_dir}` as remote repo cannot be accessed in `snapshot_download` ({api_call_error})."
                 )
                 return str(local_dir.resolve())
+            # If local_dir doesn't exist or is empty, raise an error when in offline mode
+            raise LocalEntryNotFoundError(
+                f"Cannot download files to the specified local directory '{local_dir}' as remote repo cannot be "
+                f"accessed in offline mode. Please check your internet connection or set HF_HUB_OFFLINE=0 to enable "
+                f"online mode."
+            )
         # If we couldn't find the appropriate folder on disk, raise an error.
         if local_files_only:
             raise LocalEntryNotFoundError(

tests/test_snapshot_download.py

@@ -162,6 +162,17 @@ def test_download_model_to_local_dir_with_offline_mode(self):
                     storage_folder = snapshot_download(self.repo_id, local_dir=tmpdir)
                     self.assertEqual(str(tmpdir), storage_folder)
 
+    def test_offline_mode_with_cache_and_empty_local_dir(self):
+        """Test that when cache exists but an empty local_dir is specified in offline mode, we raise an error."""
+        with SoftTemporaryDirectory() as tmpdir_cache:
+            snapshot_download(self.repo_id, cache_dir=tmpdir_cache)
+
+            for offline_mode in OfflineSimulationMode:
+                with offline(mode=offline_mode):
+                    with self.assertRaises(LocalEntryNotFoundError):
+                        with SoftTemporaryDirectory() as tmpdir:
+                            snapshot_download(self.repo_id, cache_dir=tmpdir_cache, local_dir=tmpdir)
+
     def test_download_model_offline_mode_not_in_local_dir(self):
         """Test when connection error but local_dir is empty."""
         with SoftTemporaryDirectory() as tmpdir: