ModuleNotFoundError 怎麼解？No module named 五步排查教學

這通常是套件裝到別的 Python，改用 python -m pip 安裝到執行環境，再核對匯入名稱，錯誤就能順利排除。

別擔心，這個錯誤不代表你的程式寫錯，也不代表電腦壞了。它只是 Python 在告訴你：「我找過了，但找不到這個模組。」這篇一次只處理這一件事，照順序檢查五個步驟，就能知道問題卡在哪裡。如果你還沒建立過虛擬環境，後面會用到一點相關知識，可以對照 Python 虛擬環境教學；其他基礎內容在入門教學分類。

No module named 這個錯誤是什麼意思？

完整的錯誤訊息長這樣，引號裡是找不到的模組名稱：

ModuleNotFoundError: No module named 'requests'

Python 官方文件的定義是：當 import 找不到模組時，就會引發 ModuleNotFoundError，它是 ImportError 的子類別，從 Python 3.6 開始加入。

為什麼會找不到？先解釋一個詞：模組搜尋路徑（sys.path）就是 Python 找模組時會去翻的資料夾清單。依官方文件，清單最前面是你的腳本所在的資料夾，之後是標準函式庫，最後才是第三方套件安裝的位置 site-packages。每一個 Python 都有自己的 site-packages，所以套件裝進 A，用 B 執行時，B 當然找不到。

為什麼明明 pip install 了還是找不到？

先看這張表，找到最接近你狀況的那一列：

套件被裝進另一個 Python 環境的示意圖

你看到的狀況	可能原因	解法
終端機裝好了，執行還是報錯	pip 和 python 指向不同的 Python	步驟 1、2
在終端機能跑，在 VS Code 不能跑	VS Code 選到別的解譯器	步驟 3
昨天能跑，今天重開就不行	忘了啟動虛擬環境	步驟 4
安裝的名字和 import 的名字不同	套件名稱不等於模組名稱	步驟 5
Jupyter 裡才出錯	kernel 和安裝用的 Python 不同	常見問題

步驟 1：怎麼確認現在用的是哪一個 Python？

新增一個 check_env.py 檔案，貼上下面三行，然後用平常執行程式的方式執行它：

import sys
print("目前的 Python：", sys.executable)
print("是否在虛擬環境：", sys.prefix != sys.base_prefix)

第一行輸出是 Python 主程式的完整路徑，把它記下來，等一下要比對。第二行顯示 True 表示你在虛擬環境裡，False 表示沒有。

步驟 2：怎麼把套件裝到正確的 Python？

答案是不要直接打 pip，改用「Python 帶著 pip 執行」的寫法。pip 官方說明，python -m pip 會用你指定的那個 Python 來執行 pip，所以安裝位置不會跑掉。以 requests 為例：

# macOS / Linux
python3 -m pip install requests

# Windows
py -m pip install requests

裝完後用 show 確認安裝位置：

# macOS / Linux
python3 -m pip show requests

# Windows
py -m pip show requests

輸出裡的 Location 就是安裝路徑。這個路徑應該和步驟 1 的 Python 屬於同一組。如果看到 WARNING: Package(s) not found: requests，代表這個 Python 真的沒有裝到，重新跑一次安裝指令即可。

注意，這些指令要在終端機輸入，不是在 >>> 提示字元，也不是寫進 .py 檔。如果你看到下面的錯誤，就是打錯地方了：

    pip install requests
        ^^^^^^^
SyntaxError: invalid syntax

步驟 3：VS Code 要怎麼選對解譯器？

解譯器就是實際執行你程式的那個 Python。VS Code 官方文件說明，選定的環境會用於執行、除錯和程式碼提示，所以選錯就會找不到套件。

按 Ctrl+Shift+P（macOS 是 Cmd+Shift+P）打開命令選擇區。
輸入並選擇 Python: Select Interpreter。
從清單選擇步驟 2 安裝套件的那個環境。

也可以直接點視窗下方顯示的 Python 版本來切換。切換後重新執行 check_env.py，確認路徑符合預期。

步驟 4：虛擬環境沒啟動會發生什麼事？

虛擬環境是專案專用的獨立套件空間。官方文件說明，啟動時會把環境的程式資料夾放到 PATH 最前面，所以 python 才會指向環境裡的版本。沒啟動，用的就是系統那一份，當然找不到裝在環境裡的套件。

系統	建立	啟動
macOS / Linux	`python3 -m venv .venv`	`source .venv/bin/activate`
Windows cmd	`py -m venv .venv`	`.venv\Scripts\activate.bat`
Windows PowerShell	`py -m venv .venv`	`.venv\Scripts\Activate.ps1`

如果 PowerShell 不允許執行腳本，官方文件提供的解法是先執行下面這行，它只會調整目前使用者的設定：

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

步驟 5：安裝名稱和 import 名稱不一樣怎麼辦？

這是新手很容易卡住的地方。pip 用的是「發佈名稱」，import 用的是「模組名稱」，兩者不一定相同。常見例子如下：

排除錯誤後繼續練習 Python 的上班族

pip 安裝時寫	程式裡 import 寫
`beautifulsoup4`	`from bs4 import BeautifulSoup`
`Pillow`	`from PIL import Image`
`python-docx`	`from docx import Document`
`pyyaml`	`import yaml`

遇到不確定的套件，查它的官方文件是最快的。Beautiful Soup 的文件也特別提醒，不要安裝名為 BeautifulSoup 的舊套件，那是 Beautiful Soup 3 的版本。

常見問題

Jupyter Notebook 出現同樣錯誤怎麼辦？

Python 打包指南建議在儲存格裡加上 !，並用 {sys.executable} 代替 python，這樣安裝的目標就是目前 kernel 的 Python：

import sys
!{sys.executable} -m pip install requests

終端機說找不到 pip 指令怎麼辦？

先用 python3 -m pip --version（Windows 用 py -m pip --version）檢查。如果 pip 不存在，官方指南提供的做法是執行 python3 -m ensurepip --default-pip，Windows 則是 py -m ensurepip --default-pip。