如何解决 pip install 安装报错检测到 yanked 版本需更换可用版本问题

Python系列Bug修复PyCharm控制台pip install报错：如何解决 pip install 安装报错检测到 yanked 版本需更换可用版本问题

摘要：在使用 PyCharm 控制台执行 pip install 安装第三方包时，很多开发者都会遇到一个令人头疼的报错------pip install 安装报错，提示检测到 yanked 版本，需更换可用版本（yanked version / The given version has been yanked） 。这个问题通常出现在 PyCharm 控制台、终端以及 CI/CD 自动化部署环境中，表面上看是"版本问题"，实际上背后涉及 pip 缓存机制、镜像源同步延迟、依赖解析策略等多个技术细节。本文将从真实的开发场景出发，系统地分析该报错的产生原因，并给出 10+ 种可落地的解决方案，包括国内镜像源配置、yanked 版本处理、PYTHONPATH 设置、相对导入规范等，帮助你彻底解决 pip install 相关的一系列报错。

文章目录

[Python系列Bug修复PyCharm控制台pip install报错：如何解决 pip install 安装报错检测到 yanked 版本需更换可用版本问题](#Python系列Bug修复PyCharm控制台pip install报错：如何解决 pip install 安装报错检测到 yanked 版本需更换可用版本问题)
- 一、问题出现的开发场景与技术背景
- - [1.1 典型报错场景](#1.1 典型报错场景)
  - [1.2 技术细节分析](#1.2 技术细节分析)
  - [1.3 开发环境说明](#1.3 开发环境说明)
- 二、报错原因全景排查流程
- [三、解决方案一：处理 yanked 版本，更换可用版本](#三、解决方案一：处理 yanked 版本，更换可用版本)
- - [3.1 查看包的所有可用版本](#3.1 查看包的所有可用版本)
  - [3.2 指定可用版本安装](#3.2 指定可用版本安装)
  - [3.3 如果必须使用 yanked 版本（不推荐）](#3.3 如果必须使用 yanked 版本（不推荐）)
  - [3.4 更新 requirements.txt](#3.4 更新 requirements.txt)
- 四、解决方案二：网络问题------切换国内镜像源
- - [4.1 国内常用 pip 镜像源](#4.1 国内常用 pip 镜像源)
  - [4.2 临时使用镜像源（单次安装）](#4.2 临时使用镜像源（单次安装）)
  - [4.3 永久配置镜像源](#4.3 永久配置镜像源)
  - [4.4 PyCharm 内配置镜像源](#4.4 PyCharm 内配置镜像源)
- [五、解决方案三：module 包没安装或包名错误](#五、解决方案三：module 包没安装或包名错误)
- - [5.1 区分"包名"和"导入名"](#5.1 区分"包名"和"导入名")
  - [5.2 检查包是否真的安装了](#5.2 检查包是否真的安装了)
- [六、解决方案四：忘了 import](#六、解决方案四：忘了 import)
- [七、解决方案五：缺少 `init.py` 文件](#七、解决方案五：缺少 __init__.py 文件)
- - [7.1 问题场景](#7.1 问题场景)
  - [7.2 解决方案](#7.2 解决方案)
- [八、解决方案六：package 版本不兼容](#八、解决方案六：package 版本不兼容)
- - [8.1 典型报错](#8.1 典型报错)
  - [8.2 解决方案](#8.2 解决方案)
- 九、解决方案七：自定义包名与第三方包重名
- - [9.1 问题场景](#9.1 问题场景)
  - [9.2 排查方法](#9.2 排查方法)
  - [9.3 解决方案](#9.3 解决方案)
- [十、解决方案八：PYTHONPATH 未设置或自建包路径不在 PYTHONPATH 下](#十、解决方案八：PYTHONPATH 未设置或自建包路径不在 PYTHONPATH 下)
- - [10.1 问题场景](#10.1 问题场景)
  - [10.2 解决方案](#10.2 解决方案)
- 十一、解决方案九：不恰当的使用相对导入
- - [11.1 问题场景](#11.1 问题场景)
  - [11.2 解决方案](#11.2 解决方案)
- [十二、解决方案十：pip 版本不是最新版](#十二、解决方案十：pip 版本不是最新版)
- 十三、扩展解决方案：更多可能性排查
- - [13.1 pip 缓存损坏](#13.1 pip 缓存损坏)
  - [13.2 Python 版本不支持](#13.2 Python 版本不支持)
  - [13.3 操作系统架构问题（Apple Silicon 常见）](#13.3 操作系统架构问题（Apple Silicon 常见）)
  - [13.4 代理 / 公司防火墙](#13.4 代理 / 公司防火墙)
  - [13.5 权限不足（macOS/Linux）](#13.5 权限不足（macOS/Linux）)
- 十四、问题解决方案总结

一、问题出现的开发场景与技术背景

1.1 典型报错场景

在日常 Python 开发中，我们经常会执行类似如下的安装命令：

bash 复制代码

pip install some-package==1.2.3

然后 PyCharm 控制台抛出如下报错：

复制代码

ERROR: Could not find a version that satisfies the requirement some-package==1.2.3
ERROR: No matching distribution found for some-package==1.2.3

# 或者更明确的 yanked 提示：
WARNING: The candidate selected for download or install is a yanked version: ...

所谓 yanked 版本（被撤回版本） ，是指包的维护者在 PyPI 上将某个已发布的版本标记为"撤回"，通常是因为该版本存在严重的 bug、安全问题或发布错误。pip 默认会跳过 yanked 版本 ，但如果你在 requirements.txt 或命令行中显式指定了某个 yanked 版本号，pip 就会报出"检测到 yanked 版本需更换可用版本"的错误。

1.2 技术细节分析

yanked 机制的核心逻辑如下：

技术点	说明
yanked 标记	维护者在 PyPI 上撤回版本时打上的标记，存在于包的 metadata 中
pip 行为	依赖解析时默认排除 yanked 版本，除非显式指定该版本
镜像源影响	国内镜像源同步 PyPI 存在延迟，可能出现镜像源缓存了 yanked 标记或未同步最新版本
版本锁定	`requirements.txt` 中硬编码版本号，是触发该报错的常见原因

PyPI官方源国内镜像源 pip工具 PyCharm控制台开发者 PyPI官方源国内镜像源 pip工具 PyCharm控制台开发者 #mermaid-svg-x1xz0gMMf07fcvto{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-x1xz0gMMf07fcvto .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-x1xz0gMMf07fcvto .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-x1xz0gMMf07fcvto .error-icon{fill:#552222;}#mermaid-svg-x1xz0gMMf07fcvto .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-x1xz0gMMf07fcvto .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-x1xz0gMMf07fcvto .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-x1xz0gMMf07fcvto .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-x1xz0gMMf07fcvto .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-x1xz0gMMf07fcvto .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-x1xz0gMMf07fcvto .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-x1xz0gMMf07fcvto .marker{fill:#333333;stroke:#333333;}#mermaid-svg-x1xz0gMMf07fcvto .marker.cross{stroke:#333333;}#mermaid-svg-x1xz0gMMf07fcvto svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-x1xz0gMMf07fcvto p{margin:0;}#mermaid-svg-x1xz0gMMf07fcvto .actor{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:#ECECFF;}#mermaid-svg-x1xz0gMMf07fcvto text.actor>tspan{fill:black;stroke:none;}#mermaid-svg-x1xz0gMMf07fcvto .actor-line{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);}#mermaid-svg-x1xz0gMMf07fcvto .innerArc{stroke-width:1.5;stroke-dasharray:none;}#mermaid-svg-x1xz0gMMf07fcvto .messageLine0{stroke-width:1.5;stroke-dasharray:none;stroke:#333;}#mermaid-svg-x1xz0gMMf07fcvto .messageLine1{stroke-width:1.5;stroke-dasharray:2,2;stroke:#333;}#mermaid-svg-x1xz0gMMf07fcvto #arrowhead path{fill:#333;stroke:#333;}#mermaid-svg-x1xz0gMMf07fcvto .sequenceNumber{fill:white;}#mermaid-svg-x1xz0gMMf07fcvto #sequencenumber{fill:#333;}#mermaid-svg-x1xz0gMMf07fcvto #crosshead path{fill:#333;stroke:#333;}#mermaid-svg-x1xz0gMMf07fcvto .messageText{fill:#333;stroke:none;}#mermaid-svg-x1xz0gMMf07fcvto .labelBox{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:#ECECFF;}#mermaid-svg-x1xz0gMMf07fcvto .labelText,#mermaid-svg-x1xz0gMMf07fcvto .labelText>tspan{fill:black;stroke:none;}#mermaid-svg-x1xz0gMMf07fcvto .loopText,#mermaid-svg-x1xz0gMMf07fcvto .loopText>tspan{fill:black;stroke:none;}#mermaid-svg-x1xz0gMMf07fcvto .loopLine{stroke-width:2px;stroke-dasharray:2,2;stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);}#mermaid-svg-x1xz0gMMf07fcvto .note{stroke:#aaaa33;fill:#fff5ad;}#mermaid-svg-x1xz0gMMf07fcvto .noteText,#mermaid-svg-x1xz0gMMf07fcvto .noteText>tspan{fill:black;stroke:none;}#mermaid-svg-x1xz0gMMf07fcvto .activation0{fill:#f4f4f4;stroke:#666;}#mermaid-svg-x1xz0gMMf07fcvto .activation1{fill:#f4f4f4;stroke:#666;}#mermaid-svg-x1xz0gMMf07fcvto .activation2{fill:#f4f4f4;stroke:#666;}#mermaid-svg-x1xz0gMMf07fcvto .actorPopupMenu{position:absolute;}#mermaid-svg-x1xz0gMMf07fcvto .actorPopupMenuPanel{position:absolute;fill:#ECECFF;box-shadow:0px 8px 16px 0px rgba(0,0,0,0.2);filter:drop-shadow(3px 5px 2px rgb(0 0 0 / 0.4));}#mermaid-svg-x1xz0gMMf07fcvto .actor-man line{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:#ECECFF;}#mermaid-svg-x1xz0gMMf07fcvto .actor-man circle,#mermaid-svg-x1xz0gMMf07fcvto line{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:#ECECFF;stroke-width:2px;}#mermaid-svg-x1xz0gMMf07fcvto :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;} alt $1.2.3 被 yanked$ $镜像源无该版本$ $版本可用$ pip install pkg==1.2.3 转发安装命令查询 pkg 可用版本返回版本列表(可能滞后) 检测到 yanked 版本 ERROR 需更换可用版本无匹配发行版下载并安装返回 whl/tar.gz Successfully installed

1.3 开发环境说明

本文所有操作基于以下开发环境，其他版本思路一致：

操作系统：macOS (Apple Silicon)

Python 版本：Python 3.12.x

IDE：PyCharm 2025.x Professional

pip 版本：pip 24.x+

二、报错原因全景排查流程

在遇到 pip install 报错时，不要盲目重试，按照下面的排查流程图定位问题：
#mermaid-svg-STYWlBJEsGklBaLI{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-STYWlBJEsGklBaLI .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-STYWlBJEsGklBaLI .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-STYWlBJEsGklBaLI .error-icon{fill:#552222;}#mermaid-svg-STYWlBJEsGklBaLI .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-STYWlBJEsGklBaLI .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-STYWlBJEsGklBaLI .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-STYWlBJEsGklBaLI .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-STYWlBJEsGklBaLI .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-STYWlBJEsGklBaLI .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-STYWlBJEsGklBaLI .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-STYWlBJEsGklBaLI .marker{fill:#333333;stroke:#333333;}#mermaid-svg-STYWlBJEsGklBaLI .marker.cross{stroke:#333333;}#mermaid-svg-STYWlBJEsGklBaLI svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-STYWlBJEsGklBaLI p{margin:0;}#mermaid-svg-STYWlBJEsGklBaLI .label{font-family:"trebuchet ms",verdana,arial,sans-serif;color:#333;}#mermaid-svg-STYWlBJEsGklBaLI .cluster-label text{fill:#333;}#mermaid-svg-STYWlBJEsGklBaLI .cluster-label span{color:#333;}#mermaid-svg-STYWlBJEsGklBaLI .cluster-label span p{background-color:transparent;}#mermaid-svg-STYWlBJEsGklBaLI .label text,#mermaid-svg-STYWlBJEsGklBaLI span{fill:#333;color:#333;}#mermaid-svg-STYWlBJEsGklBaLI .node rect,#mermaid-svg-STYWlBJEsGklBaLI .node circle,#mermaid-svg-STYWlBJEsGklBaLI .node ellipse,#mermaid-svg-STYWlBJEsGklBaLI .node polygon,#mermaid-svg-STYWlBJEsGklBaLI .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-STYWlBJEsGklBaLI .rough-node .label text,#mermaid-svg-STYWlBJEsGklBaLI .node .label text,#mermaid-svg-STYWlBJEsGklBaLI .image-shape .label,#mermaid-svg-STYWlBJEsGklBaLI .icon-shape .label{text-anchor:middle;}#mermaid-svg-STYWlBJEsGklBaLI .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-STYWlBJEsGklBaLI .rough-node .label,#mermaid-svg-STYWlBJEsGklBaLI .node .label,#mermaid-svg-STYWlBJEsGklBaLI .image-shape .label,#mermaid-svg-STYWlBJEsGklBaLI .icon-shape .label{text-align:center;}#mermaid-svg-STYWlBJEsGklBaLI .node.clickable{cursor:pointer;}#mermaid-svg-STYWlBJEsGklBaLI .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-STYWlBJEsGklBaLI .arrowheadPath{fill:#333333;}#mermaid-svg-STYWlBJEsGklBaLI .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-STYWlBJEsGklBaLI .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-STYWlBJEsGklBaLI .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-STYWlBJEsGklBaLI .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-STYWlBJEsGklBaLI .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-STYWlBJEsGklBaLI .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-STYWlBJEsGklBaLI .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-STYWlBJEsGklBaLI .cluster text{fill:#333;}#mermaid-svg-STYWlBJEsGklBaLI .cluster span{color:#333;}#mermaid-svg-STYWlBJEsGklBaLI div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-STYWlBJEsGklBaLI .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-STYWlBJEsGklBaLI rect.text{fill:none;stroke-width:0;}#mermaid-svg-STYWlBJEsGklBaLI .icon-shape,#mermaid-svg-STYWlBJEsGklBaLI .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-STYWlBJEsGklBaLI .icon-shape p,#mermaid-svg-STYWlBJEsGklBaLI .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-STYWlBJEsGklBaLI .icon-shape .label rect,#mermaid-svg-STYWlBJEsGklBaLI .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-STYWlBJEsGklBaLI .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-STYWlBJEsGklBaLI .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-STYWlBJEsGklBaLI :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;} 是
否
是
否
是
否
是
是
否
否
pip install 报错
提示 yanked 版本?
更换可用版本号
提示找不到包?
包名拼写正确?
修正包名: pip search索引核对
切换国内镜像源重试
ModuleNotFoundError?
检查是否忘记import
自建包?
检查__init__.py / PYTHONPATH
检查包版本兼容性
升级pip / 清理缓存

三、解决方案一：处理 yanked 版本，更换可用版本

这是本文标题报错的核心解决方案。

3.1 查看包的所有可用版本

bash 复制代码

# 方法一：通过 pip index versions（pip 21.2+）
pip index versions some-package

# 方法二：通过 yolk3k（需安装）
pip install yolk3k
yolk -V some-package

# 方法三：直接查询 PyPI 页面
# 浏览器访问 https://pypi.org/project/some-package/#history

3.2 指定可用版本安装

bash 复制代码

# 假设最新可用版本是 1.2.4
pip install some-package==1.2.4

# 或者不指定版本，让 pip 自动选择最新可用版本
pip install -U some-package

3.3 如果必须使用 yanked 版本（不推荐）

某些场景下因兼容性要求必须安装某个 yanked 版本，可以显式指定并配合 --no-cache-dir：

bash 复制代码

# 显式指定 yanked 版本（pip 会给出 warning，但不阻断）
pip install some-package==1.2.3 --no-cache-dir

⚠️ 注意：使用 yanked 版本意味着该版本存在已知缺陷，务必确认风险后再使用，并优先联系包维护者确认替代方案。

3.4 更新 requirements.txt

如果是项目依赖文件锁死了旧版本，需要同步更新：

bash 复制代码

# 将 requirements.txt 中的版本号更新为可用版本
# 原：some-package==1.2.3
# 改为：
some-package==1.2.4

四、解决方案二：网络问题------切换国内镜像源

国内访问 PyPI 官方源经常超时或被重置，这是导致安装报错的另一大元凶。

4.1 国内常用 pip 镜像源

镜像源	地址
阿里云	https://mirrors.aliyun.com/pypi/simple/
清华大学	https://pypi.tuna.tsinghua.edu.cn/simple
豆瓣	https://pypi.douban.com/simple/
中科大	https://pypi.mirrors.ustc.edu.cn/simple/
华为云	https://repo.huaweicloud.com/repository/pypi/simple/

4.2 临时使用镜像源（单次安装）

bash 复制代码

pip install some-package -i https://pypi.tuna.tsinghua.edu.cn/simple

4.3 永久配置镜像源

macOS / Linux ------ pip.conf：

bash 复制代码

# 创建或编辑配置文件
mkdir -p ~/.pip
vim ~/.pip/pip.conf

写入以下内容：

ini 复制代码

[global]
index-url = https://pypi.tuna.tsinghua.edu.cn/simple

[install]
trusted-host = pypi.tuna.tsinghua.edu.cn

Windows ------ pip.ini：

在 %APPDATA%\pip\ 目录下创建 pip.ini，内容同上：

ini 复制代码

[global]
index-url = https://pypi.tuna.tsinghua.edu.cn/simple

[install]
trusted-host = pypi.tuna.tsinghua.edu.cn

4.4 PyCharm 内配置镜像源

在 PyCharm 中：Settings/Preferences → Project → Python Interpreter → 点击 "+" → Manage Repositories，添加清华或阿里云镜像地址即可。

💡 提示：yanked 报错有时正是因为镜像源版本列表滞后于 PyPI 官方源，切换到官方源 https://pypi.org/simple 可能直接解决问题。

五、解决方案三：module 包没安装或包名错误

5.1 区分"包名"和"导入名"

这是 Python 新手最容易踩的坑------pip 安装名和 import 导入名经常不一致：

pip 安装命令	正确导入方式
`pip install opencv-python`	`import cv2`
`pip install pillow`	`from PIL import Image`
`pip install scikit-learn`	`import sklearn`
`pip install beautifulsoup4`	`from bs4 import BeautifulSoup`

5.2 检查包是否真的安装了

bash 复制代码

# 查看当前环境已安装的包
pip list | grep some-package

# 查看 PyCharm 使用的解释器是否正确
# Settings → Project → Python Interpreter

⚠️ 高频坑 ：PyCharm 项目解释器和终端 python 可能不是同一个环境！在 PyCharm 控制台报错时，先确认当前使用的解释器路径是否正确。

六、解决方案四：忘了 import

看似低级，但在大型项目中极其常见------尤其是模块名与文件名相近时。

python 复制代码

# ❌ 错误：没有导入就使用
result = requests.get("https://api.example.com")

# ✅ 正确：文件顶部导入
import requests
result = requests.get("https://api.example.com")

快速自查 ：看到 NameError: name 'xxx' is not defined，首先检查文件顶部是否缺少 import 语句。

七、解决方案五：缺少 `init.py` 文件

7.1 问题场景

在 Python 3.3 之前，一个目录要被识别为 package，必须包含 __init__.py 文件。虽然 Python 3.3+ 引入了命名空间包（Namespace Package），但很多工具链（包括部分打包工具和老代码）仍依赖传统包结构。

复制代码

project/
├── main.py
└── utils/          # ❌ 没有 __init__.py
    └── helper.py

7.2 解决方案

bash 复制代码

# 在包目录下创建 __init__.py
touch utils/__init__.py

复制代码

project/
├── main.py
└── utils/
    ├── __init__.py   # ✅ 空的即可，也可以写 __all__ 控制导出
    └── helper.py

python 复制代码

# utils/__init__.py
from .helper import some_function

__all__ = ["some_function"]

八、解决方案六：package 版本不兼容

8.1 典型报错

复制代码

ERROR: pip's dependency resolver does not currently take into account all the packages that are installed...
# 或者
pkg requires numpy>=1.24, but you have numpy 1.21.0

8.2 解决方案

bash 复制代码

# 查看包依赖要求
pip show some-package

# 升级到兼容版本
pip install -U some-package

# 使用虚拟环境隔离依赖（最佳实践）
python -m venv venv
source venv/bin/activate  # macOS/Linux
# venv\Scripts\activate   # Windows

九、解决方案七：自定义包名与第三方包重名

9.1 问题场景

你项目里有一个 requests.py 或 utils.py，pip 安装的第三方包也叫 requests，导致 import 时导入了你自己的文件。

python 复制代码

# ❌ 你的项目结构
project/
├── requests.py    # 与第三方库 requests 重名！
└── main.py

python 复制代码

# main.py 中
import requests
# 实际导入的是你自己的 requests.py，而非第三方库
# 报错：AttributeError: module 'requests' has no attribute 'get'

9.2 排查方法

python 复制代码

import requests
print(requests.__file__)  # 查看导入的实际路径

9.3 解决方案

重命名自己的文件，加前缀如 my_requests.py 或放入子包 core/requests.py
避免使用常见第三方库名作为模块名，如 requests、numpy、json、os、time 等

十、解决方案八：PYTHONPATH 未设置或自建包路径不在 PYTHONPATH 下

10.1 问题场景

自建 module 包所在路径不在 Python 的搜索路径中，导致 ModuleNotFoundError: No module named 'xxx'。

bash 复制代码

# 查看 Python 搜索路径
python -c "import sys; print(sys.path)"

10.2 解决方案

方法一：临时添加（推荐脚本调试）

bash 复制代码

export PYTHONPATH="${PYTHONPATH}:/path/to/your/project"

方法二：代码中动态添加

python 复制代码

import sys
sys.path.insert(0, "/path/to/your/project")

方法三：PyCharm 中设置 Sources Root

选中项目根目录 → 右键 → Mark Directory as → Sources Root，PyCharm 会自动将其加入 PYTHONPATH。

方法四：正确安装本地包（最佳实践）

bash 复制代码

# 在项目根目录创建 setup.py 或 pyproject.toml 后执行
pip install -e .

十一、解决方案九：不恰当的使用相对导入

11.1 问题场景

python 复制代码

# ❌ 错误：把模块当脚本直接运行时使用相对导入
# utils/helper.py
from . import config   # ValueError: attempted relative import beyond top-level package

bash 复制代码

python utils/helper.py   # ❌ 触发相对导入错误

11.2 解决方案

始终从项目根目录以模块方式运行：

bash 复制代码

python -m utils.helper   # ✅ 正确方式

#mermaid-svg-Y6d1ke2E5P4UZD7x{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-Y6d1ke2E5P4UZD7x .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-Y6d1ke2E5P4UZD7x .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-Y6d1ke2E5P4UZD7x .error-icon{fill:#552222;}#mermaid-svg-Y6d1ke2E5P4UZD7x .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-Y6d1ke2E5P4UZD7x .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-Y6d1ke2E5P4UZD7x .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-Y6d1ke2E5P4UZD7x .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-Y6d1ke2E5P4UZD7x .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-Y6d1ke2E5P4UZD7x .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-Y6d1ke2E5P4UZD7x .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-Y6d1ke2E5P4UZD7x .marker{fill:#333333;stroke:#333333;}#mermaid-svg-Y6d1ke2E5P4UZD7x .marker.cross{stroke:#333333;}#mermaid-svg-Y6d1ke2E5P4UZD7x svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-Y6d1ke2E5P4UZD7x p{margin:0;}#mermaid-svg-Y6d1ke2E5P4UZD7x defs #statediagram-barbEnd{fill:#333333;stroke:#333333;}#mermaid-svg-Y6d1ke2E5P4UZD7x g.stateGroup text{fill:#9370DB;stroke:none;font-size:10px;}#mermaid-svg-Y6d1ke2E5P4UZD7x g.stateGroup text{fill:#333;stroke:none;font-size:10px;}#mermaid-svg-Y6d1ke2E5P4UZD7x g.stateGroup .state-title{font-weight:bolder;fill:#131300;}#mermaid-svg-Y6d1ke2E5P4UZD7x g.stateGroup rect{fill:#ECECFF;stroke:#9370DB;}#mermaid-svg-Y6d1ke2E5P4UZD7x g.stateGroup line{stroke:#333333;stroke-width:1;}#mermaid-svg-Y6d1ke2E5P4UZD7x .transition{stroke:#333333;stroke-width:1;fill:none;}#mermaid-svg-Y6d1ke2E5P4UZD7x .stateGroup .composit{fill:white;border-bottom:1px;}#mermaid-svg-Y6d1ke2E5P4UZD7x .stateGroup .alt-composit{fill:#e0e0e0;border-bottom:1px;}#mermaid-svg-Y6d1ke2E5P4UZD7x .state-note{stroke:#aaaa33;fill:#fff5ad;}#mermaid-svg-Y6d1ke2E5P4UZD7x .state-note text{fill:black;stroke:none;font-size:10px;}#mermaid-svg-Y6d1ke2E5P4UZD7x .stateLabel .box{stroke:none;stroke-width:0;fill:#ECECFF;opacity:0.5;}#mermaid-svg-Y6d1ke2E5P4UZD7x .edgeLabel .label rect{fill:#ECECFF;opacity:0.5;}#mermaid-svg-Y6d1ke2E5P4UZD7x .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-Y6d1ke2E5P4UZD7x .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-Y6d1ke2E5P4UZD7x .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-Y6d1ke2E5P4UZD7x .edgeLabel .label text{fill:#333;}#mermaid-svg-Y6d1ke2E5P4UZD7x .label div .edgeLabel{color:#333;}#mermaid-svg-Y6d1ke2E5P4UZD7x .stateLabel text{fill:#131300;font-size:10px;font-weight:bold;}#mermaid-svg-Y6d1ke2E5P4UZD7x .node circle.state-start{fill:#333333;stroke:#333333;}#mermaid-svg-Y6d1ke2E5P4UZD7x .node .fork-join{fill:#333333;stroke:#333333;}#mermaid-svg-Y6d1ke2E5P4UZD7x .node circle.state-end{fill:#9370DB;stroke:white;stroke-width:1.5;}#mermaid-svg-Y6d1ke2E5P4UZD7x .end-state-inner{fill:white;stroke-width:1.5;}#mermaid-svg-Y6d1ke2E5P4UZD7x .node rect{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-Y6d1ke2E5P4UZD7x .node polygon{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-Y6d1ke2E5P4UZD7x #statediagram-barbEnd{fill:#333333;}#mermaid-svg-Y6d1ke2E5P4UZD7x .statediagram-cluster rect{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-Y6d1ke2E5P4UZD7x .cluster-label,#mermaid-svg-Y6d1ke2E5P4UZD7x .nodeLabel{color:#131300;}#mermaid-svg-Y6d1ke2E5P4UZD7x .statediagram-cluster rect.outer{rx:5px;ry:5px;}#mermaid-svg-Y6d1ke2E5P4UZD7x .statediagram-state .divider{stroke:#9370DB;}#mermaid-svg-Y6d1ke2E5P4UZD7x .statediagram-state .title-state{rx:5px;ry:5px;}#mermaid-svg-Y6d1ke2E5P4UZD7x .statediagram-cluster.statediagram-cluster .inner{fill:white;}#mermaid-svg-Y6d1ke2E5P4UZD7x .statediagram-cluster.statediagram-cluster-alt .inner{fill:#f0f0f0;}#mermaid-svg-Y6d1ke2E5P4UZD7x .statediagram-cluster .inner{rx:0;ry:0;}#mermaid-svg-Y6d1ke2E5P4UZD7x .statediagram-state rect.basic{rx:5px;ry:5px;}#mermaid-svg-Y6d1ke2E5P4UZD7x .statediagram-state rect.divider{stroke-dasharray:10,10;fill:#f0f0f0;}#mermaid-svg-Y6d1ke2E5P4UZD7x .note-edge{stroke-dasharray:5;}#mermaid-svg-Y6d1ke2E5P4UZD7x .statediagram-note rect{fill:#fff5ad;stroke:#aaaa33;stroke-width:1px;rx:0;ry:0;}#mermaid-svg-Y6d1ke2E5P4UZD7x .statediagram-note rect{fill:#fff5ad;stroke:#aaaa33;stroke-width:1px;rx:0;ry:0;}#mermaid-svg-Y6d1ke2E5P4UZD7x .statediagram-note text{fill:black;}#mermaid-svg-Y6d1ke2E5P4UZD7x .statediagram-note .nodeLabel{color:black;}#mermaid-svg-Y6d1ke2E5P4UZD7x .statediagram .edgeLabel{color:red;}#mermaid-svg-Y6d1ke2E5P4UZD7x #dependencyStart,#mermaid-svg-Y6d1ke2E5P4UZD7x #dependencyEnd{fill:#333333;stroke:#333333;stroke-width:1;}#mermaid-svg-Y6d1ke2E5P4UZD7x .statediagramTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-Y6d1ke2E5P4UZD7x :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;} python helper.py
from . import xxx 失败
python -m utils.helper
package 有值
直接运行脚本
相对导入报错
模块方式运行
导入成功
改用模块方式运行

💡 经验法则 ：包内模块间导入用相对导入 from . import xxx，入口脚本用绝对导入，运行时用 python -m，可以规避绝大多数导入问题。

十二、解决方案十：pip 版本不是最新版

旧版本 pip 的依赖解析器（2020 年前的 legacy resolver）存在大量 bug，升级 pip 能解决很多莫名其妙的安装报错。

bash 复制代码

# 升级 pip
python -m pip install --upgrade pip

# 如官方源慢，用国内源升级
python -m pip install -U pip -i https://pypi.tuna.tsinghua.edu.cn/simple

同时建议升级 setuptools 和 wheel：

bash 复制代码

python -m pip install -U pip setuptools wheel

十三、扩展解决方案：更多可能性排查

除了以上十大方向，以下情况也会导致 pip install 相关报错：

13.1 pip 缓存损坏

bash 复制代码

# 清理缓存后重试
pip cache purge
pip install some-package --no-cache-dir

13.2 Python 版本不支持

某些包只支持特定 Python 版本，检查包的 Requires: Python 元数据：

bash 复制代码

pip index versions some-package  # 查看 requires_python 信息
python --version                 # 确认当前 Python 版本

13.3 操作系统架构问题（Apple Silicon 常见）

bash 复制代码

# macOS M系列芯片部分包需通过 conda 或源码编译安装
# 例如某些包没有 arm64 的 wheel
arch -x86_64 python -m pip install some-package

13.4 代理 / 公司防火墙

bash 复制代码

# 配置代理
pip install some-package --proxy http://proxy.company.com:8080

13.5 权限不足（macOS/Linux）

bash 复制代码

# ❌ 不要用 sudo pip install（污染系统环境）
# ✅ 使用虚拟环境，或使用 --user
pip install --user some-package

十四、问题解决方案总结

报错现象	根因	解决方案	优先级
检测到 yanked 版本	显式指定了被撤回的版本号	`pip index versions` 查看后更换可用版本	⭐⭐⭐⭐⭐
找不到匹配的发行版	网络问题 / 镜像源滞后	切换国内镜像源或官方源	⭐⭐⭐⭐⭐
ModuleNotFoundError	包未安装 / 包名错误	核对安装名与导入名，重新安装	⭐⭐⭐⭐
NameError	忘了 import	文件顶部补充导入语句	⭐⭐⭐
ModuleNotFoundError (自建包)	缺少 `__init__.py`	包目录下补建 `__init__.py`	⭐⭐⭐⭐
依赖冲突报错	包版本不兼容	升级包 / 使用虚拟环境隔离	⭐⭐⭐⭐
导入的是错误模块	自定义包名与第三方包重名	重命名本地文件，打印 `__file__` 排查	⭐⭐⭐
No module named 'xxx' (自建)	PYTHONPATH 未包含包路径	设置 PYTHONPATH / Mark Sources Root / `pip install -e .`	⭐⭐⭐⭐
ValueError: attempted relative import	相对导入方式不当	改用 `python -m` 模块方式运行	⭐⭐⭐
各种莫名其妙的安装失败	pip 版本过旧	`python -m pip install -U pip setuptools wheel`	⭐⭐⭐⭐

#mermaid-svg-AYUUPRe92CBicUjI{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-AYUUPRe92CBicUjI .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-AYUUPRe92CBicUjI .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-AYUUPRe92CBicUjI .error-icon{fill:#552222;}#mermaid-svg-AYUUPRe92CBicUjI .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-AYUUPRe92CBicUjI .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-AYUUPRe92CBicUjI .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-AYUUPRe92CBicUjI .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-AYUUPRe92CBicUjI .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-AYUUPRe92CBicUjI .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-AYUUPRe92CBicUjI .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-AYUUPRe92CBicUjI .marker{fill:#333333;stroke:#333333;}#mermaid-svg-AYUUPRe92CBicUjI .marker.cross{stroke:#333333;}#mermaid-svg-AYUUPRe92CBicUjI svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-AYUUPRe92CBicUjI p{margin:0;}#mermaid-svg-AYUUPRe92CBicUjI .edge{stroke-width:3;}#mermaid-svg-AYUUPRe92CBicUjI .section--1 rect,#mermaid-svg-AYUUPRe92CBicUjI .section--1 path,#mermaid-svg-AYUUPRe92CBicUjI .section--1 circle,#mermaid-svg-AYUUPRe92CBicUjI .section--1 path{fill:hsl(240, 100%, 76.2745098039%);}#mermaid-svg-AYUUPRe92CBicUjI .section--1 text{fill:#ffffff;}#mermaid-svg-AYUUPRe92CBicUjI .node-icon--1{font-size:40px;color:#ffffff;}#mermaid-svg-AYUUPRe92CBicUjI .section-edge--1{stroke:hsl(240, 100%, 76.2745098039%);}#mermaid-svg-AYUUPRe92CBicUjI .edge-depth--1{stroke-width:17;}#mermaid-svg-AYUUPRe92CBicUjI .section--1 line{stroke:hsl(60, 100%, 86.2745098039%);stroke-width:3;}#mermaid-svg-AYUUPRe92CBicUjI .lineWrapper line{stroke:#ffffff;}#mermaid-svg-AYUUPRe92CBicUjI .disabled,#mermaid-svg-AYUUPRe92CBicUjI .disabled circle,#mermaid-svg-AYUUPRe92CBicUjI .disabled text{fill:lightgray;}#mermaid-svg-AYUUPRe92CBicUjI .disabled text{fill:#efefef;}#mermaid-svg-AYUUPRe92CBicUjI .section-0 rect,#mermaid-svg-AYUUPRe92CBicUjI .section-0 path,#mermaid-svg-AYUUPRe92CBicUjI .section-0 circle,#mermaid-svg-AYUUPRe92CBicUjI .section-0 path{fill:hsl(60, 100%, 73.5294117647%);}#mermaid-svg-AYUUPRe92CBicUjI .section-0 text{fill:black;}#mermaid-svg-AYUUPRe92CBicUjI .node-icon-0{font-size:40px;color:black;}#mermaid-svg-AYUUPRe92CBicUjI .section-edge-0{stroke:hsl(60, 100%, 73.5294117647%);}#mermaid-svg-AYUUPRe92CBicUjI .edge-depth-0{stroke-width:14;}#mermaid-svg-AYUUPRe92CBicUjI .section-0 line{stroke:hsl(240, 100%, 83.5294117647%);stroke-width:3;}#mermaid-svg-AYUUPRe92CBicUjI .lineWrapper line{stroke:black;}#mermaid-svg-AYUUPRe92CBicUjI .disabled,#mermaid-svg-AYUUPRe92CBicUjI .disabled circle,#mermaid-svg-AYUUPRe92CBicUjI .disabled text{fill:lightgray;}#mermaid-svg-AYUUPRe92CBicUjI .disabled text{fill:#efefef;}#mermaid-svg-AYUUPRe92CBicUjI .section-1 rect,#mermaid-svg-AYUUPRe92CBicUjI .section-1 path,#mermaid-svg-AYUUPRe92CBicUjI .section-1 circle,#mermaid-svg-AYUUPRe92CBicUjI .section-1 path{fill:hsl(80, 100%, 76.2745098039%);}#mermaid-svg-AYUUPRe92CBicUjI .section-1 text{fill:black;}#mermaid-svg-AYUUPRe92CBicUjI .node-icon-1{font-size:40px;color:black;}#mermaid-svg-AYUUPRe92CBicUjI .section-edge-1{stroke:hsl(80, 100%, 76.2745098039%);}#mermaid-svg-AYUUPRe92CBicUjI .edge-depth-1{stroke-width:11;}#mermaid-svg-AYUUPRe92CBicUjI .section-1 line{stroke:hsl(260, 100%, 86.2745098039%);stroke-width:3;}#mermaid-svg-AYUUPRe92CBicUjI .lineWrapper line{stroke:black;}#mermaid-svg-AYUUPRe92CBicUjI .disabled,#mermaid-svg-AYUUPRe92CBicUjI .disabled circle,#mermaid-svg-AYUUPRe92CBicUjI .disabled text{fill:lightgray;}#mermaid-svg-AYUUPRe92CBicUjI .disabled text{fill:#efefef;}#mermaid-svg-AYUUPRe92CBicUjI .section-2 rect,#mermaid-svg-AYUUPRe92CBicUjI .section-2 path,#mermaid-svg-AYUUPRe92CBicUjI .section-2 circle,#mermaid-svg-AYUUPRe92CBicUjI .section-2 path{fill:hsl(270, 100%, 76.2745098039%);}#mermaid-svg-AYUUPRe92CBicUjI .section-2 text{fill:#ffffff;}#mermaid-svg-AYUUPRe92CBicUjI .node-icon-2{font-size:40px;color:#ffffff;}#mermaid-svg-AYUUPRe92CBicUjI .section-edge-2{stroke:hsl(270, 100%, 76.2745098039%);}#mermaid-svg-AYUUPRe92CBicUjI .edge-depth-2{stroke-width:8;}#mermaid-svg-AYUUPRe92CBicUjI .section-2 line{stroke:hsl(90, 100%, 86.2745098039%);stroke-width:3;}#mermaid-svg-AYUUPRe92CBicUjI .lineWrapper line{stroke:#ffffff;}#mermaid-svg-AYUUPRe92CBicUjI .disabled,#mermaid-svg-AYUUPRe92CBicUjI .disabled circle,#mermaid-svg-AYUUPRe92CBicUjI .disabled text{fill:lightgray;}#mermaid-svg-AYUUPRe92CBicUjI .disabled text{fill:#efefef;}#mermaid-svg-AYUUPRe92CBicUjI .section-3 rect,#mermaid-svg-AYUUPRe92CBicUjI .section-3 path,#mermaid-svg-AYUUPRe92CBicUjI .section-3 circle,#mermaid-svg-AYUUPRe92CBicUjI .section-3 path{fill:hsl(300, 100%, 76.2745098039%);}#mermaid-svg-AYUUPRe92CBicUjI .section-3 text{fill:black;}#mermaid-svg-AYUUPRe92CBicUjI .node-icon-3{font-size:40px;color:black;}#mermaid-svg-AYUUPRe92CBicUjI .section-edge-3{stroke:hsl(300, 100%, 76.2745098039%);}#mermaid-svg-AYUUPRe92CBicUjI .edge-depth-3{stroke-width:5;}#mermaid-svg-AYUUPRe92CBicUjI .section-3 line{stroke:hsl(120, 100%, 86.2745098039%);stroke-width:3;}#mermaid-svg-AYUUPRe92CBicUjI .lineWrapper line{stroke:black;}#mermaid-svg-AYUUPRe92CBicUjI .disabled,#mermaid-svg-AYUUPRe92CBicUjI .disabled circle,#mermaid-svg-AYUUPRe92CBicUjI .disabled text{fill:lightgray;}#mermaid-svg-AYUUPRe92CBicUjI .disabled text{fill:#efefef;}#mermaid-svg-AYUUPRe92CBicUjI .section-4 rect,#mermaid-svg-AYUUPRe92CBicUjI .section-4 path,#mermaid-svg-AYUUPRe92CBicUjI .section-4 circle,#mermaid-svg-AYUUPRe92CBicUjI .section-4 path{fill:hsl(330, 100%, 76.2745098039%);}#mermaid-svg-AYUUPRe92CBicUjI .section-4 text{fill:black;}#mermaid-svg-AYUUPRe92CBicUjI .node-icon-4{font-size:40px;color:black;}#mermaid-svg-AYUUPRe92CBicUjI .section-edge-4{stroke:hsl(330, 100%, 76.2745098039%);}#mermaid-svg-AYUUPRe92CBicUjI .edge-depth-4{stroke-width:2;}#mermaid-svg-AYUUPRe92CBicUjI .section-4 line{stroke:hsl(150, 100%, 86.2745098039%);stroke-width:3;}#mermaid-svg-AYUUPRe92CBicUjI .lineWrapper line{stroke:black;}#mermaid-svg-AYUUPRe92CBicUjI .disabled,#mermaid-svg-AYUUPRe92CBicUjI .disabled circle,#mermaid-svg-AYUUPRe92CBicUjI .disabled text{fill:lightgray;}#mermaid-svg-AYUUPRe92CBicUjI .disabled text{fill:#efefef;}#mermaid-svg-AYUUPRe92CBicUjI .section-5 rect,#mermaid-svg-AYUUPRe92CBicUjI .section-5 path,#mermaid-svg-AYUUPRe92CBicUjI .section-5 circle,#mermaid-svg-AYUUPRe92CBicUjI .section-5 path{fill:hsl(0, 100%, 76.2745098039%);}#mermaid-svg-AYUUPRe92CBicUjI .section-5 text{fill:black;}#mermaid-svg-AYUUPRe92CBicUjI .node-icon-5{font-size:40px;color:black;}#mermaid-svg-AYUUPRe92CBicUjI .section-edge-5{stroke:hsl(0, 100%, 76.2745098039%);}#mermaid-svg-AYUUPRe92CBicUjI .edge-depth-5{stroke-width:-1;}#mermaid-svg-AYUUPRe92CBicUjI .section-5 line{stroke:hsl(180, 100%, 86.2745098039%);stroke-width:3;}#mermaid-svg-AYUUPRe92CBicUjI .lineWrapper line{stroke:black;}#mermaid-svg-AYUUPRe92CBicUjI .disabled,#mermaid-svg-AYUUPRe92CBicUjI .disabled circle,#mermaid-svg-AYUUPRe92CBicUjI .disabled text{fill:lightgray;}#mermaid-svg-AYUUPRe92CBicUjI .disabled text{fill:#efefef;}#mermaid-svg-AYUUPRe92CBicUjI .section-6 rect,#mermaid-svg-AYUUPRe92CBicUjI .section-6 path,#mermaid-svg-AYUUPRe92CBicUjI .section-6 circle,#mermaid-svg-AYUUPRe92CBicUjI .section-6 path{fill:hsl(30, 100%, 76.2745098039%);}#mermaid-svg-AYUUPRe92CBicUjI .section-6 text{fill:black;}#mermaid-svg-AYUUPRe92CBicUjI .node-icon-6{font-size:40px;color:black;}#mermaid-svg-AYUUPRe92CBicUjI .section-edge-6{stroke:hsl(30, 100%, 76.2745098039%);}#mermaid-svg-AYUUPRe92CBicUjI .edge-depth-6{stroke-width:-4;}#mermaid-svg-AYUUPRe92CBicUjI .section-6 line{stroke:hsl(210, 100%, 86.2745098039%);stroke-width:3;}#mermaid-svg-AYUUPRe92CBicUjI .lineWrapper line{stroke:black;}#mermaid-svg-AYUUPRe92CBicUjI .disabled,#mermaid-svg-AYUUPRe92CBicUjI .disabled circle,#mermaid-svg-AYUUPRe92CBicUjI .disabled text{fill:lightgray;}#mermaid-svg-AYUUPRe92CBicUjI .disabled text{fill:#efefef;}#mermaid-svg-AYUUPRe92CBicUjI .section-7 rect,#mermaid-svg-AYUUPRe92CBicUjI .section-7 path,#mermaid-svg-AYUUPRe92CBicUjI .section-7 circle,#mermaid-svg-AYUUPRe92CBicUjI .section-7 path{fill:hsl(90, 100%, 76.2745098039%);}#mermaid-svg-AYUUPRe92CBicUjI .section-7 text{fill:black;}#mermaid-svg-AYUUPRe92CBicUjI .node-icon-7{font-size:40px;color:black;}#mermaid-svg-AYUUPRe92CBicUjI .section-edge-7{stroke:hsl(90, 100%, 76.2745098039%);}#mermaid-svg-AYUUPRe92CBicUjI .edge-depth-7{stroke-width:-7;}#mermaid-svg-AYUUPRe92CBicUjI .section-7 line{stroke:hsl(270, 100%, 86.2745098039%);stroke-width:3;}#mermaid-svg-AYUUPRe92CBicUjI .lineWrapper line{stroke:black;}#mermaid-svg-AYUUPRe92CBicUjI .disabled,#mermaid-svg-AYUUPRe92CBicUjI .disabled circle,#mermaid-svg-AYUUPRe92CBicUjI .disabled text{fill:lightgray;}#mermaid-svg-AYUUPRe92CBicUjI .disabled text{fill:#efefef;}#mermaid-svg-AYUUPRe92CBicUjI .section-8 rect,#mermaid-svg-AYUUPRe92CBicUjI .section-8 path,#mermaid-svg-AYUUPRe92CBicUjI .section-8 circle,#mermaid-svg-AYUUPRe92CBicUjI .section-8 path{fill:hsl(150, 100%, 76.2745098039%);}#mermaid-svg-AYUUPRe92CBicUjI .section-8 text{fill:black;}#mermaid-svg-AYUUPRe92CBicUjI .node-icon-8{font-size:40px;color:black;}#mermaid-svg-AYUUPRe92CBicUjI .section-edge-8{stroke:hsl(150, 100%, 76.2745098039%);}#mermaid-svg-AYUUPRe92CBicUjI .edge-depth-8{stroke-width:-10;}#mermaid-svg-AYUUPRe92CBicUjI .section-8 line{stroke:hsl(330, 100%, 86.2745098039%);stroke-width:3;}#mermaid-svg-AYUUPRe92CBicUjI .lineWrapper line{stroke:black;}#mermaid-svg-AYUUPRe92CBicUjI .disabled,#mermaid-svg-AYUUPRe92CBicUjI .disabled circle,#mermaid-svg-AYUUPRe92CBicUjI .disabled text{fill:lightgray;}#mermaid-svg-AYUUPRe92CBicUjI .disabled text{fill:#efefef;}#mermaid-svg-AYUUPRe92CBicUjI .section-9 rect,#mermaid-svg-AYUUPRe92CBicUjI .section-9 path,#mermaid-svg-AYUUPRe92CBicUjI .section-9 circle,#mermaid-svg-AYUUPRe92CBicUjI .section-9 path{fill:hsl(180, 100%, 76.2745098039%);}#mermaid-svg-AYUUPRe92CBicUjI .section-9 text{fill:black;}#mermaid-svg-AYUUPRe92CBicUjI .node-icon-9{font-size:40px;color:black;}#mermaid-svg-AYUUPRe92CBicUjI .section-edge-9{stroke:hsl(180, 100%, 76.2745098039%);}#mermaid-svg-AYUUPRe92CBicUjI .edge-depth-9{stroke-width:-13;}#mermaid-svg-AYUUPRe92CBicUjI .section-9 line{stroke:hsl(0, 100%, 86.2745098039%);stroke-width:3;}#mermaid-svg-AYUUPRe92CBicUjI .lineWrapper line{stroke:black;}#mermaid-svg-AYUUPRe92CBicUjI .disabled,#mermaid-svg-AYUUPRe92CBicUjI .disabled circle,#mermaid-svg-AYUUPRe92CBicUjI .disabled text{fill:lightgray;}#mermaid-svg-AYUUPRe92CBicUjI .disabled text{fill:#efefef;}#mermaid-svg-AYUUPRe92CBicUjI .section-10 rect,#mermaid-svg-AYUUPRe92CBicUjI .section-10 path,#mermaid-svg-AYUUPRe92CBicUjI .section-10 circle,#mermaid-svg-AYUUPRe92CBicUjI .section-10 path{fill:hsl(210, 100%, 76.2745098039%);}#mermaid-svg-AYUUPRe92CBicUjI .section-10 text{fill:black;}#mermaid-svg-AYUUPRe92CBicUjI .node-icon-10{font-size:40px;color:black;}#mermaid-svg-AYUUPRe92CBicUjI .section-edge-10{stroke:hsl(210, 100%, 76.2745098039%);}#mermaid-svg-AYUUPRe92CBicUjI .edge-depth-10{stroke-width:-16;}#mermaid-svg-AYUUPRe92CBicUjI .section-10 line{stroke:hsl(30, 100%, 86.2745098039%);stroke-width:3;}#mermaid-svg-AYUUPRe92CBicUjI .lineWrapper line{stroke:black;}#mermaid-svg-AYUUPRe92CBicUjI .disabled,#mermaid-svg-AYUUPRe92CBicUjI .disabled circle,#mermaid-svg-AYUUPRe92CBicUjI .disabled text{fill:lightgray;}#mermaid-svg-AYUUPRe92CBicUjI .disabled text{fill:#efefef;}#mermaid-svg-AYUUPRe92CBicUjI .section-root rect,#mermaid-svg-AYUUPRe92CBicUjI .section-root path,#mermaid-svg-AYUUPRe92CBicUjI .section-root circle{fill:hsl(240, 100%, 46.2745098039%);}#mermaid-svg-AYUUPRe92CBicUjI .section-root text{fill:#ffffff;}#mermaid-svg-AYUUPRe92CBicUjI .icon-container{height:100%;display:flex;justify-content:center;align-items:center;}#mermaid-svg-AYUUPRe92CBicUjI .edge{fill:none;}#mermaid-svg-AYUUPRe92CBicUjI .eventWrapper{filter:brightness(120%);}#mermaid-svg-AYUUPRe92CBicUjI :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;} 遇到报错第一步完整阅读报错信息定位报错类型快速处理第二步升级pip和setuptools 清理缓存 --no-cache-dir 定位根因第三步 yanked?换版本网络?换镜像源导入?查路径与重名根治问题第四步使用虚拟环境规范requirements.txt pip install 报错解决最佳实践时间线

🔔 温馨提示 ：更多Bug解决方案请查看==>全栈Bug解决方案专栏https://blog.csdn.net/lyzybbs/category_12988910.html

如何解决 pip install 安装报错 检测到 yanked 版本需更换可用版本 问题

Python系列Bug修复PyCharm控制台pip install报错：如何解决 pip install 安装报错 检测到 yanked 版本需更换可用版本 问题

文章目录

一、问题出现的开发场景与技术背景

1.1 典型报错场景

1.2 技术细节分析

1.3 开发环境说明

二、报错原因全景排查流程

三、解决方案一：处理 yanked 版本，更换可用版本

3.1 查看包的所有可用版本

3.2 指定可用版本安装

3.3 如果必须使用 yanked 版本（不推荐）

3.4 更新 requirements.txt

四、解决方案二：网络问题------切换国内镜像源

4.1 国内常用 pip 镜像源

4.2 临时使用镜像源（单次安装）

4.3 永久配置镜像源

4.4 PyCharm 内配置镜像源

五、解决方案三：module 包没安装或包名错误

5.1 区分"包名"和"导入名"

5.2 检查包是否真的安装了

六、解决方案四：忘了 import

七、解决方案五：缺少 __init__.py 文件

7.1 问题场景

7.2 解决方案

八、解决方案六：package 版本不兼容

8.1 典型报错

8.2 解决方案

九、解决方案七：自定义包名与第三方包重名

9.1 问题场景

9.2 排查方法

9.3 解决方案

十、解决方案八：PYTHONPATH 未设置或自建包路径不在 PYTHONPATH 下

10.1 问题场景

10.2 解决方案

十一、解决方案九：不恰当的使用相对导入

11.1 问题场景

11.2 解决方案

十二、解决方案十：pip 版本不是最新版

十三、扩展解决方案：更多可能性排查

13.1 pip 缓存损坏

13.2 Python 版本不支持

13.3 操作系统架构问题（Apple Silicon 常见）

13.4 代理 / 公司防火墙

13.5 权限不足（macOS/Linux）

十四、问题解决方案总结

如何解决 pip install 安装报错检测到 yanked 版本需更换可用版本问题

Python系列Bug修复PyCharm控制台pip install报错：如何解决 pip install 安装报错检测到 yanked 版本需更换可用版本问题

七、解决方案五：缺少 `init.py` 文件