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

- **ID:** `pip/path-too-long-unpack`
- **领域:** pip
- **类别:** system_error
- **错误码:** `ERROR`
- **验证级别:** ai_generated
- **修复率:** 85%

## 根因

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

## 版本兼容性

| 版本 | 状态 | 引入 | 弃用 |
|------|------|------|------|
| pip 23.0 | active | — | — |
| pip 24.0 | active | — | — |
| pip 24.2 | active | — | — |

## 解决方案

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
   ```

## 无效尝试

- **Manually rename the wheel file to a shorter name before installing** — 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. (95% 失败率)
- **Use --no-deps to skip dependency installation** — The error occurs during extraction of the main package, not dependencies; skipping dependencies does not shorten the path of the package itself. (80% 失败率)
- **Reinstall Python to a shorter path like C:\Python** — 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. (60% 失败率)