CPython 中 sys.path 模块搜索路径的初始化机制详解

CPython 在启动时会基于输入脚本、环境变量、可执行文件位置与各类“landmark”（地标）文件逐层推算模块搜索路径，最终结果暴露在 sys.path 中。本文以 CPython 官方文档 Doc/library/sys_path_init.rst 为骨架，结合仓库中 Modules/getpath.py（路径计算的实际规范实现）、Python/pathconfig.c 与 Lib/site.py 的源码，完整梳理从脚本目录到 site-packages 的全过程，帮助你理解 sys.path 各条目从何而来、为何顺序如此，以及在虚拟环境、._pth 文件和嵌入式场景下如何精确控制搜索路径。

一、总览：sys.path 的初始化顺序

每次 Python 解释器启动时，模块搜索路径（module search path）都会被初始化，最终结果存放在 sys.path。根据官方文档描述，完整流程大致如下：

1. 第一条目：包含输入脚本的目录；若无脚本（交互式 shell、-c 命令或 -m 模块），则是当前目录；
2. PYTHONPATH 环境变量指定的目录；
3. 标准库目录（platform-independent 的 prefix）与扩展模块目录（platform-dependent 的 exec_prefix）；
4. 虚拟环境处理：若存在 pyvenv.cfg，则 sys.prefix / sys.exec_prefix 指向虚拟环境；
5. site 模块处理并追加 site-packages 目录（含用户级 site-packages）。

这一套顺序并非写死的常量，而是运行期根据可执行文件位置、环境变量和文件系统现状动态推算出来的。仓库中的实际计算发生在 Python/pathconfig.c 的 _PyPathConfig_InitPathConfig() 中，它把一份高度可移植的 Python 脚本 Modules/getpath.py 预编译成字节码后直接求值执行。该脚本顶部注释即为整个算法的最权威说明，我们可以据此一步步拆解。

二、sys.path[0]：脚本目录还是当前目录

文档开门见山地规定了搜索路径的第一条目：

• 存在输入脚本时，第一条目为脚本所在目录；
• 否则（交互模式、-c、-m）第一条目为当前目录。

它的计算并不发生在 Modules/getpath.py 中，而是在启动接近尾声时由 Python/pathconfig.c 的 _PyPathConfig_ComputeSysPath0() 完成，其核心逻辑为：

int
_PyPathConfig_ComputeSysPath0(const PyWideStringList *argv, PyObject **path0_p)
{
    wchar_t *argv0 = argv->items[0];
    int have_module_arg = (wcscmp(argv0, L"-m") == 0);
    int have_script_arg = (!have_module_arg && (wcscmp(argv0, L"-c") != 0));
    ...
}

• 当 argv[0] 为 -m 时，调用 _Py_wgetcwd() 取当前工作目录的绝对路径作为 path0；
• 当 argv[0] 为脚本（have_script_arg）时，先经 realpath/GetFullPathNameW 解析符号链接得到真实路径，再截取最后一个路径分隔符（/ 或 \）之前的目录部分，即“脚本所在目录”；
• 若符号链接指向纯文件名或相对路径，则按文档注释中的特殊规则（链接无路径 / 需拼接目录）处理；
• 若当前工作目录已被删除或 argv 为空，函数返回 0，sys.path 保持不变。

而 argv[0] 为 -c 时，have_script_arg 为假，最终 path0 就是 argv[0] 本身经处理后的结果。随后在 Python/sysmodule.c 的 sys.path 初始化代码中，只有当 argv[0] 不是 -c 也不是 -m 时才会把 path0 前置到 sys.path。这解释了为何同样执行 python script.py、python -c ...、python -m pkg 时 sys.path[0] 的表现各异。

顺带一提，脚本以符号链接方式被调用时，这里会先解析真实路径，再取真实路径的所在目录，而非符号链接所在目录（Unix 下 realpath 行为，Windows 下对应 GetFullPathNameW）。

三、PYTHONPATH：向搜索路径追加目录

在脚本目录/当前目录之后，解释器检查 :envvar:PYTHONPATH 环境变量，若存在则将其中列出的目录追加进搜索路径。在 Modules/getpath.py 的 UPDATE pythonpath (sys.path) 段落中，环境变量中的每条目经 abspath() 转为绝对路径后依次追加：

