Bỏ qua đến nội dung chính
Mục lục

ModuleNotFoundError, ImportError trong Python: cách sửa

AIDev Team · duyệt: Nguyễn Việt Chung

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

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

No module named 'holidays'

Gói chưa cài

python -m pip install holidays

No module named 'holidays', dù vừa cài

Cài vào bản Python khác, thường vì chưa kích hoạt .venv

Kích hoạt môi trường ảo, cài lại bằng python -m pip

No module named 'calender'

Gõ sai tên, hay sai chữ hoa như 'Calendar'

Sửa thành calendar

No module named 'cv2'

Tên cài bằng pip khác tên import

python -m pip install opencv-python

No module named 'gia_ve'

File gia_ve.py tự viết không nằm cạnh file chính

Đặt file module vào cùng thư mục với file chính

cannot import name 'montth' from 'calendar'

Module có thật, tên bên trong thì không

Sửa theo gợi ý Did you mean

module 'calendar' has no attribute 'month'

File calendar.py của bạn che module chuẩn

Đổi tên file của bạn

attempted relative import with no known parent package

Import có dấu chấm đầu trong file chính

Import tuyệt đối, xem bài package

No module named 'tkinter', '_tkinter' hay '_ctypes'

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 (sudo apt install python3-tk trên Ubuntu), hay với bản tự biên dịch thì cài thư viện C còn thiếu rồi biên dịch lại. Bản cài từ python.org cho Windows và macOS đã có sẵn tkinter

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:

python
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:

python
import holidays

Dòng cuối của thông báo lỗi:

text
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):

bash
.venv\Scripts\Activate.ps1
python -m pip install holidays

macOS/Linux:

bash
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ó:

bash
python -c "import sys; print(sys.executable)"
python lich.py
deactivate
python -c "import sys; print(sys.executable)"
python lich.py

KẾ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:

python
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 pyyaml

Tê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)):

bash
python main.py

KẾ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ỹ:

python
print(issubclass(ModuleNotFoundError, ImportError))

KẾT QUẢ

True

Dò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:

bash
python main.py

KẾ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:

python
from .ngay_le import NGAY_LE

Dòng cuối của thông báo lỗi:

text
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

  1. Bạn vừa cài holidays mà dự án vẫn báo No 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 holidays không có trên PyPI
    • Trình soạn code chạy file bằng Python chung thay vì Python của .venv
  2. Dòng import cv2 báo No module named 'cv2'. Lệnh cài nào đúng?

    • python -m pip install cv2
    • python -m pip install opencv-python
    • python -m venv cv2
  3. Thư mục có file calendar.py của bạn. File chính gọi calendar.month(2026, 11) thì báo lỗi gì?

    • ModuleNotFoundError
    • ImportError
    • AttributeError
Đúng hết lần đầu +15 XP

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.

python
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ày

Tó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ằng python -m pip.

  • Một số gói có tên cài khác tên import, như cv2 cài bằng opencv-python.

  • File trùng tên module chuẩn, như calendar.py, gây AttributeError: đổi tên file.

  • ImportError cannot import name nghĩ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ủ đề

modulenotfounderror

Bài này có hữu ích?

Hỏi đáp

Đang tải câu hỏi…

Tham vấn chuyên môn

Nguyễn Việt Chung

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.
Biên soạn: AIDev Team · Rà soát · Quy trình biên tập