Python 启动阶段耗时分析的方法

用 python -x importtime 快速定位启动瓶颈，它按耗时倒序输出模块导入时间，配合 2>&1 | grep -e “import|total” | tail -20 过滤关键行；注意其仅适用于 cpython 3.7+，且不干扰运行时行为。

怎么快速定位 Python 启动慢的瓶颈

Python 脚本或服务启动慢，八成不是代码逻辑问题，而是启动阶段的模块加载、路径扫描、字节码生成或环境初始化拖了后腿。直接上 python -X importtime 是最快切入点——它会在导入每个模块时打印耗时，输出按时间倒序排列，一眼就能揪出最重的几个 import。

注意：这个开关只在 CPython 3.7+ 有效，且输出是纯文本流，建议配合 2>&1 | grep -E "import|total" | tail -20 过滤关键行。别用 time python script.py，它测的是整个执行周期，掩盖了启动和运行的差异。

• -X importtime 不影响运行时行为，但会显著增加启动开销（尤其导入深的包），仅用于诊断
• 输出里每行末尾的数字是微秒级耗时，import time 可能显示 50000（50ms），而 import pandas 动辄几百万微秒
• 如果看到大量 importlib._bootstrap 或 _frozen_importlib_external 占高，说明模块查找路径（sys.path）里存在大量无效目录或网络挂载点

为什么 site-packages 多会导致启动变慢

Python 启动时会扫描 site-packages 下所有 .pth 文件，并执行其中的 Python 代码；还会遍历每个包的 __init__.py（哪怕为空）来确认是否为合法包。当项目依赖多、虚拟环境老旧、或误装了带副作用的开发包（比如某些调试工具自动 patch import），启动就会卡在这些隐式操作上。

典型症状：python -c "pass" 很快，但 python -c "import sys; print(len(sys.path))" 显示路径条目超过 50 条，尤其含 /usr/local/lib/python3.x/site-packages 和多个虚拟环境混杂路径。

立即学习“Python免费学习笔记（深入）”；

• 检查当前 sys.path：运行 python -c "import sys; [print(p) for p in sys.path]"
• 临时清理路径：用 PYTHONPATH= python script.py 测试是否变快，确认是否由第三方路径引入
• 禁用 .pth 扫描：加 -S 参数（跳过 site 模块），但会丢失所有第三方包——仅用于验证是否为根源

__pycache__ 和字节码生成对首次启动的影响

Python 第一次导入一个模块时，会将其编译为字节码并写入 __pycache__/module.cpython-3x.pyc。如果目标目录不可写（如容器只读文件系统、CI 环境无权限）、或磁盘 I/O 极慢（NAS、加密卷），这个过程就会阻塞启动，且错误往往静默——没有报错，只是卡住几秒到几十秒。

常见于 docker 镜像构建后未预编译、或部署时把源码挂载为只读卷的场景。此时 importtime 日志里会出现某模块耗时异常高，但没对应错误信息。

• 预编译全部源码：python -m compileall -f -l path/to/package，-f 强制重编，-l 不递归子包（避免污染）
• 跳过写缓存：PYTHONDONTWRITEBYTECODE=1 python script.py，代价是每次启动都重新编译，仅限调试
• 检查缓存目录权限：ls -ld $(python -c "import sys; print(sys.path[0])")/__pycache__，确认用户有写权限

哪些第三方工具会悄悄拖慢启动

有些库在模块顶层就执行耗时操作：比如 requests 会预加载 ssl 证书、sqlalchemy 做方言检测、click 解析装饰器树。更隐蔽的是日志配置库（如 loguru 默认加载配置文件）、配置中心客户端（如 etcd 或 nacos 的 SDK 在 import 时尝试连接）。

它们不会报错，但会让 import xxx 耗时陡增。一旦在 importtime 输出里发现某个非核心依赖排进前五，就要警惕。

• 延迟导入：把 import heavy_module 移到函数内部，而非模块顶层
• 禁用自动初始化：如 loguru 加 disable=True 参数，sqlalchemy 用 create_engine(..., echo=False)
• 检查 __init__.py：打开疑似包的 __init__.py，看是否有同步网络调用、大文件读取、或循环 import

真正难排查的，是多个小开销叠加：10 个模块各慢 200ms，加起来就是 2 秒。别只盯着最大的那个，得把 importtime 输出导出排序，从头扫三遍——第三遍常会发现被忽略的路径扫描或隐式依赖。