مشكلة وحل 12: حل خطأ ImportError و ModuleNotFoundError في بايثون

من أكثر الأخطاء التي تظهر للمبتدئين أثناء تعلم بايثون خطأ ImportError وخطأ ModuleNotFoundError. وغالبًا تظهر هذه الأخطاء عندما تحاول استيراد مكتبة أو ملف داخل برنامج Python، لكن بايثون لا تستطيع العثور عليه أو لا تستطيع استيراده بالطريقة الصحيحة.

قد تكتب كودًا بسيطًا مثل import requests، ثم تظهر لك رسالة خطأ تقول إن المكتبة غير موجودة. أو قد تحاول استيراد دالة من ملف آخر، فتظهر مشكلة في اسم الملف أو مكانه أو طريقة الاستيراد.

في هذا المقال من سلسلة مشكلة وحل على بايثون العرب، سنشرح الفرق بين ImportError و ModuleNotFoundError، وأشهر أسباب ظهور هذه الأخطاء، وكيف تحلها خطوة بخطوة مع أمثلة عملية مناسبة للمبتدئين.

{getToc} $title={محتوى المقال}

{alertInfo} أخطاء الاستيراد في بايثون لا تعني دائمًا أن الكود صعب؛ غالبًا السبب مكتبة غير مثبتة، اسم خاطئ، أو تشغيل الملف من مسار غير مناسب.

ما معنى ImportError في بايثون؟

خطأ ImportError يظهر عندما تواجه بايثون مشكلة أثناء استيراد مكتبة أو جزء من مكتبة أو ملف من ملفات مشروعك.

مثال على رسالة الخطأ:

ImportError: cannot import name 'something'

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

ما معنى ModuleNotFoundError في بايثون؟

خطأ ModuleNotFoundError يظهر عندما لا تستطيع بايثون العثور على المكتبة أو الملف من الأساس.

مثال:

ModuleNotFoundError: No module named 'requests'

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

الفرق بين ImportError و ModuleNotFoundError

الفرق بين الخطأين مهم جدًا للمبتدئ؛ لأن طريقة الحل تختلف حسب معنى الرسالة.

الخطأ	معناه	مثال
ModuleNotFoundError	بايثون لم تجد المكتبة أو الملف من الأساس	No module named 'requests'
ImportError	بايثون وجدت شيئًا، لكنها لم تستطع استيراد الاسم المطلوب	cannot import name 'x'

بشكل مبسط: إذا كانت المشكلة أن المكتبة غير موجودة، فغالبًا سترى ModuleNotFoundError. أما إذا كانت المشكلة في اسم الشيء الذي تريد استيراده أو في طريقة الاستيراد، فقد ترى ImportError.

السبب الأول: المكتبة غير مثبتة

هذا هو السبب الأشهر لخطأ ModuleNotFoundError. مثلًا إذا كتبت:

import requests

ثم ظهرت الرسالة:

ModuleNotFoundError: No module named 'requests'

فهذا يعني غالبًا أن مكتبة requests غير مثبتة في بيئة Python التي تستخدمها.

الحل

افتح موجه الأوامر أو Terminal واكتب:

pip install requests

أو إذا كنت تستخدم أكثر من إصدار Python:

python -m pip install requests

وبعد التثبيت جرّب تشغيل الكود مرة أخرى.

{alertSuccess} إذا ظهر لك No module named، فابدأ دائمًا بالتأكد أن المكتبة مثبتة في نفس بيئة Python التي تشغل منها البرنامج.

السبب الثاني: تثبيت المكتبة في بيئة مختلفة

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

مثال: قد تثبت المكتبة باستخدام:

pip install pandas

لكن عند التشغيل يظهر:

ModuleNotFoundError: No module named 'pandas'

هنا المشكلة ليست بالضرورة أن المكتبة غير مثبتة، بل ربما ثبتّها في Python مختلف عن الذي يشغل البرنامج.

الحل

استخدم هذا الأمر لتثبيت المكتبة داخل نفس Python المستخدم:

python -m pip install pandas

ويمكنك معرفة نسخة Python التي تعمل عليها بكتابة:

python --version

ولمعرفة مكان Python:

where python

على ويندوز، أو:

which python

على Linux أو macOS.

السبب الثالث: خطأ في كتابة اسم المكتبة

بايثون حساسة للأسماء، لذلك أي خطأ بسيط في كتابة اسم المكتبة قد يسبب مشكلة.

مثال خاطئ:

import Request

أو:

import request

بينما الاسم الصحيح للمكتبة هو:

import requests

لاحظ حرف s في النهاية.

{alertWarning} قبل أن تبحث عن حل طويل، تأكد أولًا من كتابة اسم المكتبة بشكل صحيح كما هو في التوثيق أو صفحة التثبيت.

السبب الرابع: اسم ملفك يطابق اسم مكتبة

هذه مشكلة شائعة جدًا. مثلًا إذا سميت ملفك:

