sitecustomize.py 是 Python 启动时由 site 模块自动导入的模块，位于当前环境的 site-packages 目录下，会在每次标准启动时早于用户代码执行，用于路径修补、日志初始化等轻量预设，但不适用于冻结程序或嵌入式环境。
sitecustomize.py 是什么，它真能自动执行吗
sitecustomize.py 是 Python 启动时由 site 模块自动导入的模块，前提是它存在于当前 Python 环境的 site-packages 目录下，且没有被禁用（比如启动时加了 -S 参数）。它确实会在每次 Python 解释器启动（包括 python script.py、python -c、甚至 IPython/Jupyter 内核）时早于用户代码执行，但仅限于标准启动流程。
- 它不是“全局钩子”，对冻结打包后的可执行文件（如 PyInstaller 生成的 exe）、嵌入式 Python 或某些容器化环境可能完全不生效
- 它的执行时机在
sys.path初始化之后、<strong>main</strong>加载之前，适合做路径修补、日志初始化、环境预设等 - 如果同目录存在
usercustomize.py，它也会被加载，但默认不存在，优先级低于sitecustomize.py
怎么放对位置：找到真正的 site-packages 路径
放错位置是失败最常见的原因。Python 可能有多个 site-packages（系统级、用户级、虚拟环境），必须确认你改的是当前解释器实际使用的那个：
运行
python -c "import site; print(site.getsitepackages())"（多路径时取第一个）-
或更可靠：运行
python -c "import sitecustomize; print(sitecustomize.<strong>file</strong>)"（如果已存在，直接看到路径）立即学习“Python免费学习笔记（深入）”；
虚拟环境中，通常是
venv/lib/python3.x/site-packages/；用户级可能是~/.local/lib/python3.x/site-packages/不要手动创建整个路径，先用
pip show pip看Location:，再拼出site-packages文件必须叫
sitecustomize.py，不能是sitecustomize.pyc或带其他后缀权限需可读，且不能有语法错误，否则 Python 启动会报
ImportError并继续——但你的代码不会运行
写什么代码：安全边界和典型用途
sitecustomize.py 里写的代码会直接影响所有 Python 启动行为，稍有不慎就导致整个环境瘫痪（比如意外覆盖 print 或修改 sys.excepthook）。只做轻量、幂等、无副作用的事：
添加额外路径：
import sys; sys.path.insert(0, "/my/utils")设置默认编码（仅限旧版 Python）：
import sys; sys.setdefaultencoding("utf-8")（Python 3 不需要）预加载调试工具：
import faulthandler; faulthandler.enable()关闭烦人的警告：
import warnings; warnings.filterwarnings("ignore", category=DeprecationWarning)避免调用耗时操作（如网络请求、大文件读取），它会拖慢每个 Python 启动
不要尝试 patch
builtins（如重写open），不同解释器行为不一致，且可能被后续 import 覆盖不要依赖
<strong>name</strong> == "<strong>main</strong>"，它永远是"sitecustomize"
替代方案比 sitecustomize.py 更可控
真正需要“每次脚本启动都运行”的场景，sitecustomize.py 往往不是最优解：
- 对单个项目：用
pyproject.toml的[tool.setuptools.script-launcher]或封装 shell wrapper - 对调试需求：直接设置环境变量
PYTHONSTARTUP=/path/to/startup.py（仅交互式有效） - 对强制初始化：在项目入口
<strong>init</strong>.py或主模块顶部显式 import 一个初始化模块，语义清晰、可测试、易关闭
sitecustomize.py 的隐蔽性是双刃剑——别人接手你的环境时，根本想不到某段逻辑藏在 site-packages 里，而且无法用常规 import 语句定位或 disable。除非你在构建一个封闭的内部 Python 发行版，否则优先选显式、可追踪的方式。
