根本原因是PYTHONPATH路径设置错误或Python未读取到该值，常见于指向包本身而非其父目录、含未展开的~或相对路径、IDE未重启导致环境变量未生效。
PYTHONPATH 设置后为什么 import 还是报 ModuleNotFoundError
根本原因通常是路径没加对，或者 Python 没读到你设的值。常见情况包括：PYTHONPATH 指向的是包的父目录（不是包本身），路径里混用了相对路径或未展开的 ~，或者你在 IDE 里改了系统环境变量但没重启终端/IDE 进程。
实操建议：
立即学习“Python免费学习笔记（深入）”；
macOS UI 自动化技能包 —— 用 Python 控制你的 Mac
下载
让 macOS 自动化像说话一样简单 —— 用代码控制你的 Mac，无需学习 AppleScript 系统要求 macOS 14+ (Sonoma) Python 3.9+ 需要开启：辅助功能 + 屏幕录制权限
- 用
python -c "import sys; print('\n'.join(sys.path))"确认当前生效的sys.path，检查你的路径是否真在里面 -
PYTHONPATH应该指向「包含__init__.py的包所在目录的上一级」，比如项目结构是/home/user/proj/src/mypkg/__init__.py，那要加的是/home/user/proj/src，不是/home/user/proj/src/mypkg - Linux/macOS 下在 shell 中临时设置：
export PYTHONPATH="/path/to/src:$PYTHONPATH"；Windows 命令行用set PYTHONPATH=C:\path\to\src;%PYTHONPATH% - 避免在脚本里用
sys.path.append()替代PYTHONPATH—— 它只对当前进程有效，且容易因路径顺序引发隐式覆盖
PyCharm / VS Code 中 PYTHONPATH 不生效怎么办
这些工具默认不继承系统 shell 的环境变量，尤其 VS Code 的集成终端可能用的是 login shell，而 GUI 启动时不会加载 ~/.bashrc。
实操建议：
立即学习“Python免费学习笔记（深入）”；
- PyCharm：进
Run → Edit Configurations → Environment variables，手动添加PYTHONPATH=/path/to/src - VS Code：在工作区根目录加
.env文件，写入PYTHONPATH=/path/to/src；或在launch.json的env字段里显式配置 - 验证方式：在调试器里打印
os.environ.get('PYTHONPATH')和sys.path[0]，确认两者一致
用 PYTHONPATH 还是 pip install -e . 更可靠
长期开发推荐 pip install -e .，PYTHONPATH 更适合快速验证或 CI 环境中临时注入路径。
原因很实际：
-
pip install -e .会把包注册进site-packages，支持importlib.metadata、pkg_resources等元数据读取，很多框架（如 pytest、flask CLI）依赖这个机制 -
PYTHONPATH加的路径在sys.path里靠前，容易意外覆盖已安装的同名包（比如本地有个requests目录） -
setup.py或pyproject.toml里定义好packages后，-e安装还能自动处理子包、数据文件、entry_points
Windows 下 PYTHONPATH 路径分隔符和空格问题
Windows 用分号 ; 分隔多个路径，且路径含空格时必须加英文双引号，否则命令行会截断。
典型错误示例：set PYTHONPATH=C:\My Project\src;C:\utils → 实际只生效了 C:\My
正确写法：
- 命令行：
set PYTHONPATH="C:\My Project\src";"C:\utils" - PowerShell：
$env:PYTHONPATH="C:\My Project\src;C:\utils"（PowerShell 不需要引号，但路径含空格仍建议加） - 注册表方式（不推荐）：修改
HKEY_CURRENT_USER\Environment，值类型为REG_EXPAND_SZ，内容填带引号的完整路径串
PYTHONPATH 只是控制起点之一；真正容易被忽略的是：不同启动方式（直接 python、-m、IDE、systemd、Docker）加载环境变量的时机和范围完全不同，别假设设一次就处处生效。 