if use_environment and ENV_PYTHONPATH:
    for p in ENV_PYTHONPATH.split(DELIM):
        pythonpath.append(abspath(p))

注意几个细节：

• 路径分隔符在 POSIX 上为 :，在 Windows 上为 ;（脚本内常量 DELIM）；
• PYTHONPATH 目录在 sys.path 中的位置先于标准库目录——因此若在此加入了与标准库重名的包，导入时会优先命中 PYTHONPATH 中的版本；
• 该变量并非无副作用，官方文档专门给出了警告：

PYTHONPATH 会影响到所有已安装的 Python 版本/环境。在 shell 配置文件或全局环境变量中设置它时务必谨慎。若需要更精细的控制，推荐使用下文提到的 site 模块机制。

也就是说，若你的机器上同时存在系统 Python、多个虚拟环境或其他解释器发行版，全局设置 PYTHONPATH 会让所有这些环境共享同一份额外的导入路径，很容易造成版本污染。可用 Lib/site.py 提供的方式（sitecustomize、usercustomize、site-packages、.pth）替代。

四、标准库与扩展模块目录：prefix / exec_prefix 的推导

4.1 基本概念

在 PYTHONPATH 之后加入的是存放标准库纯 Python 模块及扩展模块的目录：

• prefix：存放与平台无关的 Python 模块（如 os.py、json/）；
• exec_prefix：存放平台相关的扩展模块（extension modules）。

扩展模块在 Windows 上是 .pyd 文件，在其他平台上是 .so 文件。对应到磁盘布局，Unix 安装中典型的 prefix 是 /usr/local（其下 lib/python3.x/os.py 为 landmark），exec_prefix 通常与之相同；在 Windows 上 prefix 与 exec_prefix 恒为同一目录。平台相关的 lib 目录名可能为 lib64 或其他值，可通过 sys.platlibdir 与 :envvar:PYTHONPLATLIBDIR 查看/指定。

4.2 home 的确定

• home 指真实 Python 可执行文件所在位置（任何符号链接都会被解析，最终真实可执行文件的位置才是搜索起点）。
• home 的来源优先级依次包括：Py_SetPythonHome()、:envvar:PYTHONHOME、pyvenv.cfg 的 home 字段、._pth 文件目录、以及构建目录（build directory）检测。
• 确定可执行文件时：若 argv[0] 不含路径分隔符，则会在 $PATH 中查找同名可执行文件；若找不到，回退使用原始 argv[0]。macOS 与 Windows 还可直接从运行进程读取 real_executable。

4.3 用“landmark”反推 prefix / exec_prefix

Modules/getpath.py 的高层算法注释（原 getpath.c 注释的延续）说明了核心思想：以可执行文件目录为起点，不断向父目录回溯（search_up），直到在某层找到 landmark 文件/目录，从而确定 prefix 与 exec_prefix。脚本还细分了不同平台的 landmark：

用途	Unix（os_name=='posix'/'darwin'）	Windows（nt）
标准库目录	lib/python{MAJOR}.{MINOR}{+t}/os.py（或 os.pyc）	Lib\os.py
平台标准库（扩展模块）	lib/python{MAJOR}.{MINOR}{+t}/lib-dynload（目录，用于锚定 exec_prefix）	与 prefix 相同（DLLs 由平台代码单独处理）
zip 归档 landmark	lib/python{MAJOR}{MINOR}{+t}.zip（python311.zip）	python{MAJOR}{MINOR}{_d}.zip，在 home 中查找

上面表格中 {+t} 表示 free-threaded（自由线程）构建才会附加的 t 后缀，由编译期常量 ABI_THREAD 决定，例如 lib/python3.14t。

文档对 landmark 搜索次序的描述与代码完全一致：

1. 先检查 python{major}{minor}.zip（如 python311.zip）归档文件：Windows 在 home 中查找，Unix 预期归档位于 lib 下。注意：即便该 zip 文件实际不存在，其预期位置也会被加入模块搜索路径（见 Modules/getpath.py 中无条件 pythonpath.append(stdlib_zip) 的代码）；
2. Windows 未找到 zip 时继续以 Lib\os.py 为 landmark 寻找 prefix；
3. Unix 则以 lib/python{MAJOR}.{MINOR}/os.py（例如 lib/python3.11/os.py）为 landmark 寻找 prefix；
4. exec_prefix 在 Unix 上以 lib/python{MAJOR}.{MINOR}/lib-dynload 目录为锚点搜索；Windows 上 prefix == exec_prefix。

