Python 路徑設定與確認完整指南｜錯誤排除與實用技巧彙整

By 佐川 直弘 | Naohiro Sagawa (運営者)

※記事内に広告を含みます。Amazonアソシエイトとして適格販売により収入を得ています。

1. 前言

1.1 為什麼需要設定 Python 的路徑？

在建立 Python 開發環境時，「確認與設定路徑」是不可或缺的重要步驟，能讓開發作業更加順暢。若未正確設定模組或函式庫的路徑，可能會導致錯誤發生。

本文將從 Python 路徑的基本知識開始，詳細介紹確認方式、設定步驟與故障排除方法。內容簡單易懂，適合從初學者到中階使用者閱讀。

1.2 文章的目標讀者與目的

本指南適合以下讀者：

• 想學習 Python 環境基本設定的初學者
• 希望了解路徑設定問題與最佳化的中階使用者
• 在工作或專案中使用 Python，需要有效管理路徑的人

透過本文，您將學會從基礎到進階的 Python 路徑設定知識，提升開發環境的效率。

2. 什麼是 Python 的「路徑」？

2.1 路徑的基本概念

2.1.1 什麼是路徑？

「路徑」是指檔案或資料夾在電腦中的位置資訊。在 Python 中，當我們要匯入某個程式檔或模組時，Python 會依照設定好的路徑來尋找該檔案。

例如，以下程式碼會匯入標準函式庫中的「os」模組：

import os

這時 Python 就會在系統中搜尋「os」模組的位置。這段搜尋的流程稱為「模組搜尋路徑」。

2.1.2 絕對路徑與相對路徑

在指定檔案或資料夾時，Python 支援兩種寫法：「絕對路徑」與「相對路徑」。

• 絕對路徑：從系統的根目錄開始指定的完整路徑。
  例：/usr/local/bin/python3 或 C:Python39python.exe
• 相對路徑：以目前的工作目錄為基準的路徑。
  例：./scripts/myscript.py 或 ../config/settings.py

範例：確認檔案路徑的程式碼

import os

# 取得目前的工作目錄
print(os.getcwd())

# 將相對路徑轉換為絕對路徑
relative_path = './test/example.py'
absolute_path = os.path.abspath(relative_path)
print(absolute_path)

2.2 路徑的作用

2.2.1 模組搜尋的流程

當 Python 匯入模組時，會依照以下順序進行搜尋：

1. 目前的工作目錄 – 優先搜尋執行中的程式所在的資料夾。
2. 環境變數 PYTHONPATH – 搜尋使用者手動加入的自訂路徑。
3. 標準函式庫資料夾 – 搜尋 Python 預設的標準函式庫。
4. site-packages 資料夾 – 搜尋透過 pip install 安裝的第三方套件。

可使用以下程式碼來查看這些搜尋路徑：

import sys
print(sys.path)

2.2.2 使用 sys.path 控制搜尋順序

sys.path 是一個可以自訂的清單，列出了 Python 搜尋模組的順序。

以下是臨時新增路徑的範例：

import sys
sys.path.append('/custom/path/to/module')

import mymodule  # 匯入自訂模組

透過這種方式，我們可以輕鬆地讓 Python 尋找專案中的自訂模組。

3. 如何確認 Python 的路徑

3.1 使用命令列確認

透過命令列可以輕鬆地查看 Python 的模組搜尋路徑。請依照以下步驟進行：

步驟1：執行指令

在終端機或命令提示字元中輸入以下指令：

python -c "import sys; print(sys.path)"

步驟2：確認輸出結果

執行後，會顯示類似下列的輸出結果：

['',
 '/usr/lib/python3.9',
 '/usr/lib/python3.9/lib-dynload',
 '/home/user/.local/lib/python3.9/site-packages',
 '/usr/local/lib/python3.9/dist-packages']

這個清單表示 Python 搜尋模組時的順序，會依照列表的先後依序搜尋。

3.2 在程式中確認

也可以直接在 Python 程式碼中確認目前的搜尋路徑。這種方法適合在開發或除錯時使用。

範例1：列出目前所有路徑

import sys
for path in sys.path:
    print(path)

執行後會逐行列出所有目前的模組搜尋路徑。

範例2：確認特定路徑是否存在

import sys
path_to_check = '/home/user/myproject'
if path_to_check in sys.path:
    print("Path is included.")
else:
    print("Path is not included.")

3.3 在 IDE 中確認

開發時常會使用 IDE（整合式開發環境）。以下說明如何在 Visual Studio Code 和 PyCharm 中確認路徑。

