ERROR pip system_error ai_generated true

错误：由于操作系统错误 [Errno 63] 文件名过长，无法安装软件包

ERROR: Could not install packages due to an OSError: [Errno 63] File name too long: '/path/to/venv/lib/python3.10/site-packages/...'

ID: pip/path-too-long-unpack

其他格式: JSON · Markdown 中文 · English
85%修复率
88%置信度
1证据数
2024-01-15首次发现

版本兼容性

版本状态引入弃用备注
pip 23.0 active — — —
pip 24.0 active — — —
pip 24.2 active — — —

根因分析

pip 尝试将 wheel 内容解压到深度嵌套的目录结构中，超出了文件系统的最大路径长度限制（Linux 上通常为每组件 255 字节或总长度 4096 字节）。

English

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).

generic

官方文档

https://pip.pypa.io/en/stable/topics/platform-support/#filesystem-limits

解决方案

  1. 使用 --no-compile 选项安装软件包以避免生成 .pyc 文件，这可以略微缩短路径：pip install --no-compile <package>
  2. 使用路径非常短的虚拟环境（例如 /tmp/venv）来减少整体路径长度：python3 -m venv /tmp/venv && /tmp/venv/bin/pip install <package>
  3. 手动解压 wheel 并通过 setup.py 安装：unzip <package>.whl -d /tmp/extracted && cd /tmp/extracted && python setup.py install

无效尝试

常见但无效的做法:

  1. Manually rename the wheel file to a shorter name before installing 95% 失败

    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.

  2. Use --no-deps to skip dependency installation 80% 失败

    The error occurs during extraction of the main package, not dependencies; skipping dependencies does not shorten the path of the package itself.

  3. Reinstall Python to a shorter path like C:\Python 60% 失败

    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.