如何設定 Python 模組搜尋路徑

我被程式碼海扁姓名標示-非商業-禁改作

閱讀 12:39·字數 3799·更新 2024-4-3

Youtube 頻道
訂閱 480

先決條件

閱讀本節的先決條件是對 Python 模組搜尋路徑有所掌握，你可以檢視Python 模組搜尋路徑介紹，模組搜尋路徑中的目錄有哪些一節來了解相關資訊。

設定 Python 模組搜尋路徑

為了讓需要匯入的模組可以被正確的找到，我們可能要對模組搜尋路徑進行設定，而以下是幾種用於設定模組搜尋路徑的方法。

為何設定模組搜尋路徑後沒有效果？

如果設定模組搜尋路徑沒有效果，那麽原因可能有多種，比如，對環境變數的修改尚不能被 Python 讀取，需要進行重新啟動（比如，重新啟動命令列），或使用_pth檔案覆寫了所有的模組搜尋路徑。

覆寫搜尋路徑

關於_pth檔案的使用，你可以檢視如何使用 _pth 檔案覆寫 Python 模組搜尋路徑一節。

使用 sys.path 設定 Python 模組搜尋路徑

在 Python 啟動後，模組搜尋路徑等同於sys模組的path變數，該變數是一個串列物件，新增目錄至path或刪除path中的目錄，都將影響模組搜尋路徑。

設定 sys.path 對模組搜尋路徑的影響是有限的

需要註意的是，修改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模組的輸出資訊。

set_path.py

# 取得資料夾 plants 的絕對路徑
import os
import sys
plants_path = os.path.abspath('plants')


# 將資料夾 plants 的絕對路徑新增至模組搜尋路徑
sys.path.append(plants_path)


# 直接匯入 plants 中的 tree 模組
import tree

plants/tree.py

print('哦？這是一顆樹？')

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檔案所列出的目錄必須是真實存在的，否則，他們不會被新增至模組搜尋路徑。

pth 檔案允許編寫 Python 程式碼

除了路徑，你還可以在pth檔案中寫入簡單的程式碼，相關聯的程式碼應該保持在同一行，因為不同行的程式碼會被分開執行，多個陳述式之間可以使用;進行分隔。比如，書寫import sys;sys.path.append('custom_lib')會將相對路徑custom_lib新增到sys.path。

如何在 pth 檔案中新增註解？

在一行的開始位置使用#後，該行即成為 pth 檔案的註解。

第三方套件

要了解第三方套件的具體位置，你可以檢視Python 第三方套件的位置一段。

下面名為my.pth的檔案，包含了一個相對路徑，一行註解，以及一行簡單的程式碼。

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。

my.reg

Windows Registry Editor Version 5.00


[HKEY_CURRENT_USER\Software\Python\PythonCore\3.12\PythonPath]
@="C:\\;custom_lib"

Python 模組搜尋路徑中的 zip 檔案路徑

在模組搜尋路徑中，不僅可以包含目錄，還可以包含zip檔案的路徑，這些zip檔案含有自己的目錄結構和模組。因此，你可以將他們視為一種特殊的目錄。

使用之前的檔案tree.py建立壓縮檔案plants.zip，並在add_zip.py中將其絕對路徑新增至模組搜尋路徑（plants.zip和add_zip.py位於同一資料夾），陳述式import tree會匯入plants.zip中的tree模組。

將命令列切換至add_zip.py所在的目錄，然後執行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 模組搜尋路徑中使用相對路徑

模組搜尋路徑允許使用相對路徑，這些相對路徑一般會轉換為絕對路徑（除非直接設定sys.path），在不同的設定方式中，相對路徑所「相對」的目標可能不同。

sys.path 中的相對路徑

對於sys模組的串列變數path，向其新增或其原本包含的任何相對路徑，是指相對於目前工作目錄。

如何檢視 Python 的目前工作目錄？

在互動模式中，輸入import os和os.getcwd()兩行程式碼，將顯示目前工作目錄。如果是py檔案，可以改寫os.getcwd()為print(os.getcwd())。

os 模組的 getcwd 函式

os模組的getcwd函式傳回一個字串，他以絕對路徑的形式表示目前工作目錄。

Windows

import os
os.getcwd()
'…'

UNIX/Linux/macOS

import os
os.getcwd()
'/usr/bin'

print_getcwd.py

# 顯示目前工作目錄
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。

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