Raspberry Pi पर uvicorn के साथ FastAPI में pandas ModuleNotFoundError का समाधान

Raspberry Pi पर FastAPI/uvicorn चलाते वक्त pandas ModuleNotFoundError का कारण और समाधान: सही venv सक्रिय करें, python -m pip से इंस्टॉल करें, wrapper सेट करें.

Raspberry Pi पर uvicorn और multiprocessing के साथ FastAPI सेवा चलाते समय एक दिखने में आसान, पर उलझाने वाली त्रुटि सामने आ सकती है: ModuleNotFoundError: No module named 'pandas'. प्रोजेक्ट एक अलग वर्चुअल एनवायरनमेंट इस्तेमाल करता है, requirements सूची में pandas शामिल है, फिर भी uvicorn के एप्लिकेशन मॉड्यूल लोड करते ही import फेल हो जाता है। आमतौर पर दिक्कत न तो pandas में होती है और न ही आपके कोड में, बल्कि इस बात में कि पैकेज कहाँ इंस्टॉल हुआ है और वास्तव में कौन-सा Python इंटरप्रेटर आपकी प्रक्रियाएँ चला रहा है।

सर्विस पाथ से न्यूनतम पुनरुत्पादन

असफलता तब ट्रिगर होती है जब uvicorn एप्लिकेशन मॉड्यूल इम्पोर्ट करता है। इस मामले में, केवल यह import पंक्ति ही क्रैश कराने के लिए पर्याप्त है:

# src/services/ALS_back.py
import pandas as pnd

और सेवा एक फ़ंक्शन से शुरू होती है जो नियंत्रण uvicorn को सौंप देता है। कॉल पाथ का सार इस तरह दिखता है:

# main.py
import uvicorn
def start_backend(port_num):
    uvicorn.run("src.services.ALS_back:app", host="0.0.0.0", port=port_num, reload=False)

जैसे ही uvicorn मॉड्यूल इम्पोर्ट तक पहुँचता है, वह pandas के लिए ModuleNotFoundError उठाता है।

असल में गड़बड़ी कहाँ होती है

स्टैक ट्रेस दिखाता है कि इंटरप्रेटर पैकेज प्रोजेक्ट के .venv से लोड कर रहा है। इसी समय, pip का इंस्टॉलेशन पथ /home/rpi/.local/lib/python3.9/site-packages की ओर इशारा करता है, जो उस venv के बाहर है। यह असंगति साफ बताती है कि पैकेज वर्चुअल एनवायरनमेंट वाले pip से नहीं, बल्कि सिस्टम pip से इंस्टॉल हुए हैं। अगर आपका लॉन्चर स्क्रिप्ट प्रोजेक्ट का .venv सक्रिय किए बिना Python शुरू करता है, तो subprocesses और uvicorn workers गलत इंटरप्रेटर विरासत में ले लेते हैं, और डिस्क के किसी और स्थान पर pandas मौजूद होने के बावजूद import फेल हो जाता है।

समाधान: उसी venv के अंदर इंस्टॉल करें जिसे आप वास्तव में चलाते हैं

इंस्टॉलेशन और रनटाइम को एकसमान रखने का विश्वसनीय तरीका है कि किसी भी कदम से पहले वर्चुअल एनवायरनमेंट सक्रिय करें, बिल्ड टूलिंग अपग्रेड करें, और उसी एनवायरनमेंट के इंटरप्रेटर से requirements इंस्टॉल करें। प्रोजेक्ट रूट से:

cd /home/rpi/Desktop/als-v4
. .venv/bin/activate
python -m pip install --upgrade pip setuptools wheel
python -m pip install -r requirements-rpi.txt

यह पूरा होने पर, सुनिश्चित करें कि पैकेज सक्रिय एनवायरनमेंट से ही रेजॉल्व हो रहे हैं:

python -c "import pandas; print(pandas.__version__)"
python -c "import numpy; print(numpy.__version__)"

यदि आप ऐप को किसी wrapper स्क्रिप्ट (जैसे, alsv4) से शुरू करते हैं, तो Python या uvicorn चलाने से पहले वह .venv सक्रिय करे—ताकि सभी प्रक्रियाएँ एक ही इंटरप्रेटर के तहत चलें।

जब साफ शुरुआत सबसे तेज़ रास्ता हो

अगर आपने पहले सिस्टम और venv इंस्टॉलेशनों को मिलाया हुआ है और ऊपर दिए कदमों का असर नहीं हो रहा, तो बचे-खुचे असर को डिबग करने से बेहतर है कि नया सिरे से एनवायरनमेंट बनाएं। मौजूदा .venv हटाकर नया बनाना और requirements दोबारा इंस्टॉल करना—इसी सेटअप में अपेक्षित व्यवहार वापस ले आया।

Raspberry Pi और समान सेटअप्स पर यह क्यों मायने रखता है

uvicorn और multiprocessing जैसे टूल्स उस एनवायरनमेंट पर निर्भर रहते हैं जो उन्हें लॉन्च करता है। अगर इंस्टॉलेशन venv के बाहर हुआ है, लेकिन रनटाइम venv की ओर इशारा कर रहा है (या उल्टा), तो मशीन पर कहीं पैकेज इंस्टॉल होने के बावजूद import त्रुटियाँ मिलेंगी। इंस्टॉलेशन और निष्पादन को एक ही .venv के भीतर सख्ती से रखने से ऐसी विफलताओं से बचा जा सकता है और आपका डिप्लॉयमेंट पूर्वानुमेय रहता है।

सारांश और व्यावहारिक सलाह

कुछ भी इंस्टॉल करने और ऐप शुरू करने से पहले प्रोजेक्ट का .venv सक्रिय करें। वर्तमान सक्रिय इंटरप्रेटर से pip को जोड़ने के लिए python -m pip का उपयोग करें। requirements-rpi.txt उसी venv के अंदर इंस्टॉल करें। त्वरित import जाँचों से संस्करण सत्यापित करें। यदि पहले की असंगतियों के कारण समस्या बनी रहती है, तो venv दोबारा बनाएँ और पुनः इंस्टॉल करें। अंत में, सुनिश्चित करें कि आपका लॉन्चर स्क्रिप्ट uvicorn या किसी worker प्रक्रिया को शुरू करने से पहले एनवायरनमेंट सक्षम करे, ताकि हर घटक एक ही स्थान से imports रेजॉल्व करे।