xiaowei-system/skills/devops/devops-umbrella/references/windows-python-pip.md

Windows Python Pip 故障排查

原 skill：windows-python-pip，已合并到 devops-umbrella。

Windows 上使用 pip install 安装 Python CLI 包后，经常遇到命令行入口（*.exe）找不到、被旧版本覆盖、或 PATH 冲突的问题。

触发条件

• pip install <package> 后 where <command> 找不到
• 命令行工具报错 ModuleNotFoundError
• 新安装的版本被旧版本覆盖
• uv tool 或 pip 混用导致入口点混乱
• 同一工具存在多个版本残留

排查流程

第一步：确认安装状态

pip show <package>
where <command>
Get-ChildItem "$env:LOCALAPPDATA\Programs\Python\Python<version>\Scripts\<command>*"

第二步：定位冲突来源

位置	说明
%USERPROFILE%\.local\bin\	uv tool 安装的入口点
%USERPROFILE%\AppData\Roaming\uv\tools\	uv tool 完整安装目录
%LOCALAPPDATA%\Programs\Python\Python<ver>\Scripts\	pip 安装的入口点
%USERPROFILE%\.hermes\	Hermes 相关安装目录

第三步：清理旧版本

pip uninstall <package> -y
uv tool uninstall <package>    # 如果用 uv 安装过
Remove-Item "$env:USERPROFILE\.local\bin\<command>*" -ErrorAction SilentlyContinue
Remove-Item "$env:LOCALAPPDATA\Programs\Python\Python<ver>\Scripts\<command>*" -ErrorAction SilentlyContinue

第四步：重新安装

pip install --force-reinstall --no-cache-dir <package>==<version>

第五步：验证

where <command>                    # 只返回一个路径
python -c "import <module>; print(<module>.__version__)"  # 成功
<command> --version                # 成功

常见痛点

痛点1：ModuleNotFoundError 但 pip 显示已安装

修复：完全清理后使用特定版本

pip uninstall <package> -y
pip install --no-cache-dir <package>==<known-good-version>

痛点2：uv tool 和 pip 混用导致入口点混乱

修复：统一使用 pip，删除 uv 版本

uv tool uninstall <package>
pip install <package>

痛点3：Scripts 目录不在 PATH 中

$pythonScripts = "$env:LOCALAPPDATA\Programs\Python\Python<ver>\Scripts"
$currentPath = [Environment]::GetEnvironmentVariable("PATH", "User")
if (-not $currentPath.Contains($pythonScripts)) {
    [Environment]::SetEnvironmentVariable("PATH", "$currentPath;$pythonScripts", "User")
}

经验法则

规则	说明
彻底清理后再重装	不要叠加安装，先完全删除所有旧版本
优先使用 pip	在 Windows 上，pip install 比 uv tool install 更可靠
验证时先用 Python	python -c "import module" 比命令行更可靠
--force-reinstall 强于 install	可以重新生成损坏的 entry points