Python 3.11下setuptools V80.9.0断言错误问题咨询

问题现象 #

安装Python 3.11及最新版setuptools（V80.9.0）后，导入setuptools或执行py -3.11 -m pip install .安装本地包时，触发断言错误，提示AssertionError: C:\Python311\Lib\distutils\core.py。将setuptools降级至59.8.0可恢复正常，但其他工具依赖新版本setuptools，导致版本冲突。

排查结论 #

执行core = importlib.import_module('distutils.core')时，Python优先导入了标准库路径下的C:\Python311\Lib\distutils\core.py，而setuptools预期使用自身内置的C:\Python311\lib\site-packages\setuptools\_distutils\core.py。此前使用Python 3.11无此问题，重装环境后出现异常。

错误日志 #

导入setuptools时的错误： #

C:\Users\ptib001\ARTS>py -3.11
Python 3.11.9 (tags/v3.11.9:de54cf5, Apr  2 2024, 10:12:12) [MSC v.1938 64 bit (AMD64)] on win32
Type "help", "copyright", "credits" or "license" for more information.
>>> import setuptools
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "C:\Python311\Lib\site-packages\setuptools\__init__.py", line 21, in <module>
    import _distutils_hack.override  # noqa: F401
    ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "C:\Python311\Lib\site-packages\_distutils_hack\override.py", line 1, in <module>
    __import__('_distutils_hack').do_override()
  File "C:\Python311\Lib\site-packages\_distutils_hack\__init__.py", line 89, in do_override
    ensure_local_distutils()
  File "C:\Python311\Lib\site-packages\_distutils_hack\__init__.py", line 76, in ensure_local_distutils
    assert '_distutils' in core.__file__, core.__file__
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
AssertionError: C:\Python311\Lib\distutils\core.py
>>>

安装本地包时的错误： #

C:\Users\ptib001\ARTS>py -3.11 -m pip install .
Processing c:\users\ptib001\arts
  Preparing metadata (setup.py) ... error
  error: subprocess-exited-with-error

  × python setup.py egg_info did not run successfully.
  │ exit code: 1
  ╰─> [14 lines of output]
      Traceback (most recent call last):
        File "<string>", line 2, in <module>
        File "<pip-setuptools-caller>", line 14, in <module>
        File "C:\Python311\Lib\site-packages\setuptools\__init__.py", line 21, in <module>
          import _distutils_hack.override  # noqa: F401
          ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
        File "C:\Python311\Lib\site-packages\_distutils_hack\override.py", line 1, in <module>
          __import__('_distutils_hack').do_override()
        File "C:\Python311\Lib\site-packages\_distutils_hack\__init__.py", line 89, in do_override
          ensure_local_distutils()
        File "C:\Python311\Lib\site-packages\_distutils_hack\__init__.py", line 76, in ensure_local_distutils
          assert '_distutils' in core.__file__, core.__file__
                 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
      AssertionError: C:\Python311\Lib\distutils\core.py
      [end of output]

  note: This error originates from a subprocess, and is likely not a problem with pip.
error: metadata-generation-failed

× Encountered error while generating package metadata.
╰─> See above for output.

note: This is an issue with the package mentioned above, not pip.
hint: See above for details.

解决方案 #

• 检查并清理PYTHONPATH：若系统或用户环境变量PYTHONPATH中包含C:\Python311\Lib\distutils，移除该路径后重启终端，确保Python优先加载setuptools内置的_distutils。
• 强制重装setuptools：执行命令py -3.11 -m pip install --force-reinstall setuptools==80.9.0，覆盖可能损坏的setuptools文件，确保其内置的_distutils被正确识别。
• 清理缓存文件：删除C:\Python311\Lib\distutils\__pycache__目录，以及C:\Python311\Lib\site-packages下与distutils相关的残留缓存文件，避免旧缓存干扰导入顺序。
• 使用虚拟环境隔离：创建独立虚拟环境规避全局依赖冲突，执行以下命令：

  py -3.11 -m venv myenv
  myenv\Scripts\activate
  pip install setuptools==80.9.0
  

  在激活的虚拟环境中安装所需工具及本地包。

内容的提问来源于stack exchange，提问作者TSobhy