如何設定 Python 模組搜尋路徑
閱讀 12:43·字數 3819·更新
先決條件
閱讀本節的先決條件是對 Python 模組搜尋路徑有所掌握，你可以檢視Python 模組搜尋路徑介紹，Python 模組搜尋路徑中的目錄有哪些一節來了解相關資訊。
設定 Python 模組搜尋路徑
為了讓需要匯入的模組可以被正確的找到，我們可能要對 Python 模組搜尋路徑進行設定，而以下是幾種用於設定模組搜尋路徑的方法。
為何設定 Python 模組搜尋路徑後沒有效果？
如果設定 Python 模組搜尋路徑沒有效果，那麽原因可能有多種，比如，對環境變數的修改尚不能被 Python 讀取，需要進行重新啟動（比如，重新啟動命令列），或使用_pth檔案覆寫了所有的 Python 模組搜尋路徑。
覆寫搜尋路徑
關於_pth檔案的使用，你可以檢視如何使用 _pth 檔案覆寫 Python 模組搜尋路徑一節。
使用 sys.path 設定 Python 模組搜尋路徑
在 Python 啟動後，模組搜尋路徑等同於sys模組的path變數，該變數是一個串列物件，新增目錄至path或刪除path中的目錄，都將影響模組搜尋路徑。
設定 sys.path 對 Python 模組搜尋路徑的影響是有限的
需要註意的是，修改sys.path所造成的影響，僅對此執行中的 Python 有效。
在腳本檔案set_path.py中，tree.py所在的目錄plants被新增至sys.path（plants與set_path.py處於同一目錄），因此可以直接書寫import tree來匯入模組tree（set_path.py所在的目錄將成為模組搜尋路徑的一部分）。
將命令列切換至set_path.py所在的目錄，然後執行set_path.py，可以看到tree模組的輸出資訊。
# 取得資料夾 plants 的絕對路徑
import os
import sys
plants_path = os.path.abspath('plants')
# 將資料夾 plants 的絕對路徑新增至模組搜尋路徑
sys.path.append(plants_path)
# 直接匯入 plants 中的 tree 模組
import treeprint('哦？這是一顆樹？')Windows
python set_path.py
哦？這是一顆樹？UNIX/Linux/macOS
python3 set_path.py
哦？這是一顆樹？使用環境變數 PYTHONPATH 設定 Python 模組搜尋路徑
設定環境變數PYTHONPATH，將為模組搜尋路徑新增一組目錄，他們可以是相對或絕對路徑。當你希望設定自己的 Python 標準/擴充程式庫時，可以把相關目錄放入PYTHONPATH中。
PYTHONPATH的設定方式類似於環境變數PATH，在 Windows 中采用;分隔多個目錄，在 UNIX/Linux/macOS 中則是:。
變更後的環境變數 PYTHONPATH 可能無法對 Python 立即產生影響
在一般的使用場景中，環境變數PYTHONPATH是由執行 Python 的命令列應用提供的，如果再次啟動 Python 後模組搜尋路徑沒有變化，那麽可能是因為變更尚不能被命令列識別或應用，他為 Python 提供了與之前一樣的PYTHONPATH。
設定環境變數
關於如何設定環境變數，你可以檢視程式設計指南的如何設定 Windows 環境變數，如何設定 UNIX/Linux/macOS 環境變數兩節。
使用 pth 檔案設定 Python 模組搜尋路徑
通過在第三方套件目錄中新增pth檔案，同樣可以為模組搜尋路徑新增目錄，pth檔案對檔案名沒有特殊要求，每個目錄均作為單獨的一行儲存在檔案中，他們可以是相對或絕對路徑。
pth 檔案中列出的目錄需要真實存在
與使用sys.path，環境變數PYTHONPATH以及稍後提到的 Windows 登錄檔不同，pth檔案所列出的目錄必須是真實存在的，否則，他們不會被新增至 Python 模組搜尋路徑。
pth 檔案允許編寫 Python 程式碼
除了路徑，你還可以在pth檔案中寫入簡單的程式碼，相關聯的程式碼應該保持在同一行，因為不同行的程式碼會被分開執行，多個陳述式之間可以使用;進行分隔。比如，書寫import sys;sys.path.append('custom_lib')會將相對路徑custom_lib新增到sys.path。
如何在 pth 檔案中新增註解？
在一行的開始位置使用#後，該行即成為 pth 檔案的註解。
第三方套件
要了解第三方套件的具體位置，你可以檢視Python 第三方套件的位置一段。
下面名為my.pth的檔案，包含了一個相對路徑，一行註解，以及一行簡單的程式碼。
my_modules
# 這是一行註解哦！
import sys;sys.path.append('custom_lib')使用 Windows 登錄檔設定 Python 模組搜尋路徑
如果你在使用 Windows，那麽登錄檔也是設定模組搜尋路徑的途徑之一，登錄檔機碼HKEY_CURRENT_USER\Software\Python\PythonCore\<X>.<Y>\PythonPath，HKEY_LOCAL_MACHINE\Software\Python\PythonCore\<X>.<Y>\PythonPath的預設機碼值應包含相應的目錄，他們可以是相對或絕對路徑，多個目錄之間使用;進行分隔。
上述X為需要設定搜尋路徑的 Python 的主要版本號碼，Y為次要版本號碼。
登錄檔機碼 HKEY_CURRENT_USER 和 HKEY_LOCAL_MACHINE 之間的區別
HKEY_CURRENT_USER中的登錄檔機碼和機碼值針對目前 Windows 使用者，而HKEY_LOCAL_MACHINE中的登錄檔機碼和機碼值適用於所有 Windows 使用者，當然，設定HKEY_LOCAL_MACHINE可能需要相關權限。
無論你選擇設定HKEY_CURRENT_USER還是HKEY_LOCAL_MACHINE，或是兩者皆選，他們包含的目錄均會被新增至對應版本的 Python 的模組搜尋路徑中。
某些版本的 Python 可能不支援通過 Windows 登錄檔設定模組搜尋路徑
對於 Python 3.12 之前的版本，設定 Windows 登錄檔可能無法達到預期效果，但具體結果也可能因為 Windows 系統版本的不同而有所變化。
下面的reg檔案，用於向登錄檔新增機碼HKEY_CURRENT_USER\Software\Python\PythonCore\3.12\PythonPath，其包含的目錄將被新增至 3.12 版本的 Python。
Windows Registry Editor Version 5.00
[HKEY_CURRENT_USER\Software\Python\PythonCore\3.12\PythonPath]
@="C:\\;custom_lib"Python 模組搜尋路徑中的 zip 檔案路徑
在 Python 模組搜尋路徑中，不僅可以包含目錄，還可以包含zip檔案的路徑，這些zip檔案含有自己的目錄結構和 Python 模組。因此，你可以將他們視為一種特殊的目錄。
使用之前的檔案tree.py建立壓縮檔案plants.zip，並在add_zip.py中將其絕對路徑新增至模組搜尋路徑（plants.zip和add_zip.py位於同一資料夾），陳述式import tree會匯入plants.zip中的tree模組。
將命令列切換至add_zip.py所在的目錄，然後執行add_zip.py，將得到與之前一樣的輸出結果。
# 取得壓縮檔案 plants.zip 的絕對路徑
import os
import sys
zip_path = os.path.abspath('plants.zip')
# 將 plants.zip 的絕對路徑新增至模組搜尋路徑
sys.path.append(zip_path)
# 匯入 plants.zip 中的 tree 模組
import tree在 Python 模組搜尋路徑中使用相對路徑
Python 模組搜尋路徑允許使用相對路徑，這些相對路徑一般會轉換為絕對路徑（除非直接設定sys.path），在不同的設定方式中，相對路徑所“相對”的目標可能不同。
Python sys.path 中的相對路徑
對於sys模組的串列變數path，向其新增或其原本包含的任何相對路徑，是指相對於目前工作目錄。
如何檢視 Python 的目前工作目錄？
在 Python 的互動模式中，輸入import os和os.getcwd()兩行程式碼，將顯示目前工作目錄。如果是py檔案，可以改寫os.getcwd()為print(os.getcwd())。
Python os 模組的 getcwd 函式
os模組的getcwd函式傳回一個字串，他以絕對路徑的形式表示目前工作目錄。
Windows
import os
os.getcwd()
'…'UNIX/Linux/macOS
import os
os.getcwd()
'/usr/bin'# 顯示目前工作目錄
import os
print(os.getcwd())PYTHONPATH 環境變數中的相對路徑
對於環境變數PYTHONPATH中的相對路徑，同樣是相對於 Python 的目前目錄，但在新增至sys.path時，他們將被轉換為等價的絕對路徑。
假設 Windows 存在環境變數PYTHONPATH，其值為custom_lib\hello;system_lib，目前工作目錄為C:\，那麽sys.path將包含C:\custom_lib\hello和C:\system_lib。
Python pth 檔案中的相對路徑
需要註意，pth檔案中包含的相對路徑，是相對於該檔案所在的目錄，而非 Python 的目前工作目錄。在被新增至sys.path時，他們會轉換為等價的絕對路徑。
假設 Windows 中 Python 的第三方套件目錄為C:\python\Lib\site-packages，該目錄擁有檔案my.pth並包含相對路徑custom_lib\hello和system_lib，那麽常規啟動後，sys.path將包含C:\python\Lib\site-packages\custom_lib\hello和C:\python\Lib\site-packages\system_lib。
Windows 登錄檔中的相對路徑
在 Windows 系統中，登錄檔機碼HKEY_CURRENT_USER\Software\Python\PythonCore\<X>.<Y>\PythonPath，HKEY_LOCAL_MACHINE\Software\Python\PythonCore\<X>.<Y>\PythonPath中的相對路徑，與環境變數PYTHONPATH中的相對路徑類似，他們相對於目前工作目錄，並在新增至sys.path時被轉換為絕對路徑。
上述X為 Python 主要版本號碼，Y為次要版本號碼。
程式碼
set_path.py·codebeatme/python-reference·GitHub
plants/tree.py·codebeatme/python-reference·GitHub
my.pth·codebeatme/python-reference·GitHub
my.reg·codebeatme/python-reference·GitHub
add_zip.py·codebeatme/python-reference·GitHub
print_getcwd.py·codebeatme/python-reference·GitHub