python install_error ai_generated true

错误：元数据生成失败 × 生成包元数据时遇到错误。

error: metadata-generation-failed × Encountered error while generating package metadata. ╰─> See above for output.

ID: python/pip-install-metadata-generation-failed

其他格式: JSON · Markdown 中文 · English
80%修复率
88%置信度
0证据数
2024-03-12首次发现

版本兼容性

版本状态引入弃用备注
3.8 active — — —
3.9 active — — —
3.10 active — — —
3.11 active — — —
3.12 active — — —

根因分析

pip 使用 PEP 517 构建隔离在独立环境中构建 wheel 元数据。如果构建后端（setuptools、hatchling、poetry-core）缺失或构建依赖未在 pyproject.toml 中声明，元数据生成会在实际安装前失败。

English

pip uses PEP 517 build isolation to build wheel metadata in an isolated environment. If the build backend (setuptools, hatchling, poetry-core) is missing or a build dependency is not declared in pyproject.toml, metadata generation fails before the actual install.

generic

解决方案

  1. 85% 成功率 
    pip install setuptools wheel
pip install --no-build-isolation ./mypackage
  2. 90% 成功率 
    [build-system]
requires = ["setuptools>=64", "wheel", "cython"]
build-backend = "setuptools.build_meta"
  3. 80% 成功率 
    pip install -v ./mypackage 2>&1 | grep -A5 'Error'

无效尝试

常见但无效的做法:

  1. 55% 失败

    Disables isolation but the missing build dependency is still not present in the current environment, so the backend import fails anyway.

  2. 70% 失败

    The failure is in the build backend invocation, not a corrupted download; clearing cache does not add missing build deps.

  3. 60% 失败

    Newer pip still respects pyproject.toml build-system requirements; the missing dependency is unchanged.