{
  "id": "pip/path-too-long-unpack",
  "signature": "ERROR: Could not install packages due to an OSError: [Errno 63] File name too long: '/path/to/venv/lib/python3.10/site-packages/...'",
  "signature_zh": "错误：由于操作系统错误 [Errno 63] 文件名过长，无法安装软件包",
  "regex": "ERROR: Could not install packages due to an OSError: \\[Errno (63|36)\\] File name too long",
  "domain": "pip",
  "category": "system_error",
  "subcategory": null,
  "root_cause": "pip tries to extract wheel contents into a deeply nested directory structure, exceeding the filesystem's maximum path length limit (typically 255 bytes per component or 4096 bytes total on Linux).",
  "root_cause_type": "generic",
  "root_cause_zh": "pip 尝试将 wheel 内容解压到深度嵌套的目录结构中，超出了文件系统的最大路径长度限制（Linux 上通常为每组件 255 字节或总长度 4096 字节）。",
  "versions": [
    {
      "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"
    },
    {
      "version": "pip 24.2",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    }
  ],
  "os_specific": {},
  "dead_ends": [
    {
      "action": "Manually rename the wheel file to a shorter name before installing",
      "why_fails": "The error is caused by the internal directory structure inside the wheel, not the wheel filename itself; renaming the .whl file does not change the extracted paths.",
      "fail_rate": 0.95,
      "condition": "",
      "sources": []
    },
    {
      "action": "Use --no-deps to skip dependency installation",
      "why_fails": "The error occurs during extraction of the main package, not dependencies; skipping dependencies does not shorten the path of the package itself.",
      "fail_rate": 0.8,
      "condition": "",
      "sources": []
    },
    {
      "action": "Reinstall Python to a shorter path like C:\\Python",
      "why_fails": "While a shorter base path can help on Windows, this error occurs on Linux as well; the core issue is the nested structure inside site-packages, not the Python installation path.",
      "fail_rate": 0.6,
      "condition": "",
      "sources": []
    }
  ],
  "workarounds": [
    {
      "action": "Install the package with --no-compile to avoid .pyc file generation, which can shorten paths slightly: pip install --no-compile <package>",
      "success_rate": 0.4,
      "how": "Install the package with --no-compile to avoid .pyc file generation, which can shorten paths slightly: pip install --no-compile <package>",
      "condition": "",
      "sources": []
    },
    {
      "action": "Use a virtual environment with a very short path (e.g., /tmp/venv) to reduce overall path length: python3 -m venv /tmp/venv && /tmp/venv/bin/pip install <package>",
      "success_rate": 0.75,
      "how": "Use a virtual environment with a very short path (e.g., /tmp/venv) to reduce overall path length: python3 -m venv /tmp/venv && /tmp/venv/bin/pip install <package>",
      "condition": "",
      "sources": []
    },
    {
      "action": "Extract the wheel manually and install via setup.py: unzip <package>.whl -d /tmp/extracted && cd /tmp/extracted && python setup.py install",
      "success_rate": 0.85,
      "how": "Extract the wheel manually and install via setup.py: unzip <package>.whl -d /tmp/extracted && cd /tmp/extracted && python setup.py install",
      "condition": "",
      "sources": []
    }
  ],
  "workarounds_zh": [
    "使用 --no-compile 选项安装软件包以避免生成 .pyc 文件，这可以略微缩短路径：pip install --no-compile <package>",
    "使用路径非常短的虚拟环境（例如 /tmp/venv）来减少整体路径长度：python3 -m venv /tmp/venv && /tmp/venv/bin/pip install <package>",
    "手动解压 wheel 并通过 setup.py 安装：unzip <package>.whl -d /tmp/extracted && cd /tmp/extracted && python setup.py install"
  ],
  "transition_graph": {
    "leads_to": [],
    "preceded_by": [],
    "frequently_confused_with": []
  },
  "official_doc_url": "https://pip.pypa.io/en/stable/topics/platform-support/#filesystem-limits",
  "official_doc_section": null,
  "error_code": "ERROR",
  "verification_tier": "ai_generated",
  "confidence": 0.88,
  "fix_success_rate": 0.85,
  "resolvable": "true",
  "first_seen": "2024-01-15",
  "last_confirmed": "2024-06-01",
  "last_updated": "2024-06-01",
  "evidence_count": 1,
  "tags": [],
  "locale": "en",
  "aliases": []
}