【Python】解决 Windows 下 pip 安装报错 OSError: [Errno 2] No such file or directory (路径过长问题)

1. 问题描述

2. 原因分析

3. 解决方案

方案一：修改临时目录路径（最快，无需重启）

方案二：解除 Windows 路径长度限制（一劳永逸）

4. 总结

给您的建议（发文前可看）：

【Python】解决 Windows 下 pip 安装报错 OSError: [Errno 2] No such file or directory (路径过长问题)

1. 问题描述

在使用 pip 安装某些 Python 包（特别是像volcengine-python-sdk、aws-cli或深度学习相关的这种目录层级很深的 SDK 包）时，突然爆出如下错误：

报错信息示例：

Bash

ERROR: Could not install packages due to an OSError: [Errno 2] No such file or directory: 'C:\\Users\\Administrator\\AppData\\Local\\Temp\\pip-install-ml1b_jcg\\volcengine-python-sdk_dd84aee360a44c31af85b7de292e2695\\volcenginesdktransitrouter\\models\\transit_router_traffic_qos_marking_policy_for_describe_transit_router_traffic_qos_marking_policies_output.py'

乍一看以为是文件丢失或者权限问题，但仔细观察报错路径，发现文件路径异常的长。

2. 原因分析

这个问题的根本原因在于Windows 系统默认的文件路径长度限制（MAX_PATH）。

MAX_PATH 限制：Windows API 默认定义的最大路径长度为260 个字符。
Pip 的安装机制：Pip 在安装包时，会先将其解压到系统的临时目录（通常是C:\Users\用户名\AppData\Local\Temp\...）。
冲突点：如果你安装的包本身目录结构就很深（如上面的volcengine-python-sdk），文件名又很长，再加上 Windows 冗长的临时目录前缀，总路径长度很容易就超过了 260 个字符，导致系统无法写入或读取该文件，从而抛出[Errno 2] No such file or directory。

3. 解决方案

针对这个问题，有两种解决方案：一种是临时规避（推荐快速解决），一种是永久解除限制（推荐开发环境配置）。

方案一：修改临时目录路径（最快，无需重启）

既然问题出在路径太长，我们可以通过设置环境变量，把 pip 的临时工作目录指定到一个极短的路径（例如C:\tmp），从而“腾出”更多的字符空间给文件名。

操作步骤：

在 C 盘根目录下新建一个文件夹，命名为tmp。
在命令行中设置临时环境变量，并重新执行安装命令。

CMD (命令提示符) 用户执行：

DOS

set TEMP=C:\tmp set TMP=C:\tmp pip install volcengine-python-sdk

PowerShell 用户执行：

PowerShell

$env:TEMP="C:\tmp" $env:TMP="C:\tmp" pip install volcengine-python-sdk

注意：这种方式只在当前终端窗口有效，关闭后环境变量会恢复默认，不会影响系统其他软件的运行。

方案二：解除 Windows 路径长度限制（一劳永逸）

如果你是 Windows 10 (版本1607及以上) 或 Windows 11 用户，可以直接在注册表中解除 260 字符的限制。

操作步骤：

按下Win + R键，输入regedit并回车，打开注册表编辑器。
在地址栏输入或逐级定位到以下路径：
HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\FileSystem
在右侧列表中找到名为LongPathsEnabled的项。
- 如果找不到，请右键空白处 ->新建->DWORD (32位) 值，命名为LongPathsEnabled。
双击LongPathsEnabled，将其数值数据修改为1。
点击确定，关闭注册表。
重要：重启电脑（或重启你的 IDE/终端）使配置生效。

生效后，Python 和 Git 等工具就可以支持超过 260 字符的长路径了。

4. 总结

在 Windows 上开发 Python 项目时，路径过长是一个老生常谈的坑。

如果是临时遇到这个问题，建议使用方案一，简单快捷，没有副作用。
如果是长期使用Windows 进行开发，建议使用方案二彻底修改注册表，避免以后安装其他大型库（如 TensorFlow, PyTorch 等）时再次踩坑。

希望这篇文章能帮到遇到同样问题的你，如果有帮助请点赞收藏！

给您的建议（发文前可看）：

标签建议：选择Python、Pip、Windows、运维、Bug调试。
摘要建议：在 Windows 使用 pip 安装 Python 包时报错 OSError: [Errno 2] No such file or directory，通常是由于 MAX_PATH 路径长度限制导致的。本文介绍了两种解决方法：修改临时环境变量和修改注册表解除限制。
封面图：CSDN 发文时建议配一张带有 Python Logo 或报错截图的图片，点击率会更高。