random.py

ثم حاولت استخدام مكتبة random الأصلية:

import random

print(random.randint(1, 10))

قد يحدث خلل؛ لأن بايثون قد تحاول استيراد ملفك أنت بدل المكتبة الأصلية.

الحل

لا تسمِّ ملفاتك بأسماء مكتبات مشهورة مثل:

• random.py
• math.py
• requests.py
• json.py
• datetime.py

غيّر اسم الملف إلى اسم واضح مثل:

test_random_number.py

ثم احذف ملفات الكاش إن وجدت مثل مجلد:

__pycache__

السبب الخامس: محاولة استيراد اسم غير موجود

قد يظهر ImportError عندما تحاول استيراد دالة أو كلاس غير موجود داخل الملف.

لنفترض أن لديك ملفًا اسمه tools.py وفيه:

def say_hello():
    print("Hello")

ثم في ملف آخر كتبت:

from tools import welcome

هنا سيظهر خطأ؛ لأن welcome غير موجودة داخل ملف tools.py.

الحل

استورد الاسم الصحيح:

from tools import say_hello

say_hello()

أو تأكد من أن الاسم الذي تستورده موجود فعلًا داخل الملف.

السبب السادس: تشغيل الملف من مسار غير صحيح

قد يكون الملف موجودًا، لكنك تشغل البرنامج من مجلد مختلف، فتفشل عملية الاستيراد.

مثال على هيكل مشروع بسيط:

project/
  main.py
  helpers.py

إذا كان الملفان في نفس المجلد، يمكنك كتابة:

import helpers

لكن إذا شغلت البرنامج من مكان مختلف أو نقلت الملفات بطريقة غير منظمة، قد تظهر مشاكل الاستيراد.

الحل

• تأكد أن الملفات داخل نفس مجلد المشروع إذا كان الاستيراد مباشرًا.
• افتح Terminal من داخل مجلد المشروع.
• لا تنقل ملفًا واحدًا بعيدًا عن باقي ملفات المشروع.
• استخدم أسماء ملفات واضحة بدون مسافات أو رموز غريبة.

السبب السابع: مشاكل البيئة الافتراضية venv

البيئة الافتراضية venv مفيدة جدًا لتنظيم مكتبات كل مشروع، لكنها قد تسبب ارتباكًا للمبتدئ إذا لم يتم تفعيلها قبل التثبيت أو التشغيل.

إذا كنت تستخدم بيئة افتراضية، يجب تفعيلها أولًا.

على ويندوز:

venv\Scripts\activate

على Linux أو macOS:

source venv/bin/activate

ثم ثبت المكتبة:

pip install requests

ثم شغّل البرنامج من نفس البيئة.

السبب الثامن: الاستيراد الدائري Circular Import

الاستيراد الدائري يحدث عندما يحاول ملفان استيراد بعضهما في نفس الوقت.

مثال مبسط:

ملف a.py يستورد من b.py، وملف b.py يستورد من a.py. هنا قد تتلخبط بايثون وتظهر رسالة ImportError.

الحل

• انقل الدوال المشتركة إلى ملف ثالث مثل utils.py.
• تجنب أن يستورد ملفان بعضهما مباشرة.
• اجعل هيكل المشروع أوضح.

مثال أفضل:

project/
  a.py
  b.py
  utils.py

ثم يستورد كل من a.py و b.py الدوال المشتركة من utils.py بدل استيراد بعضهما.

جدول أسباب وحلول ImportError و ModuleNotFoundError

السبب	الخطأ المتوقع	الحل
المكتبة غير مثبتة	ModuleNotFoundError	ثبتها باستخدام python -m pip install package
تثبيت المكتبة في بيئة مختلفة	No module named	تأكد من البيئة المستخدمة وشغّل التثبيت بنفس Python
خطأ في اسم المكتبة	ModuleNotFoundError	راجع الاسم الصحيح للمكتبة
اسم الملف يطابق اسم مكتبة	ImportError أو سلوك غريب	غيّر اسم الملف واحذف __pycache__
استيراد اسم غير موجود	cannot import name	تأكد أن الدالة أو الكلاس موجود داخل الملف
مسار تشغيل غير صحيح	ModuleNotFoundError	شغّل البرنامج من مجلد المشروع الصحيح
استيراد دائري	ImportError	أعد تنظيم الملفات واستخدم ملفًا مشتركًا

خطوات حل الخطأ بسرعة

عندما يظهر لك ImportError أو ModuleNotFoundError، اتبع هذه الخطوات بالترتيب:

