92 lines
2.8 KiB
Markdown
Executable File
92 lines
2.8 KiB
Markdown
Executable File
# 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 | |