{
  "id": "pip/legacy-setup-py-install-error",
  "signature": "error: legacy-install-failure\n× Encountered error while trying to install package.\n╰─> numpy\n\nnote: This is an issue with the package mentioned above, not pip.\nhint: See the output of 'pip debug --verbose' for an overview of the current compatibility.",
  "signature_zh": "错误：传统安装失败\n× 尝试安装包时遇到错误。\n╰> numpy\n\n注意：这是上述包的问题，不是 pip 的问题。\n提示：查看 'pip debug --verbose' 的输出以了解当前兼容性概览。",
  "regex": "error: legacy-install-failure",
  "domain": "pip",
  "category": "build_error",
  "subcategory": null,
  "root_cause": "Pip's legacy setup.py install path failed because the package (e.g., numpy) uses an outdated build system that is incompatible with the current pip or Python version, often due to missing compiler toolchain or unsupported build flags.",
  "root_cause_type": "generic",
  "root_cause_zh": "Pip 的传统 setup.py 安装路径失败，因为包（例如 numpy）使用了与当前 pip 或 Python 版本不兼容的过时构建系统，通常是由于缺少编译器工具链或不支持的构建标志。",
  "versions": [
    {
      "version": "pip 21.3+",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    },
    {
      "version": "numpy <1.20",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    },
    {
      "version": "Python 3.10",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    }
  ],
  "os_specific": {},
  "dead_ends": [
    {
      "action": "Reinstalling pip with --upgrade pip",
      "why_fails": "Upgrading pip alone does not fix the underlying build system incompatibility; the issue is with the package's setup.py, not pip itself.",
      "fail_rate": 0.2,
      "condition": "",
      "sources": []
    },
    {
      "action": "Manually running python setup.py install in the package directory",
      "why_fails": "This bypasses pip but still uses the same broken build system, leading to the same error or different cryptic failures.",
      "fail_rate": 0.5,
      "condition": "",
      "sources": []
    },
    {
      "action": "Installing with --no-build-isolation flag",
      "why_fails": "This may expose missing system dependencies but does not fix the core setup.py issue; often results in different build errors.",
      "fail_rate": 0.4,
      "condition": "",
      "sources": []
    }
  ],
  "workarounds": [
    {
      "action": "Upgrade the package to a version that supports modern build backends: pip install numpy>=1.20",
      "success_rate": 0.85,
      "how": "Upgrade the package to a version that supports modern build backends: pip install numpy>=1.20",
      "condition": "",
      "sources": []
    },
    {
      "action": "Use a pre-built wheel if available: pip install --only-binary=:all: numpy",
      "success_rate": 0.9,
      "how": "Use a pre-built wheel if available: pip install --only-binary=:all: numpy",
      "condition": "",
      "sources": []
    },
    {
      "action": "Install a compatible Python version that still supports the legacy setup.py (e.g., Python 3.8) and use pip<21.0",
      "success_rate": 0.75,
      "how": "Install a compatible Python version that still supports the legacy setup.py (e.g., Python 3.8) and use pip<21.0",
      "condition": "",
      "sources": []
    }
  ],
  "workarounds_zh": [
    "将包升级到支持现代构建后端的版本：pip install numpy>=1.20",
    "如果可用，使用预构建的 wheel：pip install --only-binary=:all: numpy",
    "安装仍支持传统 setup.py 的兼容 Python 版本（例如 Python 3.8）并使用 pip<21.0"
  ],
  "transition_graph": {
    "leads_to": [],
    "preceded_by": [],
    "frequently_confused_with": []
  },
  "official_doc_url": "https://pip.pypa.io/en/stable/topics/backtracking/",
  "official_doc_section": null,
  "error_code": "error",
  "verification_tier": "ai_generated",
  "confidence": 0.85,
  "fix_success_rate": 0.8,
  "resolvable": "true",
  "first_seen": "2023-11-15",
  "last_confirmed": "2024-06-01",
  "last_updated": "2024-06-01",
  "evidence_count": 1,
  "tags": [],
  "locale": "en",
  "aliases": []
}