Sửa lỗi ModuleNotFoundError: No module named 'xxx' trong Python

Chuyện gì đang xảy ra

Python không tìm thấy module lúc import. Đơn giản vậy thôi. Nhưng nguyên nhân thì khác nhau: package chưa được cài, cài vào nhầm môi trường Python, pip và python trỏ đến hai nơi khác nhau, hoặc tên package trên PyPI khác với tên bạn dùng trong câu lệnh import.

Hãy xác định nguyên nhân trước — cài mù quáng chỉ tốn thời gian và thường không giải quyết được gì.

Debug trước

Tìm ra chính xác Python binary nào đang chạy script của bạn:

which python
which python3
python --version
python3 --version

Sau đó kiểm tra xem package đã được cài cho đúng Python đó chưa:

python -m pip list | grep requests   # thay 'requests' bằng tên module của bạn

Package xuất hiện trong danh sách nhưng lỗi vẫn còn? Đó là trường hợp pip/Python không khớp — chuyển thẳng sang Giải pháp 3.

Giải pháp 1: Cài đặt package còn thiếu

Chín trong mười trường hợp, package đơn giản là chưa được cài. Cài nó đi:

pip install xxx

Trên máy có cả Python 2 và 3, hãy chỉ định rõ ràng:

pip3 install xxx
# Hoặc gắn trực tiếp với Python binary bạn đang dùng:
python -m pip install xxx
python3 -m pip install xxx

python -m pip là cách an toàn hơn. Nó bỏ qua sự nhầm lẫn về PATH của shell bằng cách gọi pip thuộc về đúng Python binary đó.

Giải pháp 2: Sai virtual environment

Bạn đã cài rồi — chỉ là cài vào nhầm env. Ai cũng từng gặp ít nhất một lần.

# Có virtualenv nào đang active không?
echo $VIRTUAL_ENV

# Kích hoạt đúng env, sau đó cài đặt
source venv/bin/activate          # Linux/macOS
.\venv\Scripts\activate           # Windows

pip install xxx

Người dùng Conda:

conda activate myenv
pip install xxx
# hoặc nếu có trong conda registry:
conda install xxx

Dấu hiệu nhận biết: package cài không có lỗi, nhưng ModuleNotFoundError cứ quay lại mỗi khi bạn mở terminal mới.

Giải pháp 3: pip/Python binary không khớp

Trên nhiều bản Linux, pip thuần vẫn trỏ về Python 2.7. Bạn cài package vào đó, Python 3 không thấy, rồi đứng gãi đầu không hiểu tại sao.

python -m pip install xxx

Sau khi cài xong, xác nhận nó nằm đúng chỗ Python thực sự tìm kiếm:

python -c "import xxx; print(xxx.__file__)"

Đường dẫn in ra phải nằm trong virtualenv đang active hoặc thư mục site-packages của Python 3.x — không phải đâu đó dưới /usr/lib/python2.7/.

Giải pháp 4: Tên pip khác tên import

Tên trên PyPI và tên import không phải lúc nào cũng giống nhau. pip install thành công không có nghĩa là bạn gõ đúng tên trong câu lệnh import. Những trường hợp kinh điển:

• pip install Pillow → import PIL
• pip install scikit-learn → import sklearn
• pip install python-dateutil → import dateutil
• pip install opencv-python → import cv2
• pip install beautifulsoup4 → import bs4

Khi không chắc, hãy kiểm tra trang PyPI của package hoặc README của nó. Tên import luôn được ghi rõ ở đó.

Giải pháp 5: Module local không nằm trong sys.path

Với các module tự viết (không phải pip package), Python có thể đơn giản là không biết tìm ở đâu:

import sys
print(sys.path)   # liệt kê tất cả thư mục Python tìm kiếm

Cách xử lý nhanh:

import sys
sys.path.insert(0, '/đường/dẫn/tuyệt/đối/đến/project')
import xxx

Giải pháp tốt hơn về lâu dài: chạy Python từ thư mục gốc của project, hoặc cài package ở chế độ editable để luôn có thể import được:

pip install -e .

Giải pháp 6: Python version không tương thích

Các package như tensorflow 2.x đã bỏ hỗ trợ Python 3.7. Nếu bản thân lệnh pip install báo lỗi, hãy đọc kỹ — thường nó ghi rõ dải phiên bản Python được hỗ trợ.

Ghim một phiên bản cũ hơn vẫn còn hỗ trợ Python của bạn:

pip install "somepackage==1.2.3"   # phiên bản cuối cùng hỗ trợ Python của bạn

Kiểm tra kết quả

# Import có thành công không?
python -c "import xxx; print('OK')"

# Nó nằm ở đâu?
python -c "import xxx; print(xxx.__file__)"

# Phiên bản nào được cài?
python -m pip show xxx

Bài học rút ra

• Dùng python -m pip install làm mặc định. pip thuần là cái bẫy trên hệ thống nhiều phiên bản Python.
• Kích hoạt virtualenv trước khi bắt đầu làm việc. Quên activate là nguyên nhân gốc rễ của ít nhất một nửa những than thở "nhưng tôi đã cài rồi mà!".
• Commit một file requirements.txt. Chạy pip install -r requirements.txt trong môi trường mới phải tái tạo lại đúng setup — không có bất ngờ.
• Khi dùng Python 3.10 và 3.11 song song, hãy chỉ định rõ: python3.11 -m pip install xxx loại bỏ mọi sự mơ hồ.