科技 · 實用指南
pip 顯示已安裝卻報 ModuleNotFoundError？先證明 interpreter 與 import path
由失敗 process 確認 Python，核對該 interpreter 可見的 distribution、真正 import name 與 sys.path，再以 clean import 證明。
pip 安裝成功與 import 失敗可同時成立，因為它們可能描述不同 interpreter、名稱或 search path。
由失敗 process 內部開始，把後續 command 綁定到 absolute Python，再證明 metadata、name mapping、path resolution 與 module origin。
先保存失敗 runtime
重跑完整失敗 command，保存 working directory 與 traceback；以同一 launch path 輸出 sys.executable、version、prefix、base_prefix 與 sys.path。Terminal、IDE、notebook、service、shebang 可能各選不同 interpreter。
不要先 sudo pip、--user、改 global PYTHONPATH 或複製 site-packages。第一項證據是 failed process 回報的 absolute executable。
讓該 interpreter 檢查 distribution
用 /absolute/python -m pip show <distribution>，記錄 Name、Version、Location，必要時加 --files。另一個 pip 成功與此 runtime 無關。
若該 interpreter 找不到 distribution，依 lock 安裝到目標環境；若 Location 不在 sys.path，檢查 activation、user site、pyvenv.cfg、service 或 container boundary。
分開 distribution 與 import name
pip 使用 distribution name，import 使用 import package。兩者沒有強制一對一，例如 Pillow 對應 PIL。
核對 project docs 與 installed files，並可在 failing interpreter 查 packages_distributions()。不要用錯 import name 後就判定 install 失敗。
解釋 search path 而非加補丁
Python 由 script/current directory、environment variables、executable landmarks、venv config 與 site processing 建立 sys.path。用 python -m site 記錄 USER_SITE 與 ENABLE_USER_SITE。
service 可能停用 user site，IDE/kernel 可能過期，shebang 可能指向別處。修復最小 launcher boundary，避免 global PYTHONPATH 或隨意 sys.path.append。
排除 shadowing 並要求 exit proof
檢查 project 中同名 file/folder。import 前用 find_spec，成功後記錄 module.__file__，證明沒有 local shadowing。
相同 executable 顯示預期 Location、從預期 path resolve 正確 import、clean process 成功且原 script/test 通過才結案。保存 executable、Location、path、find_spec 與 module file。
