【笔记】修复 ComfyUI 启动 ImportError: cannot import name ‘cached_download‘ 错误

GitHub - huggingface/huggingface_hub: The official Python client for the Hugging Face Hub.

huggingface-hub · PyPI

---

目录

报错示例

报错原因分析

解决方案

方案1：降级 huggingface_hub 到兼容版本

方案2：修改插件代码适配新版本（不推荐，升级后可能失效）

​编辑

为什么会出现这个错误？

验证是否成功

---

---

报错示例

Traceback (most recent call last):
  File "H:\PythonProjects1\Win_ComfyUI\nodes.py", line 2131, in load_custom_node
    module_spec.loader.exec_module(module)
  File "<frozen importlib._bootstrap_external>", line 999, in exec_module
  File "<frozen importlib._bootstrap>", line 488, in _call_with_frames_removed
  File "H:\PythonProjects1\Win_ComfyUI\custom_nodes\ComfyUI-layerdiffuse\__init__.py", line 1, in <module>
    from .layered_diffusion import NODE_CLASS_MAPPINGS, NODE_DISPLAY_NAME_MAPPINGS
  File "H:\PythonProjects1\Win_ComfyUI\custom_nodes\ComfyUI-layerdiffuse\layered_diffusion.py", line 22, in <module>
    from .lib_layerdiffusion.models import TransparentVAEDecoder
  File "H:\PythonProjects1\Win_ComfyUI\custom_nodes\ComfyUI-layerdiffuse\lib_layerdiffusion\models.py", line 8, in <module>
    from diffusers.configuration_utils import ConfigMixin, register_to_config
  File "H:\PythonProjects1\Win_ComfyUI\.venv\Lib\site-packages\diffusers\__init__.py", line 5, in <module>
    from .utils import (
  File "H:\PythonProjects1\Win_ComfyUI\.venv\Lib\site-packages\diffusers\utils\__init__.py", line 38, in <module>
    from .dynamic_modules_utils import get_class_from_dynamic_module
  File "H:\PythonProjects1\Win_ComfyUI\.venv\Lib\site-packages\diffusers\utils\dynamic_modules_utils.py", line 28, in <module>
    from huggingface_hub import cached_download, hf_hub_download, model_info
ImportError: cannot import name 'cached_download' from 'huggingface_hub' (H:\PythonProjects1\Win_ComfyUI\.venv\Lib\site-packages\huggingface_hub\__init__.py). Did you mean: 'hf_hub_download'?

Cannot import H:\PythonProjects1\Win_ComfyUI\custom_nodes\ComfyUI-layerdiffuse module for custom nodes: cannot import name 'cached_download' from 'huggingface_hub' (H:\PythonProjects1\Win_ComfyUI\.venv\Lib\site-packages\huggingface_hub\__init__.py)
 

---

---

报错原因分析

这个错误是因为 huggingface_hub 新版本中移除了 cached_download 函数，而 ComfyUI-layerdiffuse 插件还在使用这个被废弃的函数。

---

---

解决方案

以下是两种解决方案（推荐方案1，更简单稳定）：

方案1：降级 huggingface_hub 到兼容版本

cached_download 函数在 huggingface_hub==0.19.4 及以下版本中存在，降级后可直接解决兼容性问题：

1. 打开终端（或 ComfyUI 对应的虚拟环境终端）
2. 执行降级命令：

   # 如果使用 pip（大多数情况）
   pip install huggingface_hub==0.19.4# 如果使用 conda（少数情况）
   conda install -c conda-forge huggingface_hub=0.19.4
   

3. 重启 ComfyUI，插件应该能正常加载。

---

方案2：修改插件代码适配新版本（不推荐，升级后可能失效）

如果不想降级依赖，可以手动修改插件代码，用 hf_hub_download 替代 cached_download（官方推荐替代方案）：

1. 打开文件：H:\PythonProjects1\Win_ComfyUI\.venv\Lib\site-packages\diffusers\utils\dynamic_modules_utils.py
2. 找到第28行代码：

   from huggingface_hub import cached_download, hf_hub_download, model_info
   

3. 修改为（删除 cached_download）：

   from huggingface_hub import hf_hub_download, model_info
   

4. 同时需要替换文件中所有 cached_download 调用为 hf_hub_download（如果有的话）：
   • 搜索文件中 cached_download( 替换为 hf_hub_download(
5. 保存文件后重启 ComfyUI。

---

为什么会出现这个错误？

• huggingface_hub 在 0.20.0 版本后废弃了 cached_download，统一使用 hf_hub_download
• diffusers 库的某个版本还在引用旧函数，而你的 huggingface_hub 已经是新版本
• 方案1通过降级 huggingface_hub 解决兼容性，方案2通过修改代码适配新版本

---

验证是否成功

重启 ComfyUI 后，如果没有再出现 ImportError: cannot import name 'cached_download' 错误，且 ComfyUI-layerdiffuse 插件的节点能正常显示，说明修复成功。