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 路徑配置 中進行了描述。

另請參閱