.pth文件是Python的纯文本路径配置文件，放在site-packages目录下时，会将每行绝对路径自动注入sys.path开头，实现持久化、免代码的模块导入路径扩展。
什么是.pth文件，它为什么能影响Python导入路径
.pth文件是Python解释器识别的纯文本路径文件，放在site-packages目录下时，会自动将其中每行内容（必须是绝对路径）追加到sys.path开头。它不执行代码，只做路径注入，比修改PYTHONPATH更干净，也比在代码里写sys.path.append()更持久。
注意：.pth文件只在Python启动时由site模块加载一次，且仅对启用site的环境生效（比如普通python命令、pip install后的环境），而python -S或某些嵌入式解释器会跳过它。
手动创建.pth文件的三个必要条件
- 文件必须放在已存在于
sys.path中的某个site-packages目录里（常见路径如venv/lib/python3.x/site-packages/或/usr/local/lib/python3.x/site-packages/）
- 文件名必须以
.pth结尾（如myproject.pth），不能是.pth.txt或带空格
- 每行只能写一个绝对路径，不能有注释、空行、环境变量（如
$HOME）或通配符；路径末尾不加/
/home/user/mylib
/opt/shared/utils
sys.path中的某个site-packages目录里（常见路径如venv/lib/python3.x/site-packages/或/usr/local/lib/python3.x/site-packages/）.pth结尾（如myproject.pth），不能是.pth.txt或带空格$HOME）或通配符；路径末尾不加/
如果路径不存在或拼写错误，Python不会报错，但该路径不会被加入sys.path——这是最常见的静默失败原因。
如何确认.pth是否生效
运行Python后检查sys.path是否包含你添加的路径：
python -c "import sys; print([p for p in sys.path if 'mylib' in p])"
或者更直接地，在交互式环境中验证导入：
让 macOS 自动化像说话一样简单 —— 用代码控制你的 Mac，无需学习 AppleScript 系统要求 macOS 14+ (Sonoma) Python 3.9+ 需要开启：辅助功能 + 屏幕录制权限
python -c "import sys; print('\n'.join(sys.path))"
如果没看到目标路径，优先排查：
- 当前Python解释器是否和你放.pth的
site-packages属于同一环境（尤其是conda/virtualenv混用时） -
site-packages目录是否在sys.path中（有些精简镜像会禁用site） - .pth文件权限是否为可读（
ls -l *.pth）
与其它路径扩展方式的关键区别
-
sys.path.insert(0, ...)：仅当前进程有效，每次都要写，容易漏掉子进程或新线程
-
PYTHONPATH：作用全局但污染环境，不同项目间易冲突，且无法按环境区分
-
pip install -e .：适合开发态，但要求包有setup.py或pyproject.toml，对纯模块目录不适用
sys.path.insert(0, ...)：仅当前进程有效，每次都要写，容易漏掉子进程或新线程PYTHONPATH：作用全局但污染环境，不同项目间易冲突，且无法按环境区分pip install -e .：适合开发态，但要求包有setup.py或pyproject.toml，对纯模块目录不适用.pth是唯一能在不改代码、不设环境变量、不走pip安装的前提下，让任意目录“伪装”成已安装包的方式。但它不解决依赖解析，也不会触发init.py自动执行——路径下仍需符合Python包结构才能正常import。
.pth文件本身没有加载顺序保证，多个.pth按字母序读取，但所有.pth路径都插在site-packages之前；如果你依赖某个第三方包，又想用自己的同名模块覆盖它，就得确保.pth路径在sys.path中排得比那个包更靠前——这往往需要重命名.pth文件（如00-myoverride.pth）来控制排序。
Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
