{
  "id": "pip/legacy-install-failure-numpy",
  "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.",
  "signature_zh": "错误：legacy-install-failure\n× 尝试安装包时遇到错误。\n╰─> numpy\n\n注意：这是上述包的问题，不是 pip 的问题。",
  "regex": "error: legacy-install-failure.*Encountered error while trying to install package\\.\\n╰─> .*",
  "domain": "pip",
  "category": "build_error",
  "subcategory": null,
  "root_cause": "The package (e.g., numpy) requires a legacy build system (setup.py) that fails due to missing build dependencies or compiler issues, often because the package does not provide pre-built wheels for the platform.",
  "root_cause_type": "generic",
  "root_cause_zh": "包（例如 numpy）需要旧版构建系统（setup.py），但由于缺少构建依赖项或编译器问题而失败，通常是因为该包未提供针对该平台的预编译 wheel。",
  "versions": [
    {
      "version": "pip 21.0",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    },
    {
      "version": "pip 23.0",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    },
    {
      "version": "pip 24.0",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    }
  ],
  "os_specific": {},
  "dead_ends": [
    {
      "action": "Reinstall pip and retry, assuming pip itself is broken.",
      "why_fails": "The error is from the package's build system, not pip's installation.",
      "fail_rate": 0.9,
      "condition": "",
      "sources": []
    },
    {
      "action": "Use `pip install --no-build-isolation numpy` without fixing the underlying build tools.",
      "why_fails": "This may expose more errors but doesn't fix missing compilers or libraries.",
      "fail_rate": 0.7,
      "condition": "",
      "sources": []
    },
    {
      "action": "Install numpy from a different index without verifying the version.",
      "why_fails": "The same build failure will occur if no pre-built wheel exists.",
      "fail_rate": 0.8,
      "condition": "",
      "sources": []
    }
  ],
  "workarounds": [
    {
      "action": "Install a pre-built wheel if available: `pip install numpy --only-binary :all:` or use `pip install numpy==1.24.3` (a version with wheels for most platforms).",
      "success_rate": 0.9,
      "how": "Install a pre-built wheel if available: `pip install numpy --only-binary :all:` or use `pip install numpy==1.24.3` (a version with wheels for most platforms).",
      "condition": "",
      "sources": []
    },
    {
      "action": "Install system build dependencies: on Ubuntu, run `sudo apt-get install python3-dev build-essential`; on macOS, `xcode-select --install`.",
      "success_rate": 0.85,
      "how": "Install system build dependencies: on Ubuntu, run `sudo apt-get install python3-dev build-essential`; on macOS, `xcode-select --install`.",
      "condition": "",
      "sources": []
    },
    {
      "action": "Use conda as an alternative: `conda install numpy` which provides pre-compiled binaries.",
      "success_rate": 0.95,
      "how": "Use conda as an alternative: `conda install numpy` which provides pre-compiled binaries.",
      "condition": "",
      "sources": []
    }
  ],
  "workarounds_zh": [
    "如果可用，安装预编译 wheel：`pip install numpy --only-binary :all:` 或使用 `pip install numpy==1.24.3`（该版本为大多数平台提供 wheel）。",
    "安装系统构建依赖：在 Ubuntu 上运行 `sudo apt-get install python3-dev build-essential`；在 macOS 上运行 `xcode-select --install`。",
    "使用 conda 作为替代方案：`conda install numpy` 提供预编译的二进制文件。"
  ],
  "transition_graph": {
    "leads_to": [],
    "preceded_by": [],
    "frequently_confused_with": []
  },
  "official_doc_url": "https://pip.pypa.io/en/stable/topics/legacy-builds/",
  "official_doc_section": null,
  "error_code": "error",
  "verification_tier": "ai_generated",
  "confidence": 0.84,
  "fix_success_rate": 0.88,
  "resolvable": "true",
  "first_seen": "2023-09-18",
  "last_confirmed": "2024-06-01",
  "last_updated": "2024-06-01",
  "evidence_count": 1,
  "tags": [],
  "locale": "en",
  "aliases": []
}