sys.path 模块搜索路径的初始化 — Python 3.14.5 文档
Description: 模块搜索路径是在 Python 启动时被初始化的。这个模块搜索路径可通过 sys.path 来访问。 模块搜索路径的第一个条目是包含输入脚本的目录，如果存在输入脚本的话。否则，第一个条目将是当前目录，当执行交互式 shell,-c 命令，或-m 模块时都属于这种情况。 PYTHONPATH 环境变量经常被用于将目录添加到搜索路径。如果发现了该环境变量则其内容将被添加到模块搜索路径中。 随后加...

# `sys.path` 模块搜索路径的初始化

模块搜索路径是在 Python 启动时被初始化的。这个模块搜索路径可通过 `sys.path` 来访问。

模块搜索路径的第一个条目是包含输入脚本的目录，如果存在输入脚本的话。否则，第一个条目将是当前目录，当执行交互式 shell, `-c` 命令，或 `-m` 模块时都属于这种情况。

`PYTHONPATH` 环境变量经常被用于将目录添加到搜索路径。如果发现了该环境变量则其内容将被添加到模块搜索路径中。

备注

`PYTHONPATH` 将影响所有已安装的 Python 版本/环境。在你的 shell 用户配置或全局环境变量中设置它时需要小心谨慎。 `site` 模块提供了下文所述的更细微的技巧。

随后加入的条目是包含标准 Python 模块以及这些模块所依赖的任何 extension module 的目录。扩展模块在 Windows 上为 `.pyd` 文件而在其他平台上则为 `.so` 文件。独立于平台的 Python 模块的目录称为 `prefix`。扩展模块的目录称为 `exec_prefix`。

`PYTHONHOME` 环境变量可以被用于设置 `prefix` 和 `exec_prefix` 的位置。 在其他情况下这些目录将使用 Python 可执行文件作为起始点来确定然后再查找几处 '地标' 文件和目录。 请注意任何符号链接也会被追踪解析以便使用实际的 Python 可执行文件位置作为搜索起始点。这个 Python 可执行文件位置被称为 `home`.

一旦确定了 `home`，则 `prefix` 目录将通过首先查找 `pythonmajorversionminorversion.zip` (`python311.zip`) 来找到。在 Windows 上将会到 `home` 中搜索 zip 归档而在 Unix 上则会到 `lib` 中搜索它。请注意预期的 zip 归档位置即使在此归档不存在时仍然会被添加到模块搜索路径。如果未找到归档，在 Windows 上 Python 将继续通过查找 `Lib\os.py` 来搜索 `prefix`。在 Unix 上 Python 将查找 `lib/pythonmajorversion.minorversion/os.py` (`lib/python3.11/os.py`)。在 Windows 上 `prefix` 和 `exec_prefix` 是相同的，但是在其他平台上则会搜索 `lib/pythonmajorversion.minorversion/lib-dynload` (`lib/python3.11/lib-dynload`) 并将其用作 `exec_prefix` 的锚点。在某些平台上 `lib` 可能为 `lib64` 或其他值，请参阅 `sys.platlibdir` 和 `PYTHONPLATLIBDIR`.

一旦找到，`prefix` 和 `exec_prefix` 将分别在 `sys.base_prefix` 和 `sys.base_exec_prefix` 上可用。

如果未设置 `PYTHONHOME`，而在主可执行文件所在位置或其父目录中找到了 `pyvenv.cfg` 文件，则会将 `sys.prefix` 和 `sys.exec_prefix` 设为包含 `pyvenv.cfg` 的目录，在其他情况下它们会被分别设为与 `sys.base_prefix` 和 `sys.base_exec_prefix` 相同的值。该值将被 虚拟环境 使用。

Finally, the `site` module is processed and `site-packages` directories are added to the module search path. A common way to customize the search path is to create `sitecustomize` or `usercustomize` modules as described in the `site` module documentation.

备注

Certain command line options may further affect path calculations. See `-E`, `-I`, `-s` and `-S` for further details.

在 3.14 版本发生变更: 在路径初始化期间 `sys.prefix` 和 `sys.exec_prefix` 现在会被设为 `pyvenv.cfg` 目录。在之前版本中这是由 `site` 完成的，因而会受 `-S` 影响。

## 虚拟环境

各虚拟环境会在其前缀中放置一个 `pyvenv.cfg` 文件，这将使得 `sys.prefix` 和 `sys.exec_prefix` 指向它们，而非指向基本安装位置。

基本安装版的 `prefix` 和 `exec_prefix` 值可从 `sys.base_prefix` 和 `sys.base_exec_prefix` 获取。

除了用作标识虚拟环境的标记，`pyvenv.cfg` 还可被用来配置 `site` 的初始化。请参阅 `site` 的 虚拟环境文档。

备注

`PYTHONHOME` 将覆盖 `pyvenv.cfg` 检测。

备注

There are other ways how "virtual environments" could be implemented, this documentation refers implementations based on the `pyvenv.cfg` mechanism, such as `venv`. Most virtual environment implementations follow the model set by `venv`, but there may be exotic implementations that diverge from it.

## _pth 文件

若要完全覆盖 `sys.path` 则请创建一个与共享库或可执行文件 (`python._pth` 或 `python311._pth`) 同名的 `._pth` 文件。共享库路径在 Windows 上始终是已知的，但这在其他平台上也许会不可用。 请在 `._pth` 文件中为添加到 `sys.path` 的每个路径指定对应的一行。 基于共享库名称的文件会覆盖基于可执行文件的对应文件，这允许在必要时为任何加载运行时的程序限制路径。

当文件存在时，将忽略所有注册表和环境变量，启用隔离模式，并且：除非文件中的一行指定 `import site`，否则不会导入 `site`。空白路径和以 `#` 开头的行将被忽略。每个路径可以是绝对的或相对于文件的位置。不允许使用除 `site` 以外的导入语句，并且不能指定任意代码。

请注意，当指定 `import site` 时，`.pth` 文件（没有前导下划线）将由 `site` 模块正常处理。

## 嵌入式 Python

如果 Python 被嵌入其他应用程序中则 `Py_InitializeFromConfig()` 和 `PyConfig` 结构体可被用来初始化 Python。路径专属的细节描述见 Python 路径配置。

参见

- 查找模块 了解更多有关 Windows 的细节说明。

- 在类Unix环境下使用Python 了解 Unix 的相关细节。