Fix 'ModuleNotFoundError: No module named debugpy' khi debug Python trong VS Code

Lỗi Gặp Phải

Bạn nhấn F5 trong VS Code để bắt đầu phiên debug Python và nhận được thông báo này trong Debug Console:

ModuleNotFoundError: No module named 'debugpy'

Phiên debug lập tức bị tắt. Không có breakpoint, không có output — chỉ một dòng đó thôi.

Nguyên Nhân

debugpy là debug adapter mà VS Code đưa vào tiến trình Python của bạn. Nó được đóng gói sẵn cùng với extension Python — nhưng VS Code chạy nó bên trong interpreter của bạn. Nếu interpreter đó không có debugpy, lệnh import sẽ thất bại. Virtualenv mới tạo, môi trường conda, và các bản cài đặt Python hệ thống mà VS Code chưa từng dùng đến thường là thủ phạm.

Chín trong mười trường hợp, nguyên nhân là một trong hai điều này:

• VS Code đang trỏ tới virtualenv chưa cài debugpy.
• Bạn vừa tạo lại virtualenv gần đây và quên cài lại các dev dependency.

Cách Sửa 1 — Cài debugpy Vào Môi Trường Hiện Tại

Đầu tiên, xác nhận xem VS Code đang thực sự dùng Python nào. Mở Command Palette (Ctrl+Shift+P / Cmd+Shift+P), chạy Python: Select Interpreter, và ghi lại đường dẫn — nó phải trỏ tới virtualenv của dự án bạn.

Bây giờ cài debugpy vào đúng interpreter đó:

# Khi đã kích hoạt virtualenv trong terminal:
pip install debugpy

# Hoặc chỉ định interpreter cụ thể:
/path/to/your/venv/bin/python -m pip install debugpy

# Windows:
.\venv\Scripts\python.exe -m pip install debugpy

Khởi động lại phiên debug. Cách này giải quyết được vấn đề trong phần lớn trường hợp.

Cách Sửa 2 — Trỏ VS Code Tới Đúng Interpreter

debugpy đã được cài nhưng lỗi vẫn xuất hiện? VS Code có thể đang dùng sai Python. Khi có nhiều môi trường, VS Code có thể mặc định dùng Python hệ thống thay vì venv của dự án bạn.

• Mở Command Palette → Python: Select Interpreter.
• Chọn interpreter bên trong virtualenv của bạn — tìm các đường dẫn như ./venv/bin/python hoặc ./.venv/bin/python3.
• Không thấy trong danh sách? Nhấn Enter interpreter path và duyệt tìm thủ công.

Cố định cấu hình này cho từng workspace qua .vscode/settings.json:

{
  "python.defaultInterpreterPath": "${workspaceFolder}/venv/bin/python"
}

Cách Sửa 3 — Thêm debugpy Vào Dependencies Của Dự Án

Làm việc với virtualenv mới trong CI, Docker, hay môi trường nhóm dùng chung? Hãy thêm debugpy vào dev requirements ngay từ đầu để không bao giờ bị thiếu nữa:

# requirements-dev.txt
debugpy>=1.8.0

pip install -r requirements-dev.txt

Dùng pyproject.toml thay thế:

[project.optional-dependencies]
dev = ["debugpy>=1.8.0"]

pip install -e ".[dev]"

Cách Sửa 4 — Kiểm Tra Cấu Hình launch.json

Có file .vscode/launch.json tùy chỉnh không? Kiểm tra xem nó có đang ghi đè đường dẫn Python hoặc trỏ tới interpreter không mong muốn không:

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Python: Current File",
      "type": "debugpy",
      "request": "launch",
      "program": "${file}",
      "console": "integratedTerminal"
    }
  ]
}

Các cấu hình cũ dùng "type": "python" — vẫn hoạt động bình thường. Trường type không phải nguyên nhân gây ra lỗi này trong cả hai trường hợp.

Cách Sửa 5 — Môi Trường conda

Với conda, pip thông thường hoạt động tốt bên trong môi trường đã được kích hoạt. Ngoài ra còn có tùy chọn native của conda:

conda activate myenv
pip install debugpy
# hoặc
conda install -c conda-forge debugpy

Kiểm tra lại rằng interpreter được chọn trong VS Code trỏ vào đúng môi trường conda (ví dụ: /home/user/miniconda3/envs/myenv/bin/python), không phải Python base. Đây là lỗi conda phổ biến nhất trong trường hợp này.

Xác Nhận Đã Sửa Xong

Trước khi nhấn F5, hãy chạy lệnh này trong terminal tích hợp của VS Code:

python -c "import debugpy; print(debugpy.__version__)"

Bạn sẽ thấy số phiên bản như 1.8.14. Vẫn còn lỗi ModuleNotFoundError? Terminal cũng đang dùng Python khác — hãy quay lại kiểm tra phần chọn interpreter.

Khi lệnh import đó chạy được, nhấn F5. Breakpoint sẽ được gắn vào, Debug Console hiển thị output chương trình của bạn, và debugpy sẽ không còn cản trở bạn nữa.

Phòng Ngừa

• Commit file requirements-dev.txt với debugpy>=1.8.0 — bất kỳ lần clone mới nào cũng sẽ tự động cài nó.
• Đặt python.defaultInterpreterPath trong .vscode/settings.json và commit lên repo. Cả nhóm sẽ dùng đúng interpreter ngay từ ngày đầu.
• Sau khi tạo lại virtualenv, chạy pip install -r requirements-dev.txt trước khi mở VS Code. Đừng chờ VS Code nhắc — nó sẽ không nhắc đâu.