pycharm报“modulenotfounderror”但文件存在，根本原因是未将模块所在目录设为sources root，导致编辑器和运行时均无法识别导入路径；需右键目录→mark directory as→sources root，并确保包内含__init__.py文件。
PyCharm 报 “ModuleNotFoundError” 但文件明明存在
这不是代码写错了，是 PyCharm 没把你的目录当“源码根目录”——它默认只在 sys.path 里找模块，而你自己的 .py 文件夹没被加进去。
典型现象：同级目录下有 utils.py，另一个 main.py 写了 import utils，却标红报错；终端用 python main.py 却能正常运行。
- 右键点击包含你模块的文件夹（比如
src或项目根目录）→ Mark Directory as → Sources Root - 这个操作会在该目录下生成一个
.idea/modules.xml记录，并让 PyCharm 自动把路径加进PYTHONPATH - 如果目录里没有
__init__.py，且你要以包形式导入（如from mypkg import helper），记得手动新建空的__init__.py
为什么 pip install 成功了，PyCharm 还是找不到自定义包？
因为你装的是系统或虚拟环境里的包，而 PyCharm 当前项目用的是另一个解释器——常见于用 conda 创建的环境、或 PyCharm 自动新建的 venv。
检查右下角状态栏显示的解释器路径，和你在终端执行 which python（macOS/Linux）或 where python（Windows）输出的是否一致。
- 不一致？去
File → Settings → Project → Python Interpreter，点右上角齿轮 →Add → Existing environment，选对那个带你的包的python.exe或python可执行文件 - 如果是 conda 环境，选
Conda Environment → Existing environment，路径指向envs/xxx/bin/python（macOS/Linux）或envs\xxx\python.exe（Windows） - 别依赖 PyCharm Terminal 里
pip install—— 它只装到当前 interpreter，可能不是你命令行用的那个
勾选 “Add content roots to PYTHONPATH” 有用吗？
有用，但只影响 Python Console 和 Debug 控制台，不影响代码编辑时的静态解析和跳转。
PyCharm 2026.2是 JetBrains PyCharm 的指定版本安装包，下载地址指向官方 Windows 安装包直链，可用于旧项目兼容、版本回退和环境测试。
路径： File → Settings → Tools → Python Console，勾选 Add content roots to PYTHONPATH 和 Add sources roots to PYTHONPATH。
- 勾上后，在 PyCharm 底部 Python Console 里
import本地模块就不再报错 - 但它不解决编辑器里红色波浪线、无法 Ctrl+Click 跳转的问题——那些仍取决于
Sources Root标记 - 如果你主要用 Console 做交互式开发（比如数据分析），这个选项值得开；否则优先做
Mark Directory as → Sources Root
include-system-site-packages = true 是什么？
这是 venv 的配置开关，控制虚拟环境是否“看到”系统 site-packages 里的包。PyCharm 新建项目默认关掉它，所以即使你全局 pip 装了 mylocalpkg，新 venv 也看不到。
修改位置：venv/pyvenv.cfg（Windows 下可能是 venv\pyvenv.cfg）
- 打开该文件，把
include-system-site-packages = false改成true - 改完重启 PyCharm，再看
Python Interpreter页面，应该能看到系统已安装的包（包括你自己开发的包） - 注意：这会污染虚拟环境隔离性，仅适合临时调试；长期建议用
pip install -e .开发安装方式
最常被忽略的一点：PyCharm 的模块识别是两套机制并行的——编辑器靠 Sources Root + __init__.py 做静态分析，运行时靠解释器的 sys.path。两者不同步，就会出现“能跑不能导”或“能导不能跳”的割裂感。
