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 上，将在 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.prefix 和 sys.exec_prefix 中可用。

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

注意

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

虚拟环境

如果在虚拟环境中运行 Python（如虚拟环境和包中所述），则 prefix 和 exec_prefix 特定于该虚拟环境。

如果在主可执行文件旁边或可执行文件上一级的目录中找到 pyvenv.cfg 文件，则以下变化适用

  • 如果 home 是绝对路径，并且未设置 PYTHONHOME，则在推断 prefix 和 exec_prefix 时，将使用此路径而不是主可执行文件的路径。

_pth 文件

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

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

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

嵌入式 Python

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

另请参阅