在 Visual Studio Code 中

1. 開啟終端機（快捷鍵 Ctrl + Shift + `）。
2. 輸入以下指令：

python -c "import sys; print(sys.path)"

3. 查看輸出結果以確認路徑設定。

在 PyCharm 中

1. 從選單中選擇「Settings」。
2. 開啟「Project Interpreter」。
3. 會顯示目前解譯器參考的路徑列表。
4. 可以根據需求新增自訂路徑。

4. 設定與確認環境變數 PATH

4.1 什麼是 PATH？

PATH 環境變數的基本概念

PATH 是系統用來記錄可執行檔所在資料夾的環境變數。當你在終端機或程式中執行指令時，系統會根據 PATH 指定的位置來尋找執行檔。

Python 與 PATH 的關係

如果 Python 的安裝路徑已加入 PATH，便可以直接使用以下指令來查看版本：

python --version

如果 PATH 未正確設定，會出現類似以下錯誤訊息：

'python' 不是內部或外部命令，也不是可執行的程式或批次檔。

為了解決這個問題，需要正確設定 PATH 環境變數。

4.2 在 Windows 中設定 PATH

在 Windows 中可以透過控制台或系統設定來編輯環境變數。

步驟1：開啟環境變數設定畫面

1. 在搜尋欄輸入「環境變數」，點選「檢視系統進階設定」。
2. 在出現的「系統內容」視窗中，點選「環境變數」。

步驟2：編輯 PATH 變數

1. 從「使用者變數」或「系統變數」中選擇「Path」，然後點選「編輯」。
2. 點選「新增」來加入新的路徑。
3. 輸入 Python 的安裝路徑（例如：C:Python39）。
4. 儲存設定並關閉所有對話框。

步驟3：確認設定結果

開啟命令提示字元並執行以下指令：

python --version

若正確顯示版本號，代表設定成功。

4.3 在 Mac/Linux 中設定 PATH

在 macOS 或 Linux 系統中，可透過終端機設定 PATH 環境變數。

步驟1：查看目前 PATH

在終端機輸入以下指令：

echo $PATH

會顯示目前系統已設定的 PATH 清單。

步驟2：暫時加入 PATH

可使用以下指令暫時加入一個路徑：

export PATH=$PATH:/usr/local/bin/python3

這個設定在終端機關閉後會失效。

步驟3：永久加入 PATH

若想讓設定永久生效，需編輯 shell 設定檔。

1. 開啟設定檔（例如使用 bash 的話）：

nano ~/.bashrc

2. 在檔案底部新增以下內容：

export PATH=$PATH:/usr/local/bin/python3

3. 儲存並關閉檔案（Ctrl + X → Y → Enter）。
4. 執行以下指令以套用設定：

source ~/.bashrc

步驟4：確認設定是否生效

可使用以下指令確認 Python 的路徑：

which python

如果輸出結果中包含您指定的目錄，代表 PATH 設定已生效。

5. 如何新增模組搜尋路徑

5.1 暫時新增

為什麼要暫時新增路徑？

當你只希望在程式執行期間內使用某個路徑，可以選擇暫時新增。此方法的設定在程式結束後會被重置。

使用 sys.path.append() 的方法

以下是程式內新增搜尋路徑的範例：

import sys
sys.path.append('/path/to/custom/module')

import mymodule  # 匯入自訂模組

重點說明：

• sys.path.append() 會將指定路徑加入搜尋清單的最後面。
• 此設定僅在目前的程式執行期間有效，程式結束後會失效。

注意事項

1. 請事先確認模組已正確放置在對應的資料夾中。
2. 暫時新增僅對當前執行的程式有效，重新執行時需重新設定。

5.2 永久新增

為什麼需要永久新增路徑？

如果你經常使用某些模組或函式庫，建議透過環境變數或設定檔來進行永久新增，提升效率。

使用 PYTHONPATH 環境變數的方法

Windows 的設定方法

1. 打開系統的環境變數設定畫面。
2. 新增名為「PYTHONPATH」的變數，並設定值為你想要加入的路徑：

C:pathtocustommodule

3. 儲存後，重啟命令提示字元以套用設定。

Mac/Linux 的設定方法

1. 編輯 Shell 的設定檔（例如：~/.bashrc 或 ~/.zshrc）。
2. 新增以下內容：

export PYTHONPATH=$PYTHONPATH:/path/to/custom/module

3. 儲存後執行以下指令使設定生效：

source ~/.bashrc

5.3 使用 .pth 檔案新增

什麼是 .pth 檔案？

.pth 檔案是 Python 在啟動時會讀取的設定檔。透過它可以簡單地新增搜尋路徑。

設定步驟

1. 打開 Python 安裝資料夾中的 site-packages 資料夾：

/usr/local/lib/python3.9/site-packages/

2. 建立一個新的 .pth 檔案，例如：

mymodule.pth

3. 在檔案中寫入要新增的路徑：

/path/to/custom/module

4. 儲存後重新啟動 Python 以確認設定是否生效。

確認方法

import sys
print(sys.path)

如果輸出的路徑清單中有你新增的資料夾，代表設定成功。

6. 疑難排解（Troubleshooting）

6.1 無法找到模組時的對應方法

在使用 Python 時，可能會遇到如下錯誤：

ModuleNotFoundError: No module named 'mymodule'

原因1：模組尚未安裝

這個錯誤常見於尚未安裝指定模組的情況。

解決方法：安裝所需模組

pip install mymodule

可透過以下指令確認模組是否已安裝：

pip show mymodule

原因2：路徑未正確設定

若模組已安裝仍出現錯誤，可能是因為搜尋路徑設定不當。

解決方法1：確認 PYTHONPATH 是否正確設定

echo $PYTHONPATH  # 對應 Linux/Mac
echo %PYTHONPATH%  # 對應 Windows

解決方法2：使用程式中暫時新增路徑

import sys
sys.path.append('/path/to/mymodule')

6.2 Python 無法啟動時的解決方式

錯誤範例：’python’ 不是內部或外部命令

這種錯誤通常是因為 Python 未安裝或 PATH 設定不正確所致。

解決方法：確認並修正 PATH 設定

Windows 的方法

1. 開啟命令提示字元。
2. 輸入以下指令檢視目前 PATH：

echo %PATH%

3. 新增 Python 安裝目錄（例如：C:Python39）。

Mac/Linux 的方法

echo $PATH

若有需要可新增設定：

export PATH=$PATH:/usr/local/bin/python3

6.3 與虛擬環境相關的錯誤

錯誤範例：模組在虛擬環境中無法使用

使用虛擬環境時，模組若未安裝在該環境中將無法匯入。

解決方法：確認虛擬環境已啟用

source venv/bin/activate  # 對應 Linux/Mac
venv\Scripts\activate     # 對應 Windows

在虛擬環境中重新安裝模組：

pip install -r requirements.txt

6.4 與 Python 版本管理有關的問題

當系統中安裝了多個 Python 版本時，可能會因為版本混淆導致錯誤。

解決方法1：確認當前版本

python --version
which python   # Linux/Mac
where python   # Windows

解決方法2：指定版本執行

python3.9 myscript.py

解決方法3：使用版本管理工具

可透過 pyenv 等工具靈活切換 Python 版本。

安裝範例：

curl https://pyenv.run | bash

指定版本範例：

pyenv global 3.9.7

7. 常見問題（FAQ）

Q1: 最簡單的方法來確認 Python 的路徑是什麼？

回答：
最簡單的方法是在終端機或命令提示字元中輸入以下指令：

python -c "import sys; print(sys.path)"

若要在程式中確認，也可以使用以下程式碼：

import sys
print(sys.path)

Q2: 如果錯誤設定了 PATH 環境變數，要怎麼重設？

回答：
如果不小心設定錯誤，可以依下列步驟重設 PATH。

Windows 的方法

1. 打開控制台並選擇「系統進階設定」。
2. 點選「環境變數」。
3. 將編輯過的 PATH 恢復原本的值，或新增正確的路徑。

Mac/Linux 的方法
開啟終端機並編輯設定檔（例如：.bashrc 或 .zshrc）：

nano ~/.bashrc

刪除錯誤的設定並加入正確的 PATH：

export PATH=$PATH:/usr/local/bin/python3

儲存檔案後，執行以下指令套用變更：

source ~/.bashrc

Q3: 為什麼特定模組無法匯入？

回答：
可能原因如下：

1. 模組尚未安裝

• 使用以下指令確認模組是否已安裝：
  pip show module_name
• 若尚未安裝，可透過以下指令安裝：
  pip install module_name

1. 環境變數或虛擬環境設定錯誤

• 確認虛擬環境是否已啟動：
  source venv/bin/activate # Linux/Mac
venv\Scripts\activate # Windows

1. 路徑設定不正確

• 使用 sys.path 查看目前的路徑設定：
  import sys
print(sys.path)
• 必要時可透過以下方式加入路徑：
  sys.path.append('/path/to/module')

Q4: 在虛擬環境中如何設定路徑？

回答：
使用虛擬環境時，可以針對每個專案管理獨立的模組與路徑。請依以下步驟操作：

1. 建立虛擬環境：

python -m venv myenv

2. 啟用虛擬環境：
   Windows：

myenv\Scripts\activate

Mac/Linux：

source myenv/bin/activate

3. 安裝所需模組：

pip install module_name

4. 確認虛擬環境內的路徑設定：

import sys
print(sys.path)

5. 若要離開虛擬環境，請執行：

deactivate

8. 結語

8.1 重點回顧

1. 什麼是 Python 的路徑？

• Python 使用路徑來尋找模組與函式庫。
• 理解絕對路徑與相對路徑的差異，有助於有效管理檔案。

2. 確認路徑的方法

• 可透過命令列、程式內或 IDE 來快速檢查。
• 也可以設定 PYTHONPATH 來管理自訂模組。

3. 設定與確認 PATH 環境變數

• 提供 Windows、Mac、Linux 各自對應的設定教學。
• 也說明了如何檢查與修正錯誤設定。

4. 新增模組搜尋路徑

• 可使用 sys.path.append() 進行暫時新增。
• 永久新增可透過 PYTHONPATH 或 .pth 檔案。

5. 疑難排解

• 提供模組錯誤、Python 無法啟動等問題的具體解法。
• 也涵蓋了虛擬環境與多版本管理的對應方式。

6. 常見問題（FAQ）

• 整理 PATH 設定、虛擬環境與模組錯誤等常見問題的快速解答。

8.2 未來應用建議

1. 標準化開發環境
   建議為團隊或專案建立統一的設定，並記錄於文件中，以提升效率。
2. 善用虛擬環境
   使用虛擬環境可避免依賴衝突，保持環境乾淨。
3. 導入版本管理工具
   透過 pyenv 等工具靈活管理多版本 Python，為不同專案建立最佳環境。

8.3 給讀者的行動建議

1. 檢查自己的環境

• 參考本文的操作步驟，確認 PATH 與模組搜尋設定是否正確。
• 刪除不必要的路徑，並新增實際需要的目錄。

1. 備份你的設定

• 修改環境變數或設定檔前請先備份，以利錯誤時還原。

1. 持續學習與應用

• 透過官方文件與社群資源，隨時更新相關知識。
• 實際操作中逐漸建立符合自身需求的最佳實踐。

總結

本文介紹了 Python 路徑的確認與設定方法，從基礎到進階內容一應俱全，對初學者與中階使用者皆有實用價值。希望透過這篇文章，能幫助你更順利地建立與管理 Python 的開發環境。

未來在使用 Python 開發專案時，也歡迎將此文章作為故障排除與環境設定的參考資源。

9. 相關連結與參考資料

9.1 官方文件

1. Python 官方文件

• Python 官方文件：sys 模組
• 詳細說明如何使用 sys 模組來管理系統設定與模組搜尋路徑。
• Python 官方文件：os 模組
• 說明如何操作檔案系統與環境變數。

2. 環境變數與 PATH 設定官方指南

• Python 官方指南：環境變數設定
• 介紹環境變數設定方式與可用選項。

9.2 社群與支援資源

1. Stack Overflow

• Python 相關問題與解答
• 可搜尋實際錯誤案例與社群提供的解決方案。

2. GitHub 儲存庫

• Python 環境設定範例儲存庫
• 參考實際的程式碼範例，學習設定技巧。

3. 日本語社群

• teratail
• 提供日語問題與解答的平台。

9.3 工具與擴充功能

1. pyenv

• pyenv GitHub 儲存庫
• 一個簡單管理多版本 Python 的工具。

2. pipenv

• pipenv GitHub 儲存庫
• 協助管理相依性與虛擬環境的工具。

3. Visual Studio Code 擴充功能

• Python 擴充套件：Python Extension for Visual Studio Code
• 提升 IDE 功能，方便管理 Python 路徑與虛擬環境。

總結

本章介紹了與 Python 開發環境與路徑管理相關的實用資源：

1. 使用官方文件建立穩固基礎知識。
2. 透過社群與論壇尋找實際解法。
3. 活用工具與擴充功能，提升工作效率。

善用這些資源，你將能更有效地掌握 Python 的開發與環境管理技巧。