应将含__init__.py的最外层包目录右键标记为Sources Root，使其图标变为蓝色小圆点，PyCharm才能正确识别本地模块路径并支持导入、补全与跳转。
PyCharm里import本地模块报ModuleNotFoundError怎么办
不是包没装好，也不是代码写错了，大概率是PyCharm根本没把你的模块目录当“源码根目录”看。它默认只认sys.path里已有的路径，而你写的from mypackage import utils，如果mypackage不在任何被识别的源根下，PyCharm就当它不存在——编辑器不识别、补全失效、跳转失败，运行时也可能崩（取决于实际sys.path）。
解决方法非常直接：
- 在项目文件树中，右键点击包含
__init__.py的最外层包目录（比如src或lib或你的项目名文件夹） - 选择 Mark Directory as → Sources Root
- 确认该目录图标变成蓝色小圆点（PyCharm UI标识），此时所有子模块都能被正常解析
注意：不要标记单个.py文件，也不要标记空目录；必须是含__init__.py且作为导入起点的包层级。
为什么sys.path里有却还是报错
PyCharm的静态分析（语法检查、跳转、补全）和实际运行时的sys.path是两套逻辑。你在终端跑python main.py能成功，是因为当前工作目录或PYTHONPATH恰好把父目录加进去了；但PyCharm默认用项目根目录作为工作目录，并不会自动把所有子目录塞进sys.path——除非你显式标记为Sources Root。
常见误导场景：
- 你把
myproject/utils.py放在项目根下，然后写import utils—— 这行得通，但from myproject.utils import xxx会失败，因为myproject没被标记为源根 - 你用
pip install -e .安装了本地包，但PyCharm解释器没刷新，或者没启用“Show all packages”，导致包名不显示在解释器列表里 - 你改过
sys.path.append(…)，运行时能过，但PyCharm静态分析仍报红——这是预期行为，不能靠运行时hack掩盖结构问题
PyCharm设置解释器后仍找不到本地模块
解释器配置只影响第三方包索引和运行环境，对本地模块路径无直接影响。即使你用了正确的虚拟环境，如果没设Sources Root，PyCharm照样不认识你写的models或core目录。
PyCharm 2026.2是 JetBrains PyCharm 的指定版本安装包，下载地址指向官方 Windows 安装包直链，可用于旧项目兼容、版本回退和环境测试。
关键动作只有两个：
- 确保目标目录被标记为
Sources Root（右键 → Mark Directory as → Sources Root） - 检查PyCharm右下角是否显示了正确解释器，且该解释器路径与你终端执行
which python一致（避免虚拟环境混用） - 如果刚改完设置，点一下菜单栏 File → Reload project from disk，或按
Ctrl+Shift+O强制重载索引
别依赖“自动检测”——PyCharm不会自动推断你哪一层该是源根，必须人工指定。
多级嵌套包导入时容易漏掉的细节
比如目录结构是：project/ ├── app/ │ ├── __init__.py │ └── handlers/ │ ├── __init__.py │ └── user.py ├── models/ │ ├── __init__.py │ └── user.py └── main.py
你想在main.py里写from app.handlers.user import xxx，就必须把project（即app和models共同父目录）设为Sources Root。只标app或只标models会导致跨包导入失败。
更隐蔽的问题：
-
__init__.py为空或缺失 → 包不成立，标记无效 - 目录名含中文、空格或特殊字符 → PyCharm可能无法稳定识别，建议全英文命名
- 使用WSL或远程解释器 → Sources Root路径需映射到远程文件系统路径，本地标记无效
真正起作用的永远是“谁被标记 + 谁在__init__.py里暴露了接口”，而不是文件物理位置有多近。
