Windows下pip安装报路径过长错误是因系统默认MAX_PATH限制260字符，需同时启用注册表LongPathsEnabled、使用PowerShell运行、pip≥21.3，并可通过修改TEMP/TMP环境变量或缩短安装路径临时/永久解决。
Windows 下 Python 安装或 pip install 报 OSError: [Errno 2] No such file or directory 或 [WinError 206] The filename or extension is too long，基本就是 MAX_PATH 限制在作祟——不是你装错了，是系统默认只认 260 字符以内的路径。
为什么 pip install 会卡在“No such file or directory”
这不是权限、网络或包损坏问题。pip 解包时会在临时目录（如 C:\Users\Alice\AppData\Local\Temp\pip-install-xxxxxx\）里层层展开嵌套文件夹，一旦总长度超 260 字符，Windows 底层 API（如 CreateDirectoryW）直接拒绝创建，报错就表现为“文件不存在”。典型触发包有 volcengine-python-sdk、tensorflow、aws-cli 等依赖深、文件名长的库。
- 错误路径越长（尤其含中文用户名、深层虚拟环境、长项目名），越容易触发
- PyCharm/VS Code 里能装成功，但命令行失败？因为 IDE 常悄悄改了
PYTHONPATH或用短路径启动 Python，掩盖了真实问题 -
python -m venv创建虚拟环境失败，也是同一原因：临时构建路径太长
注册表 LongPathsEnabled=1 是必要但不充分条件
只改注册表 ≠ 万事大吉。必须同时满足三项：
- 注册表项
HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\FileSystem\LongPathsEnabled值为1（需管理员权限执行Set-ItemProperty ... -Value 1） - 使用 PowerShell（非
cmd.exe）运行pip install；cmd不传递长路径上下文给子进程 -
pip版本 ≥ 21.3（2021 年后发布），旧版 pip 内部没适配\?\前缀路径逻辑
验证是否生效：python -c "import os; print(os.path.supports_long_paths)" 输出 True 才算真正启用。
立即学习“Python免费学习笔记（深入）”；
临时绕过：改 TEMP 和 TMP 环境变量
不用改注册表、不用重启，5 分钟内见效。原理是把 pip 的解压临时目录挪到极短路径下，腾出足够字符空间给包自身路径。
- 新建一个短路径文件夹，例如
C:\tmp - 设置系统环境变量：
set TEMP=C:\tmp和set TMP=C:\tmp（PowerShell 中用$env:TEMP="C:\tmp"） - 重新打开终端，再运行
pip install package_name
注意：--no-cache-dir 可配合使用，避免 %LOCALAPPDATA%\pip\Cache 下也生成长路径缓存。
长期开发建议：从安装 Python 就控制路径深度
很多问题其实在第一步就埋下了。重装或新装 Python 时请严格遵循：
- 安装路径选根目录，例如
C:\Python312，**绝不**用C:\Users\YourName\AppData\Local\Programs\Python\Python312 - 勾选安装器里的
Disable path length limit（它会自动设好注册表 + 给 Python 进程加长路径支持） - 虚拟环境统一建在短路径下：
python -m venv C:\venv\py312，而非C:\Users\...\venv - 项目根目录也尽量扁平：
C:\proj\ml比C:\Users\...\Documents\GitHub\my-company\backend\services\api\src安全得多
最易被忽略的一点：即使注册表开了、Python 版本够新，如果父进程（比如你双击打开的 cmd.exe）本身没启用长路径能力，所有子 Python 进程仍会被降级。所以日常开发，请养成用 PowerShell 启动终端的习惯。