代码中 search_up() 的实现本身很短，恰好体现了“向上回溯 + 逐一测试 landmark”的本质：

def search_up(prefix, *landmarks, test=isfile):
    while prefix:
        if any(test(joinpath(prefix, f)) for f in landmarks):
            return prefix
        prefix = dirname(prefix)

若以上基于 home 的搜索全部失败，则回退使用编译期由 configure/Makefile 注入的 PREFIX 与 EXEC_PREFIX 宏，同时打印 “Could not find platform independent libraries ” 之类的警告。在嵌入场景或可执行文件被移动的情况下，还可能见到 “Consider setting $PYTHONHOME to [:<exec_prefix>]” 的提示。最终找到的 prefix、exec_prefix 会分别记录到 sys.base_prefix 与 sys.base_exec_prefix。

五、PYTHONHOME：手工指定 prefix 与 exec_prefix

:envvar:PYTHONHOME 用于直接指定 prefix 和 exec_prefix 位置，从而绕过整套 landmark 搜索。其取值规则为：

• 只给一个目录：该目录同时作为 prefix 和 exec_prefix；
• 给出两个以路径分隔符（POSIX 为 :，Windows 为 ;）分开的目录：前者为 prefix，后者为 exec_prefix。

Modules/getpath.py 中用 partition(DELIM) 直接拆解：

prefix, had_delim, exec_prefix = home.partition(DELIM)
if not had_delim:
    exec_prefix = prefix

另外要特别注意两点：

• PYTHONHOME 由 use_environment 开关控制——-E、-I 等隔离选项会使其失效（见下文第七节）；
• PYTHONHOME 的优先级高于 pyvenv.cfg 的 home 字段检测，官方文档在虚拟环境一节专门用 note 强调了这一点。

在带 venv 的常规使用中并不需要手动设置它；它主要面向“把 Python 安装迁移到新位置后无法通过 landmark 定位”或嵌入式宿主等场景。

六、虚拟环境：pyvenv.cfg 机制与 3.14 的行为变更

6.1 虚拟环境的识别与 sys.prefix 切换

venv 等虚拟环境实现的核心机制是：在环境根目录放置一个 pyvenv.cfg 文件，其中用 home 字段记录基础安装的解释器位置。路径初始化时：

1. 解释器在可执行文件所在目录以及其父目录查找 pyvenv.cfg（Modules/getpath.py 中先试 dirname(executable_dir)，失败再试 executable_dir 本身）；
2. 读取 home 字段后，用它覆盖 executable_dir，从而把之后所有 prefix 搜索的起点“指回”基础安装；
3. 若未设置 PYTHONHOME 且找到了 pyvenv.cfg，则 sys.prefix 与 sys.exec_prefix 会被设为包含 pyvenv.cfg 的目录（即虚拟环境根目录），否则与 sys.base_prefix / sys.base_exec_prefix 相同；
4. 基础安装的 prefix / exec_prefix 则保存在 sys.base_prefix / sys.base_exec_prefix 中，随时可供恢复。

对应代码是 Modules/getpath.py 中的：

if venv_prefix:
    if not base_prefix:
        base_prefix = prefix
    if not base_exec_prefix:
        base_exec_prefix = exec_prefix
    prefix = exec_prefix = venv_prefix

此后 Lib/site.py 的 venv() 函数会读取 pyvenv.cfg，依据其中 include-system-site-packages 的值（不区分大小写，布尔化后解析）决定是否把系统级 site-packages 一并纳入搜索，实现“是否继承全局包”的开关。

6.2 版本行为变更（3.14 起）

官方文档中的 versionchanged 3.14 条目非常重要：

自 3.14 起，sys.prefix 与 sys.exec_prefix 在路径初始化期间就被设置为 pyvenv.cfg 所在目录。此前这一步由 site 模块完成，因而会受 -S（不处理 site）影响。

