ModuleNotFoundError, ImportError trong Python: cách sửa
Bài 10/13 · Chương 24
Giải nghĩa thông báo lỗi
- 10 phút
- Cơ bản
- Python 3.14
- Cập nhật
Trong bài này · 13
Dòng lỗi ModuleNotFoundError: No module named 'holidays' trong Python báo rằng lệnh import không tìm thấy module có tên đó, trong thư viện chuẩn cũng như trong các gói đã cài. Nguyên nhân thường gặp là gói chưa cài, cài vào một bản Python khác với bản đang chạy file, gõ sai tên, hay đặt tên file trùng một module chuẩn.
Cần biết trước: import, tự viết module, pip và môi trường ảo venv.
Bảng tra nhanh: nguyên nhân ModuleNotFoundError và ImportError
Cột đầu là phần đứng sau tên lỗi trên dòng cuối của thông báo. Hai hàng cùng thông báo No module named 'holidays' có nguyên nhân khác nhau, nên bạn cần kiểm tra theo thứ tự từ trên xuống:
Thông báo | Nguyên nhân | Cách sửa |
|---|---|---|
| Gói chưa cài |
|
| Cài vào bản Python khác, thường vì chưa kích hoạt | Kích hoạt môi trường ảo, cài lại bằng |
| Gõ sai tên, hay sai chữ hoa như | Sửa thành |
| Tên cài bằng pip khác tên import |
|
| File | Đặt file module vào cùng thư mục với file chính |
| Module có thật, tên bên trong thì không | Sửa theo gợi ý |
| File | Đổi tên file của bạn |
| Import có dấu chấm đầu trong file chính | Import tuyệt đối, xem bài package |
| Module của thư viện chuẩn mà bản Python trên Linux thiếu: hệ điều hành tách nó ra gói riêng, hay bản tự biên dịch thiếu thư viện C | Không dùng pip: cài gói của hệ điều hành ( |
Hàng thứ năm là hàng có cách sửa làm được ngay trên trang. Khối dưới ghi file gia_ve.py vào thư mục đang chạy rồi import nó, nên Python tìm thấy:
with open("gia_ve.py", "w", encoding="utf-8") as f:
f.write("GIA_VE = 120000\n")
import gia_ve
print(gia_ve.GIA_VE)KẾT QUẢ
120000Đổi print(gia_ve.GIA_VE) thành print(gia_ve.__name__) rồi chạy lại: dòng in ra thành gia_ve, tên mà Python dùng để tìm file gia_ve.py.
No module named: gói chưa cài hay cài sai môi trường
Chưa cài gói holidays mà đã import thì Python dừng ở dòng import:
import holidays
Dòng cuối của thông báo lỗi:
ModuleNotFoundError: No module named 'holidays'
Python gọi lỗi này là ModuleNotFoundError. Nút Chạy trên trang dùng Python 3.14 chạy trong trình duyệt, có thư viện chuẩn nhưng không cài thêm gói bằng pip được. Vì vậy trên trang, import holidays hay import requests luôn ra đúng dòng trên. Muốn dùng các gói này, bạn chạy file trên máy của mình.
Trên máy, cài gói trong cùng cửa sổ terminal đã kích hoạt môi trường ảo của dự án:
Windows (PowerShell):
.venv\Scripts\Activate.ps1
python -m pip install holidays
macOS/Linux:
source .venv/bin/activate
python -m pip install holidays
Lỗi vẫn còn sau khi cài thì gói đã vào một bản Python khác với bản đang chạy file. Đoạn dưới chạy trong Docker image python:3.14-slim, thư mục /app. Trước đó đã tạo .venv bằng python -m venv .venv, kích hoạt nó và cài holidays. File lich.py gồm hai dòng import holidays và print(holidays.VN().get("2026-09-02")). Đoạn chạy lich.py bằng Python của .venv, rồi thoát môi trường ảo và chạy lại bằng Python chung. Dòng sys.executable in đường dẫn của bản Python đang chạy, bài sys nói thêm về nó:
python -c "import sys; print(sys.executable)"
python lich.py
deactivate
python -c "import sys; print(sys.executable)"
python lich.pyKẾT QUẢ
/app/.venv/bin/python
Quốc khánh
/usr/local/bin/python
Traceback (most recent call last):
File "/app/lich.py", line 1, in <module>
import holidays
ModuleNotFoundError: No module named 'holidays'Cùng một file, Python của .venv có holidays còn Python chung thì không. Trình soạn code như VS Code cũng có thể chạy file bằng Python chung: khi đó hãy chọn lại trình thông dịch nằm trong .venv của dự án.
Tên import khác tên gói cài bằng pip
Phần lớn gói có tên cài giống tên import, như holidays hay requests. Một số gói nổi tiếng thì khác, nên dòng lỗi cho bạn tên import, còn lệnh cài cần tên gói trên PyPI:
TEN_GOI = {
"cv2": "opencv-python",
"PIL": "pillow",
"sklearn": "scikit-learn",
"bs4": "beautifulsoup4",
"yaml": "pyyaml",
}
for ten_import, ten_cai in TEN_GOI.items():
print(f"import {ten_import:8} -> pip install {ten_cai}")KẾT QUẢ
import cv2 -> pip install opencv-python
import PIL -> pip install pillow
import sklearn -> pip install scikit-learn
import bs4 -> pip install beautifulsoup4
import yaml -> pip install pyyamlTên import phân biệt chữ hoa và chữ thường: import PIL đúng, import pil báo No module named 'pil'. Khi chưa chắc tên cài, trang của gói trên PyPI ghi lệnh cài ngay đầu trang.
File của bạn trùng tên module chuẩn
Python tìm module trong thư mục của file chính trước, rồi mới tới thư viện chuẩn, trừ vài module dựng sẵn trong trình thông dịch như sys và time. Đặt tên file của mình là calendar.py thì import calendar nạp file đó, và hàm của module chuẩn không còn. Đoạn dưới chạy trong Docker image python:3.14-slim, thư mục /app có hai file: calendar.py chỉ chứa dòng BUOI = 1, và main.py gồm import calendar rồi print(calendar.month(2026, 11)):
python main.pyKẾT QUẢ
Traceback (most recent call last):
File "/app/main.py", line 2, in <module>
print(calendar.month(2026, 11))
^^^^^^^^^^^^^^
AttributeError: module 'calendar' has no attribute 'month' (consider renaming '/app/calendar.py' since it has the same name as the standard library module named 'calendar' and prevents importing that standard library module)Lỗi là AttributeError chứ không phải lỗi import, vì Python đã import thành công, chỉ là import nhầm file. Python 3.13 và 3.14 thêm lời khuyên đổi tên file trong ngoặc. Python 3.12 và nút Chạy trên trang chỉ in phần module 'calendar' has no attribute 'month', nên bạn phải tự nghĩ tới tên file.
ImportError: module có thật nhưng tên bên trong thì không
Khi module tìm được nhưng tên bạn xin trong dòng from … import không có, Python báo ImportError. ModuleNotFoundError chính là một loại ImportError riêng cho trường hợp không tìm thấy cả module. Hàm issubclass(A, B) hỏi lớp lỗi A có phải một loại B không, bài kế thừa dạy kỹ:
print(issubclass(ModuleNotFoundError, ImportError))KẾT QUẢ
TrueDòng ImportError ghi đường dẫn file của module trong ngoặc, nên mỗi máy in một khác. Đoạn dưới chạy trong Docker image python:3.14-slim, thư mục /app, với main.py chỉ có dòng from calendar import montth:
python main.pyKẾT QUẢ
Traceback (most recent call last):
File "/app/main.py", line 1, in <module>
from calendar import montth
ImportError: cannot import name 'montth' from 'calendar' (/usr/local/lib/python3.14/calendar.py). Did you mean: 'month'?Trên trang, phần trong ngoặc là /lib/python314.zip/calendar.py, còn câu Did you mean thì giống nhau. Import tương đối trong file chính cho một ImportError không có đường dẫn:
from .ngay_le import NGAY_LE
Dòng cuối của thông báo lỗi:
ImportError: attempted relative import with no known parent package
Dấu chấm đầu chỉ dùng được trong file nằm trong một package, bài package hướng dẫn cách sửa.
Kiểm tra nhanh
Bạn vừa cài
holidaysmà dự án vẫn báoNo module named 'holidays'. Những nguyên nhân nào có thể?- Cửa sổ terminal lúc cài chưa kích hoạt
.venv - Gói
holidayskhông có trên PyPI - Trình soạn code chạy file bằng Python chung thay vì Python của
.venv
- Cửa sổ terminal lúc cài chưa kích hoạt
Dòng
import cv2báoNo module named 'cv2'. Lệnh cài nào đúng?python -m pip install cv2python -m pip install opencv-pythonpython -m venv cv2
Thư mục có file
calendar.pycủa bạn. File chính gọicalendar.month(2026, 11)thì báo lỗi gì?- ModuleNotFoundError
- ImportError
- AttributeError
Bài tập
Tìm tên gói cần cài từ dòng lỗi
Viết thân hàm ten_goi_pip(dong_loi). Tham số dong_loi là dòng cuối của một thông báo lỗi. Nếu đó là dòng lỗi thiếu module, có dạng như ModuleNotFoundError: No module named 'holidays', lấy tên module nằm giữa hai dấu nháy đơn. Tra tên đó trong dict TEN_GOI: có trong dict thì trả về tên gói ghi ở đó, không có thì trả về chính tên module. Dòng lỗi loại khác thì trả về chuỗi rỗng.
Ví dụ: ten_goi_pip("ModuleNotFoundError: No module named 'PIL'") trả về "pillow".
Trả về: tên gói cần cài, một str.
TEN_GOI = {
"cv2": "opencv-python",
"PIL": "pillow",
"sklearn": "scikit-learn",
"bs4": "beautifulsoup4",
"yaml": "pyyaml",
}
def ten_goi_pip(dong_loi):
pass # Viết thân hàm thay cho dòng nàyTóm tắt
No module named 'X'nghĩa là Python không tìm thấy module X ở thư mục file chính, thư viện chuẩn hay các gói đã cài.Vừa cài mà vẫn lỗi thì gói đã vào bản Python khác: kích hoạt
.venv, cài bằngpython -m pip.Một số gói có tên cài khác tên import, như
cv2cài bằngopencv-python.File trùng tên module chuẩn, như
calendar.py, gây AttributeError: đổi tên file.ImportError
cannot import namenghĩa là module có thật, tên bên trong sai.Nút Chạy trên trang chỉ có thư viện chuẩn (trừ vài module như tkinter), không cài thêm gói được.
Câu hỏi thường gặp
Lỗi No module named trong Python sửa thế nào?
Kiểm tra theo bốn bước của bảng tra nhanh: tên module gõ đúng chưa, gói đã cài chưa, cài vào đúng môi trường ảo chưa, và tên cài có khác tên import không. Phần lớn trường hợp là bước ba, cách kích hoạt môi trường ảo có ở bài venv.
Lỗi ImportError và ModuleNotFoundError khác nhau thế nào?
ModuleNotFoundError là một loại ImportError, báo khi không tìm thấy cả module. ImportError loại thường báo khi module có nhưng tên bạn xin bên trong không có, như from calendar import montth, hay khi import tương đối sai chỗ. Câu lệnh except ImportError: bắt được cả hai, xem bài try except.
Vì sao VS Code báo No module named dù đã pip install?
VS Code chạy file bằng trình thông dịch đang chọn, có thể là Python chung chứ không phải Python trong .venv. Chọn lại trình thông dịch nằm trong .venv của dự án rồi chạy lại. In sys.executable ở đầu file để biết bản nào đang chạy, như đoạn chạy trong Docker ở trên.
Có cài thêm thư viện cho nút Chạy trên trang được không?
Không. Nút Chạy dùng Python 3.14 trong trình duyệt với thư viện chuẩn, mỗi lần chạy bắt đầu từ một thư mục trống, và không có lệnh pip. Gói ngoài như holidays hay requests cần cài và chạy trên máy của bạn theo bài pip.
Chủ đề
Bài này có hữu ích?
Hỏi đáp
Tham vấn chuyên môn
Nhà sáng lập AIDev và VietPlatform · Thạc sĩ AI MSE
- Tốt nghiệp thủ khoa xuất sắc Thạc sĩ AI MSE.
- Đồng sáng lập, CTO E-University, SVOnline: số hóa 10+ đại học, 40.000+ sinh viên.
- Xây hệ thống AI cho doanh nghiệp tại VietPlatform.