日常开发中，我们常会遇到第三方库的各种运行报错，尤其是新版本 Python 环境下，依赖包的兼容性问题更是让人头疼。最近在使用 ModelScope 时，就踩了一连串的坑 —— 从pkg_resources模块找不到，到ImpImporter属性缺失，再到依赖版本冲突。折腾了一圈才发现，问题的核心在于 Python 版本与 ModelScope 生态的适配性。
本文就把整个排错过程、根因分析和经过实测验证的解决方案完整梳理出来，帮大家少走弯路。
一、 遇到的 3 类典型报错及现象
报错 1：ModuleNotFoundError: No module named 'pkg_resources'
安装好 ModelScope 后，执行命令直接报错，日志如下：
Traceback (most recent call last):
File "", line 198, in _run_module_as_main
File "", line 88, in run_code
File "xxx\Scripts\modelscope.exe_main.py", line 2, in
from modelscope.cli.cli import run_cmd
File "xxx\Lib\site-packages\modelscope\cli\cli.py", line 13, in
from modelscope.cli.plugins import PluginsCMD
File "xxx\Lib\site-packages\modelscope\cli\plugins.py", line 6, in
from modelscope.utils.plugins import PluginsManager
File "xxx\Lib\site-packages\modelscope\utils\plugins.py", line 18, in
import pkg_resources
ModuleNotFoundError: No module named 'pkg_resources'
当时第一反应是setuptools没装？但执行pip show setuptools，发现版本是 82.0.0，明明已经安装。
报错 2：AttributeError: module 'pkgutil' has no attribute 'ImpImporter'
降级setuptools到 65.5.0 版本后，pkg_resources的错误消失了，却又冒出新的报错：
File "xxx\Lib\site-packages\pkg_resources_init_.py", line 2191, in
register_finder(pkgutil.ImpImporter, find_on_path)
^^^^^^^^^^^^^^^^^^^
AttributeError: module 'pkgutil' has no attribute 'ImpImporter'. Did you mean: 'zipimporter'?
这个报错更费解 —— 代码里明明写了pkgutil.ImpImporter，怎么会找不到？
报错 3：依赖包版本冲突
除此之外，还遇到了依赖版本不兼容的提示：
poetry 0.12.17 requires pyparsing<3.0,>=2.2, but you have pyparsing 3.2.5 which is incompatible.
torchscale 0.3.0 requires fairscale==0.4.0, but you have fairscale 0.4.13 which is incompatible.
多个库的依赖版本互相 “打架”，进一步加剧了运行异常。
二、 抽丝剥茧：根因分析
经过反复测试和查资料，终于理清了问题的本质，核心原因是 Python 版本与 ModelScope 生态的适配性问题：
1.关于pkg_resources找不到的问题：
pkg_resources是setuptools的内置模块，在新版setuptools（80 + 版本）中，官方重构了内部结构，移除了pkg_resources的独立导入方式；而 ModelScope 的源码中仍在使用import pkg_resources的旧逻辑，因此触发 “模块找不到” 的错误。
2.关于ImpImporter属性缺失的问题：
这是关键的底层原因：Python 3.13 版本对标准库进行了调整，彻底移除了pkgutil模块中的ImpImporter属性。而旧版本setuptools（如 65.5.0）的源码中，依然依赖这个属性，即使修复了pkg_resources的导入问题，也会触发属性缺失的报错。
3.关于依赖版本冲突的问题：
Python 3.13 作为较新的版本，很多第三方库（如 poetry、torchscale）还没完成适配，其发布的版本约束与新版 Python 环境下安装的依赖包版本不匹配，从而引发冲突。
划重点：经过实测，ModelScope 目前最高推荐使用 Python 3.12 版本，可稳定运行；Python 3.13 因底层 API 变更，只能通过源码修改进行兼容，复杂度高且不可控。
三、 实测可行的解决方案：彻底根治（推荐）
经过多次验证，使用 ModelScope 官方适配的 Python 版本是靠谱的解决方案，实测 Python 3.12 可完美运行，步骤如下：
步骤 1：安装 Python 3.12（或 3.10/3.11，均为稳定版）
下载地址：Python 3.12.0 官方下载（选择对应系统的安装包，Windows 推荐 64 位安装器）
安装时务必勾选：
✅ Add Python 3.12 to PATH（避免手动配置环境变量）
✅ Install for all users（全局可用，避免权限问题）
安装完成后，打开命令行执行python --version，确认输出为Python 3.12.x。
步骤 2：创建并激活虚拟环境（强烈推荐）
隔离不同项目的依赖，避免全局环境被污染，这是 Python 开发的最佳实践：
点击查看代码
# 创建名为modelscope-venv的虚拟环境（名称可自定义）
python -m venv modelscope-venv# Windows系统激活环境（cmd命令行）
modelscope-venv\Scripts\activate# Windows系统激活环境（PowerShell）
.\modelscope-venv\Scripts\Activate.ps1# Linux/Mac系统激活环境
source modelscope-venv/bin/activate
步骤 3：安装 ModelScope 及依赖（实测稳定版）
点击查看代码
# 升级pip到最新版，避免安装过程中报错
python -m pip install --upgrade pip# 安装ModelScope核心包
pip install modelscope
步骤 4：验证运行效果
执行以下命令，若输出 ModelScope 版本号且无报错，则说明环境配置成功：
点击查看代码
modelscope --version
四、 避坑总结与建议
版本选择优先看官方文档：第三方库的兼容性往往滞后于 Python 新版本，使用 ModelScope 前优先选择 3.10-3.12 的稳定版本，避免踩 3.13 的适配坑。
虚拟环境是刚需：多项目开发时，一定要用 venv 或 conda 创建独立虚拟环境，彻底避免全局依赖版本冲突。
不要盲目修改源码：Python 3.13 下修改setuptools或 ModelScope 源码的方式，仅能绕过个别报错，后续可能触发更多未知问题（如插件加载失败、模型推理异常），不建议使用。
希望这篇文章能帮大家避开 ModelScope 的版本适配坑，高效完成开发！