前兩天給一個(gè)量化回測(cè)項(xiàng)目裝依賴pip install 一跑又撞上了 ModuleNotFoundError: No module named numba。這已經(jīng)不是我第一次和這個(gè)報(bào)錯(cuò)打交道了之前幫同事排查音頻處理庫(kù)的安裝問(wèn)題、給開源項(xiàng)目補(bǔ)環(huán)境時(shí)都在這一步卡過(guò)。網(wǎng)上搜這個(gè)報(bào)錯(cuò)能翻出一大堆相似癥狀但真正原因各異的帖子有人裝上了也不解決問(wèn)題有人把 Python 卸了重裝最后發(fā)現(xiàn)只是環(huán)境錯(cuò)位。這篇我想把這個(gè)問(wèn)題徹底講透報(bào)錯(cuò)是怎么產(chǎn)生的、動(dòng)手前該做什么檢查、有哪些修復(fù)路徑、每一步的命令和原理是什么最后附上我踩過(guò)的一些坑。新手可以直接照著操作老手也能用來(lái)對(duì)照排查思路有沒(méi)有遺漏。1. 先別急著執(zhí)行 pip install numba搞懂這個(gè)報(bào)錯(cuò)是怎么觸發(fā)的1.1 三個(gè)典型報(bào)錯(cuò)現(xiàn)場(chǎng)你對(duì)號(hào)入座現(xiàn)場(chǎng)一僵在半路的安裝日志你執(zhí)行的是 pip install 某個(gè)包比如 librosa、resampy或者一個(gè)依賴矩陣運(yùn)算的量化框架。requirements.txt 里的包很多pip 在解析依賴時(shí)會(huì)先構(gòu)建完整的依賴圖其中某個(gè)包聲明了 numba 依賴。如果 numba 或者它的核心依賴 llvmlite 在安裝過(guò)程中下載失敗、編譯失敗pip 會(huì)直接中斷整個(gè)安裝流程這時(shí)候終端里可能只留下一個(gè)籠統(tǒng)的報(bào)錯(cuò)甚至沒(méi)有異常信息只是最后一個(gè)包沒(méi)裝上。等你轉(zhuǎn)頭 import就開始炸。這種情況最容易讓人誤判因?yàn)槠聊簧峡赡芸床坏?numba 三個(gè)字你甚至?xí)詾槭蔷W(wǎng)絡(luò)問(wèn)題或者磁盤問(wèn)題。實(shí)際上pip 默認(rèn)會(huì)把已經(jīng)下載好的輪子緩存起來(lái)中斷之后重新執(zhí)行同樣的命令它會(huì)從緩存繼續(xù)但如果你不清理也可能因?yàn)榫彺鎿p壞而反復(fù)失敗?，F(xiàn)場(chǎng)二import 階段的精確報(bào)錯(cuò)更多時(shí)候報(bào)錯(cuò)出現(xiàn)在你運(yùn)行腳本的那一刻Traceback (most recent call last): File test.py, line 1, in module import some_lib File /path/to/some_lib/__init__.py, line 3, in module from numba import njit ModuleNotFoundError: No module named numba注意這里的關(guān)鍵信息是 traceback 最后一行的ModuleNotFoundError。它說(shuō)明 Python 解釋器在執(zhí)行 import 語(yǔ)句時(shí)沿著 sys.path 里所有目錄找了一遍都沒(méi)有找到名為 numba 的模塊目錄。這個(gè)報(bào)錯(cuò)本身非常直白但導(dǎo)致它出現(xiàn)的原因可以有很多層——可能是沒(méi)裝上可能是裝到了另一個(gè)環(huán)境也可能是裝上了但當(dāng)前 Python 版本加載不了它的二進(jìn)制擴(kuò)展?，F(xiàn)場(chǎng)三明明裝過(guò)卻還是報(bào)錯(cuò)還有一種情況讓人非常崩潰你敲了 pip install numba終端顯示 Successfully installed numba-0.x.x但一運(yùn)行還是同樣的報(bào)錯(cuò)。這種裝了等于沒(méi)裝的反差十有八九是環(huán)境錯(cuò)位——pip 把包裝到了 A 環(huán)境的 site-packages而你當(dāng)前執(zhí)行 python 命令用的解釋器是 B 環(huán)境或者你同時(shí)裝有 Python 3.9 和 3.12pip install 默認(rèn)走的是 PATH 里靠前的那個(gè)而你的 IDE 用的是另一個(gè)。遇到這類情況檢查環(huán)境優(yōu)先級(jí)比盲目重裝重要得多。1.2 numba 不是普通包麻煩從名字就開始了Python 里大部分包是純 Python 或者只有少量 C 擴(kuò)展numba 完全不同。它的工作方式是把 Python 函數(shù)通過(guò) LLVM 編譯器實(shí)時(shí)編譯成機(jī)器碼追求接近 C 的性能?？梢园?numba 的工作方式理解成一個(gè)運(yùn)行時(shí)翻譯官你定義了一個(gè)普通的 Python 函數(shù)加上 njit 裝飾器后numba 會(huì)把它交給底層的 llvmlitellvmlite 再調(diào)用 LLVM 將函數(shù)編譯成機(jī)器碼之后每次調(diào)用都直接執(zhí)行機(jī)器碼所以能跑到接近 C 的速度。這個(gè)機(jī)制聽起來(lái)很舒服但代價(jià)就是對(duì)運(yùn)行環(huán)境極其敏感——機(jī)器碼綁定特定處理器指令集、Python ABI 和 numpy 版本任何一環(huán)對(duì)不上都沒(méi)法用。具體到安裝和運(yùn)行它有三個(gè)天然雷區(qū)第一它依賴一個(gè)底層庫(kù) llvmlite這是 LLVM 的 Python 綁定。安裝時(shí)如果沒(méi)有找到對(duì)應(yīng)平臺(tái)和 Python 版本的預(yù)編譯輪子pip 會(huì)嘗試從源碼編譯一旦你缺 C/C 編譯工具鏈編譯就失敗。第二它和 numpy 的 C API 綁定得非常深numpy 大版本升級(jí)時(shí) numba 往往跟不上比如 numpy 2.0 發(fā)布后所有 0.57 及更早版本的 numba 直接無(wú)法使用。第三它對(duì) Python 版本的支持有滯后性Python 3.12、3.13 這類新版本發(fā)布后numba 官方通常要隔一段時(shí)間才能發(fā)布兼容版本。所以你看到的 ModuleNotFoundError: No module named numba可能只是浮在水面上的冰山一角。水底下的真實(shí)原因可能是 llvmlite 編譯失敗、numpy 版本撞車、Python 版本不被支持、輪子下載不到甚至只是環(huán)境路徑?jīng)]對(duì)上。要修復(fù)這個(gè)報(bào)錯(cuò)第一步不是重裝 numba而是先做一次環(huán)境體檢。2. 修復(fù)前的環(huán)境體檢四條命令定位問(wèn)題在動(dòng)手裝包之前花兩分鐘搞清楚自己當(dāng)前在哪個(gè)環(huán)境、pip 歸誰(shuí)管、已有依賴是什么版本這能幫你避開 80% 的無(wú)效操作。2.1 確認(rèn)當(dāng)前 Python 解釋器是誰(shuí)首先執(zhí)行python --version如果系統(tǒng)里有多個(gè) Python這個(gè)命令顯示的未必是你要用的版本。更準(zhǔn)確的做法是看路徑Windowswhere pythonmacOS/Linuxwhich -a python python3我見過(guò)很多次這樣的情況用戶在 VSCode 右下角選了解釋器是 Python 3.12但是命令行窗口里敲 pip install 時(shí)用的卻是另一個(gè) Python 3.10。所以先確認(rèn)你準(zhǔn)備用哪個(gè)解釋器跑代碼然后用同一個(gè)解釋器去裝包。最穩(wěn)妥的方式是用python -m pip而不是裸pippython -m pip --version這樣可以確保 pip 一定屬于當(dāng)前這個(gè) python 解釋器。這一步做完了環(huán)境至少不會(huì)在解釋器和 pip 分家這個(gè)維度上坑你。2.2 檢查 pip 的安裝目標(biāo)和權(quán)限執(zhí)行安裝時(shí)如果看到這句話Defaulting to user installation because normal site-packages is not writeable說(shuō)明當(dāng)前環(huán)境是系統(tǒng)級(jí) Python 或者某個(gè)沒(méi)有寫權(quán)限的環(huán)境pip 把包裝到了用戶目錄Windows 下是%APPDATA%\PythonLinux/macOS 下是~/.local/lib/python3.x/site-packages。這個(gè)位置在 sys.path 里通常存在所以不一定會(huì)導(dǎo)致找不到模塊但如果你同時(shí)用 sudo 裝過(guò)包到系統(tǒng) site-packages或者 IDE 啟動(dòng)時(shí)沒(méi)有加載用戶 site-packages就可能出現(xiàn)裝了但找不到的情況。看到這個(gè)提示時(shí)最好直接創(chuàng)建一個(gè)虛擬環(huán)境而不是繼續(xù)往用戶目錄里堆依賴。虛擬環(huán)境創(chuàng)建方式python -m venv .venvWindows 激活.venv\Scripts\activatemacOS/Linux 激活source .venv/bin/activate激活后命令提示符前面會(huì)出現(xiàn)(.venv)這時(shí)候 pip install 裝的包都會(huì)進(jìn)入這個(gè)環(huán)境路徑問(wèn)題一次性解決。別嫌這一步麻煩虛擬環(huán)境建立的隔離層可以讓你隨意組合 Python 版本和包版本而不污染系統(tǒng)環(huán)境。2.3 檢查 numba、numpy、llvmlite 的現(xiàn)狀接下來(lái)看看關(guān)鍵包是不是已經(jīng)在環(huán)境里pip list | findstr numba # Windows pip list | grep -i numba # macOS/Linux或者直接用 Python 自己查python -c import numba; print(numba.__version__)如果 import 成功說(shuō)明 numba 已經(jīng)裝上了。如果 import 報(bào)錯(cuò)再查 numpypython -c import numpy; print(numpy.__version__)為什么先查 numpy因?yàn)?numba 0.57 及之前不支持 numpy 2.x如果你環(huán)境里的 numpy 是 2.x而 numba 是 0.57那么 import 階段就會(huì)出現(xiàn)各種奇怪的問(wèn)題。這類問(wèn)題在報(bào)錯(cuò)信息里不一定直接寫 numpy往往就是讓你去查 numba。所以裝 numba 前先讓 numpy 回到 1.x或者把 numba 升到 0.58 以上二選一視項(xiàng)目約束而定。還需要確認(rèn) llvmlite 是否可用python -c import llvmlite; print(llvmlite.__version__)如果 llvmlite 這一行也報(bào) ModuleNotFoundError問(wèn)題就更清晰了整條依賴鏈從底層就斷了。這時(shí)候可以跳到后面的方案 C 或方案 E。3. 五種修復(fù)路徑按優(yōu)先級(jí)從上往下試3.1 方案 A直接補(bǔ)裝 numba帶鏡像加速和升級(jí)提示如果你確實(shí)沒(méi)裝過(guò) numba最直接的修復(fù)就是python -m pip install numba第一次裝的時(shí)候pip 會(huì)把 numba 以及它的依賴 llvmlite、numpy 一起處理。如果網(wǎng)絡(luò)比較慢或者你發(fā)現(xiàn) PyPI 官方源下載超時(shí)可以加一個(gè)鏡像源國(guó)內(nèi)常用的清華鏡像python -m pip install numba -i https://pypi.tuna.tsinghua.edu.cn/simple這里有個(gè)細(xì)節(jié)用-i只是臨時(shí)指定這一次安裝的源不會(huì)修改全局配置比較干凈。如果你希望長(zhǎng)期使用鏡像可以用pip config set global.index-url配置但我不太建議在公共機(jī)器上改全局配置因?yàn)闀?huì)影響其他項(xiàng)目。裝完之后先驗(yàn)證一下python -c import numba; print(numba.__version__)如果順利輸出版本號(hào)那這個(gè)報(bào)錯(cuò)就算解決了。如果安裝過(guò)程中報(bào)了一個(gè)和 llvmlite 相關(guān)的錯(cuò)誤先別急著換方案往下看方案 C。3.2 方案 B鎖定 numpy 版本清理兼容性雷區(qū)執(zhí)行完方案 A 之后如果 import numba 還是失敗但你已經(jīng)確認(rèn) numba 在 pip list 里那么下一個(gè)懷疑對(duì)象就是 numpy。檢查一下python -c import numpy; print(numpy.__version__)如果你看到 2.x并且你用到的是比較老的 numba0.57 或更早這就是雷。處理方法有兩種取決于項(xiàng)目依賴怎么寫如果你其他包都還兼容 numpy 1.x直接降 numpypython -m pip install numpy2.0如果某些包已經(jīng)依賴 numpy 2.x那就升 numbapython -m pip install --upgrade numba第二種方式更符合趨勢(shì)因?yàn)槔习姹具t早要淘汰但前提是 numba 新版本支持你的 Python 版本。所以在動(dòng)手之前去 PyPI 上查一下 numba 的 Release history 和 Requires-Python 字段確認(rèn)當(dāng)前 Python 在支持范圍內(nèi)。這里我想強(qiáng)調(diào)一個(gè)容易忽略的點(diǎn)numpy 不是隨便降的。一個(gè)大型項(xiàng)目里可能十幾個(gè)包都依賴 numpy你手動(dòng)把 numpy 降到 1.26可能讓另一個(gè)包直接炸掉。所以降 numpy 之前先看看 requirements.txt 里有沒(méi)有硬性要求比如numpy2.0。如果有那你只能升 numba而不是降 numpy。3.3 方案 C解決 llvmlite 安裝失敗的核心問(wèn)題很多第一次遇到 numba 報(bào)錯(cuò)的新手真正卡死的地方是 llvmlite——這是 numba 的底層依賴負(fù)責(zé)把 Python 函數(shù)轉(zhuǎn)成 LLVM 中間表示。llvmlite 安裝失敗的時(shí)候報(bào)錯(cuò)信息通常長(zhǎng)這樣Windows 上error: Microsoft Visual C 14.0 or greater is required. Get it with Microsoft C Build ToolsLinux 上fatal error: llvm-config: command not found這表示當(dāng)前 pip 找不到現(xiàn)成的輪子它在嘗試從源碼編譯。編譯 llvmlite 需要完整的 LLVM 開發(fā)環(huán)境對(duì)絕大多數(shù)人來(lái)說(shuō)并不劃算。我的建議是優(yōu)先讓 pip 找到預(yù)編譯輪子方法很樸素先把 pip 升到最新版因?yàn)樾掳?pip 會(huì)識(shí)別更新的輪子標(biāo)記python -m pip install --upgrade pip wheel setuptools然后重新執(zhí)行python -m pip install llvmlite如果還是走源碼編譯再考慮裝 C Build ToolsWindows或者系統(tǒng)編譯依賴Linux 上apt install build-essential llvm之類。但說(shuō)真的如果你已經(jīng)走到了要編譯 LLVM 這一步我建議直接跳到方案 E 用 conda十分鐘配好一個(gè)帶 numba 的環(huán)境省下的時(shí)間遠(yuǎn)超裝編譯工具的時(shí)間。3.4 方案 D換 Python 版本或建立隔離環(huán)境當(dāng)你發(fā)現(xiàn) numba 官方明確不支持你當(dāng)前的 Python 大版本時(shí)不要硬剛。numba 對(duì) Python 新版本的支持總是慢半拍比如 Python 3.13 剛發(fā)布的時(shí)候一堆人安裝失敗。此時(shí)正確的操作是另建一個(gè)虛擬環(huán)境然后選一個(gè) numba 明確支持的 Python 版本通常 3.10 和 3.11 是兼容性最穩(wěn)的區(qū)段。如果你用 pyenv 管理 Pythonpyenv install 3.10.14 pyenv local 3.10.14 python -m venv .venv source .venv/bin/activate然后在這個(gè)環(huán)境里重新安裝項(xiàng)目依賴。這一步的本質(zhì)是讓 numba 的預(yù)編譯輪子能匹配到你的平臺(tái)和 Python ABI而不是硬著頭皮編譯。虛擬環(huán)境的好處還在于你可以同時(shí)保留項(xiàng)目 A 用 Python 3.12、項(xiàng)目 B 用 Python 3.10 的狀態(tài)互不干擾。這里有個(gè)必須提醒的坑用哪個(gè) Python 版本建環(huán)境就用哪個(gè) Python 的 pip 來(lái)裝包。我見過(guò)有人用 pyenv 切到了 3.10但 shell 里pip還是指向系統(tǒng) Python 3.12然后抱怨新環(huán)境不能用。每次裝包養(yǎng)成用python -m pip install ...而不是pip install ...的習(xí)慣能杜絕這類低級(jí)問(wèn)題。3.5 方案 Econda 兜底讓二進(jìn)制包替你解決一切如果你已經(jīng)試過(guò)上面幾種方案仍然失敗或者你一看到 Visual C Build Tools 就頭疼那 conda 是最后也是最省心的路徑。conda 不像 pip 那樣從源碼構(gòu)建大多數(shù)包它直接安裝預(yù)編譯的二進(jìn)制包numba、llvmlite、numpy 之間的版本組合在 conda-forge 通道里是經(jīng)過(guò)測(cè)試的。如果你還沒(méi)有 conda裝一個(gè) miniconda 就夠了體積小不強(qiáng)制占用系統(tǒng) Python。創(chuàng)建環(huán)境并安裝conda create -n jit_env python3.10 conda activate jit_env conda install numba -c conda-forge裝完驗(yàn)證python -c import numba; from numba import njit; print(numba.__version__)如果你已經(jīng)用 conda 了那建議直接在這個(gè)環(huán)境里跑整個(gè)項(xiàng)目而不是用 pip 往 conda 環(huán)境里亂塞包?；煊?conda 和 pip 不是不行但順序有講究先用 conda 裝主體框架再用 pip 補(bǔ)剩余依賴裝完后盡量不要再混著裝否則 conda 解決依賴的能力會(huì)被破壞。4. 完整實(shí)操記錄從報(bào)錯(cuò)到跑通的全過(guò)程4.1 還原我當(dāng)時(shí)踩到的坑這次我是在給一個(gè)量化回測(cè)框架裝依賴。requirements.txt 里是這樣一段numpy1.26.4 pandas2.1.4 numba0.58.1執(zhí)行安裝命令python -m pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple裝到一半pip 開始裝 numba 時(shí)終端拋出了一段紅色日志大意是Could not find a version that satisfies the requirement llvmlite然后整個(gè)安裝進(jìn)程退出。我單獨(dú)再執(zhí)行一次pip install numba0.58.1結(jié)果直接提示找不到匹配版本?？吹竭@個(gè)我第一反應(yīng)是鏡像源同步延遲或者 numba 0.58.1 的輪子還不支持我當(dāng)前的 Python 3.12。我去 PyPI 上一查發(fā)現(xiàn) numba 0.58.1 確實(shí)不支持 Python 3.12它要求 Python 3.9-3.11。而我的量化框架里又硬性鎖定了 numba0.58.1所以問(wèn)題的根不在 numba 本身在于我用 Python 3.12 去裝一個(gè)只支持到 3.11 的包的舊版本。4.2 修復(fù)操作與每一步的變化我的處理順序是這樣的先用 pyenv 裝了一個(gè) Python 3.10.14沒(méi)有卸載原來(lái)的 3.12只是另建了一個(gè)隔離環(huán)境pyenv install 3.10.14 pyenv local 3.10.14 python -m venv .venv source .venv/bin/activate激活成功后先確認(rèn)環(huán)境干凈再安裝依賴python -m pip install --upgrade pip setuptools wheel python -m pip install -r requirements.txt這次 pip 解析依賴鏈特別順利numba 0.58.1 很快下載了對(duì)應(yīng) Python 3.10 的輪子llvmlite 也直接命中預(yù)編譯包裝完沒(méi)有任何錯(cuò)誤。整個(gè)過(guò)程大概三分鐘比之前折騰編譯工具快太多。4.3 驗(yàn)證 import 和實(shí)際功能裝完后不要只看 pip list真正要驗(yàn)證的是 import 和運(yùn)行。我先跑一個(gè)最簡(jiǎn)單的 JIT 函數(shù)from numba import njit import numpy as np njit def add(a, b): return a b print(add(1, 2)) print(add(np.array([1, 2]), np.array([3, 4])))能正常打印結(jié)果說(shuō)明 numba 不光裝上了還真的能執(zhí)行 JIT 編譯。然后再跑一遍整個(gè)量化回測(cè)腳本之前卡死的地方順利通過(guò)。后來(lái)我又用同樣的思路幫一個(gè)朋友處理了另一個(gè)依賴 numba 的庫(kù)的報(bào)錯(cuò)一模一樣的套路先看 Python 版本再看 numpy 版本再確認(rèn) llvmlite基本十分鐘內(nèi)解決。5. 高頻問(wèn)題速查表與避坑心得5.1 遇到這些情況直接對(duì)照處理癥狀最常見原因優(yōu)先解法pip install numba 提示找不到匹配版本Python 版本超出 numba 支持范圍換 Python 3.10/3.11或查 PyPI 支持矩陣import numba 報(bào) ModuleNotFoundError但 pip list 里有 numba環(huán)境錯(cuò)位解釋器與 pip 不一致用 python -m pip 統(tǒng)一入口檢查 where python安裝過(guò)程中 llvmlite 編譯失敗缺少編譯工具或沒(méi)有對(duì)應(yīng)輪子升級(jí) pip裝 C Build Tools或轉(zhuǎn) conda裝完 numba 后 import 報(bào) numpy 相關(guān)錯(cuò)誤numpy 2.x 與舊 numba 不兼容降 numpy 到 1.x或升 numba 到 0.58安裝時(shí)提示 Defaulting to user installation當(dāng)前環(huán)境不可寫包裝到了用戶目錄創(chuàng)建虛擬環(huán)境避免繼續(xù)堆用戶目錄這張表基本能覆蓋 90% 的 numba 安裝問(wèn)題核心邏輯是先匹配 Python 版本再匹配 numpy 版本最后考慮編譯工具鏈。三個(gè)維度對(duì)齊了絕大多數(shù)安裝問(wèn)題都能收斂。5.2 三條我反復(fù)踩過(guò)、現(xiàn)在想提醒你的坑第一不要在系統(tǒng) Python 里裸裝項(xiàng)目依賴。系統(tǒng) Python 通常被操作系統(tǒng)或其他軟件占用權(quán)限不足時(shí) pip 會(huì)把包寫到用戶目錄時(shí)間一長(zhǎng)環(huán)境亂成一鍋粥各種 ModuleNotFoundError 會(huì)接踵而來(lái)。虛擬環(huán)境是 Python 圈子里最值得養(yǎng)成的習(xí)慣沒(méi)有之一。第二看不到報(bào)錯(cuò)全貌是排查的大忌。pip 安裝大型依賴樹時(shí)錯(cuò)誤信息可能被滾動(dòng)日志淹沒(méi)我習(xí)慣的做法是把安裝日志完整寫到文件里python -m pip install -r requirements.txt install.log 21裝完后如果失敗了在日志里搜索error、ERROR、not found通常能快速定位是哪一個(gè)環(huán)節(jié)斷掉。第三版本鎖定的力量很大但也容易變成坑。requirements.txt 里把 numba 鎖到 0.57遇到 numpy 2.x 就是炸。我的習(xí)慣是先看鎖定版本為什么存在如果項(xiàng)目可以通過(guò)升級(jí) numba 解決就升級(jí)如果升級(jí)會(huì)牽動(dòng)其他包那就用低版本 numpy 加低版本 numba 加對(duì)應(yīng) Python 的組合。記住兼容性是一個(gè)三維匹配問(wèn)題Python 版本、numpy 版本、numba 版本三者的組合必須落在官方支持矩陣?yán)?。最后再分享一個(gè)小經(jīng)驗(yàn)遇到 ModuleNotFoundError 時(shí)我現(xiàn)在的第一反應(yīng)已經(jīng)不是裝一下這個(gè)包而是先運(yùn)行python -c import sys; print(sys.path)看一眼當(dāng)前解釋器的搜索路徑。如果連包所在的目錄都不在 sys.path 里那裝一百遍都沒(méi)用。路徑問(wèn)題解決了大部分這類報(bào)錯(cuò)都能順利收?qǐng)觥?