Python按sys.path顺序查找模块，该路径由脚本目录、PYTHONPATH、标准库路径、site-packages及用户站点路径组成，可动态修改但仅限当前进程，虚拟环境会优先插入其site-packages并屏蔽系统包。
Python 会按 PYTHONPATH 中的路径顺序查找模块，但它不会自动添加到 sys.path 开头，也不覆盖标准库路径 —— 这意味着它只影响你自己写的模块，且顺序很重要。
设置 PYTHONPATH 后 import 仍失败？检查路径是否被实际加载
很多人设了 PYTHONPATH 却发现 import mypackage 报 ModuleNotFoundError，根本原因是 Python 并未真正读取该变量（尤其在 IDE 或某些 shell 环境中）。验证方式很简单：
import sys
print('\n'.join(sys.path))
看输出里有没有你设的路径。常见问题包括：
- 在 PyCharm / VS Code 中修改了系统环境变量，但没重启终端或 IDE（IDE 启动时就已读取环境变量）
- 用
export PYTHONPATH=/path/to/lib设置后，又运行了python -m venv新环境 —— 子进程默认不继承父 shell 的PYTHONPATH（除非显式用--system-site-packages或手动传递） - 路径中含空格或中文，没加引号导致 shell 解析失败（Linux/macOS 下
export PYTHONPATH="/my path/with space"才有效）
Windows 和 Linux/macOS 的写法差异
PYTHONPATH 是路径列表，但分隔符因系统而异，写错会导致整个变量被忽略：
立即学习“Python免费学习笔记（深入）”；
- Linux/macOS：用冒号
:分隔，例如export PYTHONPATH="/home/user/lib:/opt/mytools" - Windows（cmd）：用分号
;分隔，例如set PYTHONPATH=C:\mylib;D:\utils - Windows（PowerShell）：同样用分号，但需用双引号包裹含空格路径：
$env:PYTHONPATH="C:\My Lib;D:\Tools" - 注意：不要在路径末尾加
/或\，Python 不要求也不推荐
与 site-packages 和 .pth 文件的关系
PYTHONPATH 的优先级高于 site-packages，但低于当前脚本所在目录（即 '' 在 sys.path[0]）。这意味着：
- 如果你在
/project/main.py里import utils，而utils同时存在于PYTHONPATH和/project/utils/，Python 会优先导入后者 -
.pth文件（放在site-packages目录下）也能扩展路径，但它只对当前 Python 环境生效，且支持更灵活的语法（如import os; os.environ['MY_PATH']），而PYTHONPATH是全局环境变量，跨解释器生效 - 虚拟环境中，
PYTHONPATH仍有效，但容易和venv的隔离意图冲突 —— 建议只用于开发调试，上线前改用pip install -e .或 proper package layout
临时设置 vs 永久设置的取舍
临时设置适合调试单次运行，永久设置适合本地开发流；但两者都有副作用：
- 临时（推荐）：
PYTHONPATH=/path/to/src python main.py—— 只影响本次执行，不污染环境 - 永久（Linux/macOS）：写入
~/.bashrc或~/.zshrc，但要注意不同项目可能需要不同路径，硬编码易冲突 - 永久（Windows）：系统属性 → 环境变量 → 用户变量，但每次修改需重启 cmd/PowerShell
- 最安全的做法：在项目根目录放一个
pyproject.toml或setup.py，用pip install -e .注册包路径，这样既符合 Python 生态，又避免环境变量管理混乱
真正麻烦的不是怎么设 PYTHONPATH，而是它一旦设错，会在多个项目间悄悄干扰 import 行为，且错误堆栈里完全不提示来源 —— 查的时候得先 print(sys.path)，再逐个路径 ls 或 dir 看是否存在 __init__.py。