也就是说，在 Python 3.14 及以后，即使带 -S 启动、禁用 site 处理，进入虚拟环境的解释器其 sys.prefix 依旧正确指向虚拟环境；而旧版本中 -S 会导致这一赋值被跳过。这属于启动顺序重构（把 venv 判定前移到路径初始化阶段）带来的可观测差异。

6.3 两种“虚拟环境”实现的边界说明

文档还特别提示：虚拟环境并非只有一种实现方式；本文及 sys.prefix 语义所描述的是基于 pyvenv.cfg 机制的实现（如标准库 :mod:venv），当前绝大多数第三方虚拟环境/环境管理工具也都遵循这一机制。

七、_pth 文件：彻底覆盖 sys.path

7.1 文件名与位置

如果想完全自定义而不是逐级追加 sys.path，可以创建一个与共享库或可执行文件同名的 ._pth 文件，例如 Windows 上的 python._pth、python311._pth。其搜索位置与优先级（见 Modules/getpath.py 的 DETECT _pth FILE 段落）为：

1. 主 DLL/动态库（library）同目录；
2. 原始可执行文件同目录；
3. 实际可执行文件（realpath 之后）同目录。

其中基于共享库名字的文件优先级最高，会覆盖基于可执行文件命名的文件——这样宿主程序即便加载了某个共享库，也可通过库旁的 ._pth 限制 Python 的搜索范围。Windows 上共享库路径总能获知，其他平台则未必总是可用。

7.2 文件内容语义

._pth 文件每行写一个要加入 sys.path 的路径，支持以下规则：

• 每行一个路径，可以是绝对路径，也可以是相对该文件所在位置的相对路径（代码中统一用 joinpath(pth_dir, line) 拼接）；
• 空行与被 # 注释的行被忽略；
• 只有 import site 这一句 import 被允许，写上它即表示恢复导入 site 模块；
• 其他 import 语句不被允许（会打印 unsupported 'import' line in ._pth file 警告）；任意代码同样不允许指定；
• 无前导下划线的 .pth 文件（普通 .pth）在 import site 生效后仍会被 site 模块正常处理。

7.3 副作用：隔离模式与禁用环境变量

官方文档明确：只要 ._pth 文件存在，就会触发一连串副作用——所有注册表与环境变量被忽略、隔离模式（isolated mode）被启用、且默认不导入 site（除非文件中写了 import site）。对应源码为 Modules/getpath.py 中：

config['isolated'] = 1
config['use_environment'] = 0
config['site_import'] = 0
config['user_site_directory'] = 0
config['safe_path'] = 1

._pth 机制常被 Windows 上的便携版 Python 发行方用来锁定模块搜索范围，避免便携安装受机器上其他 Python/环境变量干扰。

八、site 模块：site-packages 与用户级搜索路径

整个流程的收尾由 :mod:site 模块完成：处理完毕后，site-packages 目录被加入模块搜索路径。文档给出了两个控制开关：

• :envvar:PYTHONUSERBASE：控制“用户级 site-packages”的搜索根目录（默认在 Unix 为 ~/.local，Windows 为 %APPDATA%\Python，细节见 Lib/site.py 的 getuserbase()）；
• :envvar:PYTHONNOUSERSITE：设置后完全不搜索用户级 site-packages。

Lib/site.py 用 ENABLE_USER_SITE 全局开关统一协调这些逻辑：启动时会调用 check_enableusersite() 读取环境变量与配置，随后 addusersitepackages() / addsitepackages() 分别负责追加用户级与全局的 site-packages；用户目录仅在 ENABLE_USER_SITE 为真且目录实际存在时才被加入。命令行选项 -s（抑制用户 site）正是通过关闭该开关生效。

在虚拟环境里，site 还会依据 pyvenv.cfg 决定是否并入系统 site-packages。此外，官方文档推荐的更细粒度自定义方式是在标准库 site 的机制内提供 sitecustomize 或 usercustomize 模块——前者在每个 site 初始化时导入，后者在用户 site 启用时导入，适合按机器或按用户注入额外搜索路径，而无需触碰全局 PYTHONPATH。

九、命令行选项对路径计算的综合影响

