خطای ModuleNotFoundError: No module named در پایتون؛ رفع کامل
🗓 آخرین به‌روزرسانی:
پیام ModuleNotFoundError: No module named '...' یکی از پرجست‌وجوترین خطاهای پایتون است؛ به‌خصوص وقتی کدی را از اینترنت اجرا می‌کنید که از کتابخانه‌هایی مثل requests، numpy یا pandas استفاده می‌کند. خبر خوب: این خطا تقریباً همیشه با نصب درست ماژول یا انتخاب محیط پایتون درست حل می‌شود.
معنی خطای ModuleNotFoundError در پایتون
وقتی دستور import را اجرا می‌کنید، پایتون در مسیرهای مشخصی (پوشه فعلی، کتابخانه استاندارد و پوشه site-packages محیط فعلی) دنبال ماژول می‌گردد. اگر آن را پیدا نکند، ModuleNotFoundError می‌دهد. این خطا زیرمجموعه ImportError است و معمولاً یعنی ماژول نصب نیست، نامش اشتباه نوشته شده یا در محیط پایتون دیگری نصب شده است.
علت‌های رایج این خطا
- کتابخانه خارجی (مثل requests یا numpy) اصلاً نصب نشده است.
- ماژول در یک پایتون یا محیط مجازی دیگر نصب شده و برنامه با پایتون دیگری اجرا می‌شود.
- غلط تایپی یا تفاوت حروف بزرگ و کوچک در نام ماژول (مثل
Mathبه جایmath). - نام بسته برای نصب با نام import فرق دارد (مثلاً نصب با
pip install beautifulsoup4ولی import باbs4). - فعال نبودن محیط مجازی (venv) در ترمینال یا ویرایشگر.
کد غلط و کد درست (با خروجی واقعی)
همه نمونه‌کدهای زیر با پایتون 3.13.5 اجرا شده‌اند و خروجی‌ها همان چیزی است که پایتون واقعاً نمایش می‌دهد.
مثال 1: حروف بزرگ در نام ماژول
❌ کد غلط:
import Math
print(Math.sqrt(16))خروجی:
Traceback (most recent call last):
File "/home/user/project/main.py", line 1, in <module>
import Math
ModuleNotFoundError: No module named 'Math'✅ کد درست:
import math
print(math.sqrt(16))خروجی:
4.0مثال 2: ماژول نصب‌نشده (نمونه)
❌ کد غلط:
import reqests # typo: the correct name is requestsخروجی:
Traceback (most recent call last):
File "/home/user/project/main.py", line 1, in <module>
import reqests # typo: the correct name is requests
^^^^^^^^^^^^^^
ModuleNotFoundError: No module named 'reqests'✅ کد درست:
import json # standard library, no install needed
print(json.dumps({"ok": True}))خروجی:
{"ok": true}نصب ماژول در همان پایتونی که برنامه را اجرا می‌کند
مطمئن‌ترین روش نصب، اجرای pip از طریق خود مفسر پایتون است تا ماژول دقیقاً در همان محیط نصب شود:
python -m pip install requests
# on Windows, if needed:
py -m pip install requests
# check which Python is running:
python -c "import sys; print(sys.executable)"اگر از VS Code استفاده می‌کنید، از نوار پایین یا دستور Python: Select Interpreter همان مفسری را انتخاب کنید که ماژول را در آن نصب کرده‌اید.
راه‌حل قدم‌به‌قدم
- نام ماژول در پیام خطا را بخوانید و املای آن را بررسی کنید.
- مشخص کنید ماژول جزو کتابخانه استاندارد است یا باید نصب شود.
- با
python -m pip install نام-بستهآن را در همان پایتونی نصب کنید که برنامه را اجرا می‌کند. - اگر از venv استفاده می‌کنید، ابتدا آن را فعال کنید و دوباره نصب کنید.
- در ویرایشگر، مفسر پایتون (Interpreter) درست را انتخاب کنید و برنامه را دوباره اجرا کنید.
خواندن پیام ModuleNotFoundError و عیب‌یابی
ModuleNotFoundError با پیام No module named یعنی پایتون در هیچ‌کدام از مسیرهای جست‌وجوی خود (sys.path) ماژولی با آن نام پیدا نکرده است. رایج‌ترین علت این است که کتابخانه برای همان پایتونی که کد را اجرا می‌کند نصب نشده؛ مثلاً با pip در پایتون سیستم نصب کرده‌اید ولی کد در محیط مجازی یا نسخه دیگری اجرا می‌شود.
برای تشخیص، sys.executable را چاپ کنید تا بدانید کدام مفسر اجرا می‌شود، و نصب را دقیقاً با همان مفسر انجام دهید: python -m pip install name. همچنین دقت کنید نام پکیج در pip همیشه با نام import یکی نیست؛ مثلاً beautifulsoup4 با bs4 و opencv-python با cv2 import می‌شوند.
بررسی وجود ماژول بدون خطا
import importlib.util
import sys
print("Interpreter:", sys.executable)
for name in ("json", "requests_fake_pkg"):
found = importlib.util.find_spec(name) is not None
print(name, "installed:", found)
try:
import requests_fake_pkg
except ModuleNotFoundError as error:
print(type(error).__name__, "-", error.msg)خروجی (اجراشده با Python 3.13):
Interpreter: /workspace/devsource/articles/venv/bin/python
json installed: True
requests_fake_pkg installed: False
ModuleNotFoundError - No module named 'requests_fake_pkg'قدم‌به‌قدم رفع ModuleNotFoundError
تقریباً همیشه مشکل این است که پکیج در مفسری نصب شده که کد را اجرا نمی‌کند.
- نام ماژول را بررسی کنید: غلط املایی و تفاوت نام pip و نام import (مثل bs4 و beautifulsoup4) را چک کنید.
- مفسر فعال را ببینید: sys.executable را چاپ کنید و با مفسر انتخاب‌شده در VS Code یا PyCharm مقایسه کنید.
- با همان مفسر نصب کنید: دستور python -m pip install name را با همان مسیر مفسر اجرا کنید.
- محیط مجازی را فعال کنید: اگر پروژه venv دارد، قبل از نصب و اجرا آن را activate کنید.
- sys.path را بررسی کنید: برای ماژول‌های خودتان مطمئن شوید پوشه پروژه در sys.path است یا با python -m اجرا کنید.
چک‌لیست پیشگیری
- همیشه از python -m pip install استفاده کنید تا نصب در همان مفسر انجام شود.
- در VS Code و PyCharm مفسر پروژه را روی محیط مجازی خود تنظیم کنید.
- وابستگی‌ها را در requirements.txt بنویسید و روی سیستم جدید با pip install -r نصب کنید.
- فایل‌های خود را هم‌نام ماژول‌های استاندارد یا کتابخانه‌ها نام‌گذاری نکنید.
- برای ماژول‌های خودتان، اسکریپت را از ریشه پروژه با python -m package.module اجرا کنید.
📌 همچنین بخوانید: خطای unexpected EOF while parsing در پایتون، خطای ‘int’ object is not subscriptable در پایتون و خطای ImportError
سؤالات متداول
ماژول را نصب کردم ولی باز هم No module named می‌گیرم؛ چرا؟
به احتمال زیاد چند نسخه پایتون دارید و ماژول در نسخه دیگری نصب شده است. با python -m pip install نصب کنید و مسیر sys.executable را بررسی کنید.
فرق ModuleNotFoundError و ImportError چیست؟
ModuleNotFoundError یعنی خود ماژول پیدا نشد؛ ImportError (به شکل cannot import name) یعنی ماژول پیدا شد ولی نامی که از آن خواستید داخلش نیست.
چرا نام نصب و نام import متفاوت است؟
نام بسته در PyPI و نام ماژول داخل آن لزوماً یکی نیست؛ مثلاً pip install pillow و import PIL. مستندات هر کتابخانه نام درست را می‌گوید.
نصب کردم ولی باز هم No module named می‌دهد؛ چرا؟
تقریباً همیشه به این دلیل است که pip و python به دو نسخه متفاوت اشاره می‌کنند. نصب را با python -m pip تکرار کنید.
در Jupyter چطور مطمئن شوم در kernel درست نصب شده؟
در یک سلول %pip install name را اجرا کنید؛ این دستور در همان kernel فعال نصب می‌کند.
ماژول خودم را import می‌کنم و پیدا نمی‌شود؛ چه کنم؟
مطمئن شوید فایل در همان پوشه یا در یک پکیج با ساختار درست است و اسکریپت را از ریشه پروژه اجرا کنید.
آموزش‌های مرتبط
- ماژول‌ها و پکیج‌ها در پایتون
- pip و محیط مجازی venv
- نصب پایتون در ویندوز
- آموزش جامع پایتون از صفر تا پیشرفته
- همه خطاهای رایج پایتون و راه‌حل آن‌ها