# 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` 混用导致入口点混乱
- 同一工具存在多个版本残留

## 排查流程

### 第一步：确认安装状态

```powershell
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 相关安装目录 |

### 第三步：清理旧版本

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

### 第四步：重新安装

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

### 第五步：验证

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

## 常见痛点

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

**修复**：完全清理后使用特定版本
```powershell
pip uninstall <package> -y
pip install --no-cache-dir <package>==<known-good-version>
```

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

**修复**：统一使用 pip，删除 uv 版本
```powershell
uv tool uninstall <package>
pip install <package>
```

### 痛点3：Scripts 目录不在 PATH 中

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