حل مشكلة ModuleNotFoundError في بايثون

ما معنى الخطأ ModuleNotFoundError؟

عند محاولة استيراد مكتبة أو وحدة في بايثون لم يتم العثور عليها، يظهر الخطأ التالي:

ModuleNotFoundError: No module named 'اسم_المكتبة'

هذا الخطأ يعني أن بايثون بحث عن الوحدة التي تحاول استيرادها ولم يجدها في أي من المسارات المعروفة لديه. السبب الشائع هو أنك لم تثبت المكتبة بعد، أو أن هناك خطأ في كتابة اسمها.

الفرق بين ModuleNotFoundError و ImportError

ImportError يظهر عندما يجد بايثون الوحدة، لكنه يفشل في تحميلها لسبب ما (مثل خطأ داخلي في الكود).
أما ModuleNotFoundError فهو حالة خاصة من ImportError تظهر عندما لا يتم العثور على الوحدة أساسًا.

مثال:

import doesnotexist
# ModuleNotFoundError

لكن:

from math import not_a_function
# ImportError

التأكد من كتابة اسم الحزمة أو الملف بشكل صحيح

أحد أكثر الأسباب شيوعًا لهذا الخطأ هو الخطأ الإملائي. تأكد أن الاسم مكتوب تمامًا كما هو مسجل في PyPI أو في اسم الملف.

مثال:

import numppy  # خطأ
import numpy   # صحيح

استخدم النسخ واللصق من الموقع الرسمي للحزمة بدلًا من الكتابة اليدوية لتجنب الأخطاء.

التحقق من تثبيت الحزمة المطلوبة

قبل أن تفترض أن هناك مشكلة، تأكد من أن الحزمة مثبّتة. يمكنك استخدام الأمر التالي:

pip list

أو:

pip show اسم_الحزمة

إذا لم تظهر، فذلك يعني أن الحزمة غير مثبتة أصلًا.

تثبيت الحزمة المفقودة باستخدام pip

لحل المشكلة، قم بتثبيت الحزمة. استخدم:

pip install اسم_الحزمة

إذا كان لديك أكثر من إصدار بايثون، تأكد أنك تستخدم pip الصحيح:

python3 -m pip install اسم_الحزمة

التأكد من أنك تستخدم البيئة الصحيحة (Python Environment)

قد تكون الحزمة مثبتة في بيئة افتراضية أخرى، أو تم التثبيت من حساب مختلف. تحقق من المسار الحالي الذي يستخدمه بايثون:

import sys
print(sys.executable)

تأكد من أن هذا هو نفس المسار الذي تستخدمه لتثبيت الحزم.

استخدام pip المناسب لإصدار بايثون

أحيانًا يكون عندك أكثر من بايثون على الجهاز. مثلاً، pip يتبع python2 بينما pip3 يتبع python3. لذلك استخدم:

python3 -m pip install اسم_الحزمة

أو:

py -m pip install اسم_الحزمة

إذا كنت على ويندوز.

التعامل مع باقات النظام مقابل باقات المستخدم

إذا واجهت مشكلة صلاحيات عند التثبيت (PermissionError)، يمكن أن تستخدم:

pip install --user اسم_الحزمة

هذا يثبت الحزمة فقط للمستخدم الحالي دون الحاجة لصلاحيات مدير النظام.

هل الحزمة جزء من بايثون نفسه أم حزمة خارجية؟

بعض المطورين يعتقدون أن مكتبات شهيرة مثل requests أو pandas تأتي مع بايثون، لكن الحقيقة أنها حزم خارجية يجب تثبيتها يدويًا.

وجود ملفات بنفس اسم الحزمة تسبب تعارض

إذا أنشأت ملفًا في مشروعك اسمه json.py أو random.py ثم حاولت استيراد json أو random، فسيظن بايثون أنك تحاول استيراد الملف المحلي، مما يؤدي إلى تعارض أو خطأ.

تأكد ألا يكون اسم أي ملف في مشروعك هو نفسه اسم مكتبة مشهورة.

تجربة التثبيت من جديد بعد حذف الحزمة

في بعض الأحيان، تتعرض الحزمة للتلف أو لملفات غير مكتملة، ويمكن حل المشكلة بحذف الحزمة ثم إعادة تثبيتها:

pip uninstall اسم_الحزمة
pip install اسم_الحزمة

التحقق من إصدار بايثون

بعض الحزم لا تدعم كل الإصدارات. على سبيل المثال، بعض الحزم تعمل فقط مع Python 3.7 فما فوق. تحقق من إصدارك باستخدام:

python --version

إذا كانت الحزمة غير متوافقة مع إصدارك، ستحتاج إلى الترقية أو استخدام إصدار مختلف.

التعامل مع الحزم غير المدعومة أو القديمة

إذا كانت الحزمة غير موجودة في PyPI، أو لم تعد مدعومة، قد تحتاج إلى تثبيتها يدويًا من GitHub أو من ملف tar.gz، أو البحث عن بديل حديث.

البحث عن الحلول باستخدام اسم الخطأ

عند فشل كل شيء، انسخ رسالة الخطأ كاملة وابحث عنها في Google أو Stack Overflow. تأكد من تضمين اسم الحزمة، إصدار بايثون، ونظام التشغيل في عملية البحث.