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

Python 启动时会初始化一个模块搜索路径。这个模块搜索路径可以通过 sys.path 访问。

如果存在输入脚本，则模块搜索路径的第一个条目是包含该脚本的目录。否则，第一个条目是当前目录，这发生在执行交互式 shell、-c 命令或 -m 模块时。

PYTHONPATH 环境变量通常用于向搜索路径添加目录。如果找到此环境变量，则其内容会被添加到模块搜索路径中。

备注

PYTHONPATH 将影响所有已安装的 Python 版本/环境。请注意不要在你的 shell 配置文件或全局环境变量中设置它。site 模块提供了下述更精细的技术。

接下来添加的项目是包含标准 Python 模块的目录，以及这些模块所依赖的任何扩展模块。扩展模块在 Windows 上是 .pyd 文件，在其他平台上是 .so 文件。包含平台无关的 Python 模块的目录称为 prefix。包含扩展模块的目录称为 exec_prefix。

PYTHONHOME 环境变量可用于设置 prefix 和 exec_prefix 的位置。否则，这些目录通过以 Python 可执行文件为起点，然后查找各种“地标”文件和目录来找到。请注意，会跟踪任何符号链接，因此实际的 Python 可执行文件位置被用作搜索起点。Python 可执行文件位置称为 home。

一旦确定了 home，就首先通过查找 pythonmajorversionminorversion.zip (python311.zip) 来找到 prefix 目录。在 Windows 上，zip 档案在 home 中搜索，在 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 相同的值。这被 虚拟环境 使用。

最后，处理 site 模块，并将 site-packages 目录添加到模块搜索路径中。自定义搜索路径的常用方法是创建 sitecustomize 或 usercustomize 模块，如 site 模块文档中所述。

备注

某些命令行选项可能会进一步影响路径计算。有关详细信息，请参阅 -E、-I、-s 和 -S。

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 的检测。

备注

还有其他实现“虚拟环境”的方法，本文档指的是基于 pyvenv.cfg 机制的实现，例如 venv。大多数虚拟环境实现都遵循 venv 设置的模型，但可能存在偏离它的奇特实现。

_pth 文件

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

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

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

嵌入式 Python

如果 Python 嵌入在另一个应用程序中，可以使用 Py_InitializeFromConfig() 和 PyConfig 结构来初始化 Python。路径相关的详细信息在 Python 路径配置 中描述。

参见