1. اقرأ اسم المكتبة أو الملف المذكور في رسالة الخطأ.
2. تأكد من كتابة الاسم بشكل صحيح.
3. إذا كان الخطأ No module named، تأكد أن المكتبة مثبتة.
4. ثبت المكتبة باستخدام python -m pip install package.
5. تأكد أنك تشغل البرنامج من نفس بيئة Python التي ثبتت فيها المكتبة.
6. تحقق أن اسم ملفك لا يطابق اسم مكتبة معروفة.
7. إذا كنت تستورد من ملف داخل مشروعك، تأكد من مكان الملف والاسم الموجود داخله.
8. إذا ظهرت مشكلة cannot import name، راجع الاستيراد الدائري أو الاسم غير الموجود.

{alertSuccess} أفضل طريقة لحل أخطاء الاستيراد هي قراءة الرسالة بهدوء: هل بايثون لم تجد المكتبة؟ أم وجدتها لكنها لم تجد الاسم المطلوب؟

مثال عملي كامل

لنفترض أنك كتبت هذا الكود:

import requests

response = requests.get("https://example.com")

print(response.status_code)

وظهرت الرسالة:

ModuleNotFoundError: No module named 'requests'

الحل هو تثبيت المكتبة:

python -m pip install requests

ثم تشغيل الملف مرة أخرى:

python main.py

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

أخطاء شائعة يجب تجنبها

• تثبيت المكتبة باستخدام pip ثم تشغيل البرنامج ببيئة Python مختلفة.
• تسمية الملف باسم مكتبة مشهورة مثل requests.py.
• كتابة اسم المكتبة بشكل خاطئ.
• نسيان تفعيل البيئة الافتراضية قبل التثبيت.
• استيراد دالة غير موجودة داخل الملف.
• تشغيل الملف من مجلد غير مناسب.
• استخدام كود من الإنترنت يعتمد على مكتبات لم يتم تثبيتها.

{alertWarning} لا تحل المشكلة بحذف Python أو إعادة تثبيته مباشرة. غالبًا الحل أبسط: تثبيت مكتبة، تفعيل البيئة، أو تغيير اسم ملف.

أسئلة شائعة

ما سبب ModuleNotFoundError في بايثون؟

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

ما الفرق بين ImportError و ModuleNotFoundError؟

خطأ ModuleNotFoundError يعني أن بايثون لم تجد الموديول من الأساس، أما ImportError فقد يعني أن بايثون وجدت الملف أو المكتبة لكنها لم تستطع استيراد الاسم المطلوب منها.

كيف أثبت مكتبة في بايثون؟

يمكنك تثبيت المكتبات باستخدام pip. والأفضل للمبتدئين استخدام:

python -m pip install package_name

مع استبدال package_name باسم المكتبة المطلوبة.

لماذا المكتبة مثبتة لكن الخطأ ما زال يظهر؟

غالبًا لأنك ثبتت المكتبة في بيئة Python مختلفة عن البيئة التي تشغل منها البرنامج. تأكد من مفسر Python المستخدم داخل المحرر، وفعّل البيئة الافتراضية إذا كنت تستخدمها.

هل اسم الملف قد يسبب ImportError؟

نعم. إذا سميت ملفك باسم مكتبة مثل random.py أو requests.py، قد تحاول بايثون استيراد ملفك بدل المكتبة الأصلية، مما يسبب أخطاء استيراد أو نتائج غير متوقعة.

روابط مهمة من بايثون العرب

• مشكلة وحل 10: حل مشكلة SyntaxError invalid syntax في بايثون
• مشكلة وحل 9: حل مشكلة NameError name is not defined في بايثون
• أوامر بايثون جاهزة للمبتدئين
• تشغيل بايثون أون لاين بدون تثبيت
• أفضل طريقة لتعلم بايثون بالعربي من الصفر

مصدر خارجي مفيد

يمكنك الرجوع إلى توثيق Python الرسمي لمعرفة المزيد عن نظام الاستيراد في بايثون: Python Documentation - The import system.

الخلاصة

خطأ ImportError وخطأ ModuleNotFoundError من أشهر أخطاء بايثون، وغالبًا يرتبطان بمشاكل في استيراد المكتبات أو الملفات. إذا ظهرت لك رسالة No module named، فابدأ بفحص تثبيت المكتبة والبيئة المستخدمة. وإذا ظهرت رسالة cannot import name، فراجع الاسم الذي تستورده وهيكل ملفات مشروعك.

تذكر أهم النقاط:

• ModuleNotFoundError يعني غالبًا أن المكتبة أو الملف غير موجود.
• ImportError يعني أن هناك مشكلة في عملية الاستيراد نفسها.
• استخدم python -m pip install لتثبيت المكتبات في البيئة الصحيحة.
• لا تسمِّ ملفاتك بأسماء مكتبات مشهورة.
• تأكد من تفعيل البيئة الافتراضية إذا كنت تستخدم venv.
• راجع مسار الملفات وطريقة تشغيل المشروع.

{alertSuccess} القاعدة الذهبية: عند ظهور خطأ استيراد في بايثون، اسأل نفسك أولًا: هل المكتبة غير موجودة؟ أم أن الاسم المستورد غير صحيح؟