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

參見