文档在“总览”之后的 note 中提醒：-E、-P、-I、-S、-s 会进一步影响路径计算，其语义分别如下（均可从 Modules/getpath.py 的 use_environment、isolated、site_import、safe_path 等配置项对应到代码）：

选项	名称	对路径计算的影响
-E	忽略环境变量	不读取 :envvar:PYTHONPATH、:envvar:PYTHONHOME、:envvar:PYTHONUSERBASE 等（use_environment=0）
-P	安全路径（safe path）	不自动把脚本目录/当前目录前置到 sys.path[0]（safe_path=1）
-I	隔离模式	等效 -E + -P + -s 的组合
-S	不初始化 site	跳过 site 模块，不追加任何 site-packages（site_import=0）；注意自 3.14 起不再影响 sys.prefix 的 venv 赋值
-s	不加入用户 site	抑制用户级 site-packages（user_site_directory=0）

其中 -I 因同时禁用环境变量与用户 site、并移除 sys.path[0]，是最常用于“无干扰复现导入问题”的调试手段。

十、嵌入场景：PyConfig 与路径初始化

若 Python 被嵌入到其他应用程序中，可通过 :c:func:Py_InitializeFromConfig 配合 :c:type:PyConfig 结构体完成初始化，其中与路径相关的全部细节汇总于 PyConfig 的路径配置章节（:ref:init-path-config）。嵌入者通常关心这几个字段：

• program_name / executable / base_executable：作为一切搜索的起点；
• home：对应 Py_SetPythonHome()，等价于设置 :envvar:PYTHONHOME；
• module_search_paths / module_search_paths_set：直接给出最终 sys.path 内容并跳过自动计算；
• site_import、use_environment、user_site_directory、safe_path、isolated：控制上述各环节是否生效；
• 全局便捷接口 Py_SetPath()：一次性整体覆盖搜索路径。调用后 Modules/getpath.py 会跳过 landmark 搜索、venv 检测与 ._pth 查找，并把 prefix / exec_prefix 强制置空字符串（py_setpath 分支），因此希望保留 venv 语义的嵌入程序应改用 PyConfig.module_search_paths 逐项配置，而不是 Py_SetPath()。

可执行文件与库的符号链接追踪（realpath）、构建目录检测（依赖 pybuilddir.txt，路径初始化时为规避相关安全风险要求该文件必须存在）等细节，也都发生在这一阶段。

十一、快速自检：如何观察与验证

在实际环境中，可用下面的命令直接观测整个初始化链条的结果：

# 观察 sys.path 各条目与来源目录
python -c "import sys, pprint; pprint.pp(sys.path)"

# 观察 prefix 系属性（venv 内外对比更明显）
python -c "import sys; print(sys.prefix); print(sys.base_prefix)"
python -c "import sys; print(sys.exec_prefix); print(sys.base_exec_prefix); print(sys.platlibdir)"

# 检查虚拟环境是否生效、是否继承系统包
python -c "import sys; print(sys.prefix, sys.base_prefix)"

在虚拟环境内、外分别执行对比，即可看到 sys.prefix 随 pyvenv.cfg 切换、而 sys.base_prefix 保持不变的现象。想要复现 landmark 搜索失败的情形，可以临时把可执行文件复制到脱离其安装结构的位置再执行，通常能观察到 getpath 输出的 Could not find platform independent libraries <prefix> 警告——这正好反向印证了第四节所述的向上搜索算法。

十二、总结

CPython 的 sys.path 初始化是一条高度依赖“位置推断”而非“固定预设”的流水线：脚本/当前目录 -> PYTHONPATH -> zip 归档与标准库 prefix -> exec_prefix 扩展模块目录 -> pyvenv.cfg 虚拟环境切换 -> site 的 site-packages 收尾。理解每一层条目的来源与 landmark 搜索规则，是排查“模块导不到 / 导错版本 / 便携环境串包”等问题的前提。若想进一步深挖，可直接阅读 Modules/getpath.py（路径计算的可执行规范）、Lib/site.py（site 与用户目录逻辑）、Python/sysmodule.c（sys 属性落地），并对照 Windows 平台的模块查找细节（见 windows_finding_modules）与本篇的 Unix 侧描述交叉验证。