# 错误：无法安装包，因为 OSError：[Errno 36] 文件名太长

- **ID:** `pip/wheel-install-fails-with-errno-36-file-name-too-long`
- **领域:** pip
- **类别:** system_error
- **错误码:** `ERROR`
- **验证级别:** ai_generated
- **修复率:** 75%

## 根因

解压后的 wheel 文件或其内部路径超过了文件系统的最大文件名长度（Linux/ext4 上通常为 255 字节，Windows 上为 260 个字符）。

## 版本兼容性

| 版本 | 状态 | 引入 | 弃用 |
|------|------|------|------|
| pip 21.0+ | active | — | — |
| Python 3.6-3.12 | active | — | — |
| Linux kernel 5.x+ | active | — | — |
| Windows 10/11 | active | — | — |

## 解决方案

1. ```
   pip install <包名> --target /tmp/短路径
   ```
2. ```
   pip install <包名> --no-compile --no-deps --no-build-isolation
   ```
3. ```
   在 Linux 上：安装到具有较长文件名限制的文件系统（例如 XFS 或带 dir_nlink 的 ext4），或使用符号链接缩短路径：mkdir -p /tmp/shortpip && ln -s /tmp/shortpip ~/shortpip && pip install <包名> --target ~/shortpip
   ```

## 无效尝试

- **Using --no-cache-dir option to avoid cache path issues** — The error occurs during wheel extraction, not caching; the filename length issue remains regardless of cache. (95% 失败率)
- **Upgrading pip to the latest version** — This is an OS-level filesystem limitation; pip's version does not affect filename length constraints. (90% 失败率)
- **Running pip as administrator or root** — Administrator privileges cannot override filesystem filename length limits. (95% 失败率)