Khắc phục triệt để lỗi "The command 'docker' could not be found" trong WSL 2

Chào anh em!

Trong quá trình làm việc với các hệ thống Backend hiện đại trên Windows (sử dụng môi trường Windows Subsystem for Linux - WSL 2 kết hợp với Docker Desktop), chắc chắn đã có ít nhất một lần anh em mở terminal Ubuntu lên, hừng hực khí thế gõ lệnh thần thánh:

docker compose up -d

Và rồi nhận lại ngay một gáo nước lạnh từ màn hình dòng lệnh:

The command 'docker' could not be found in this WSL 2 distro.
We recommend to activate the WSL integration in Docker Desktop settings.

Đừng hoảng loạn! Đây là một trong những lỗi phổ biến nhất mà các lập trình viên Backend thường gặp phải khi cấu hình môi trường. Hãy cùng mổ xẻ nguyên nhân và cách khắc phục triệt để lỗi này chỉ trong 1 nốt nhạc nhé!

1. Nguyên nhân thực chất là gì?

Lý do rất đơn giản: Docker Desktop (chạy trên hệ điều hành Windows gốc) và WSL 2 distro (ví dụ như Ubuntu chạy ngầm bên trong Windows) là hai môi trường độc lập.

Mặc dù bạn đã cài đặt Docker Desktop trên Windows, nhưng distro Linux của bạn (WSL 2) lại chưa được cấu hình để "nhìn thấy" và chia sẻ các lệnh Docker từ Docker Desktop truyền sang. Do đó, khi bạn gõ lệnh docker, Linux kêu lên rằng nó chẳng tìm thấy câu lệnh đó ở đâu cả!

2. Cách khắc phục nhanh nhất (Bật tích hợp WSL 2)

Cách chuẩn mực và chính thống nhất được khuyến nghị bởi Docker chính là kích hoạt tính năng WSL Integration trong Docker Desktop:

1. Mở ứng dụng Docker Desktop trên Windows của bạn lên.
2. Click vào biểu tượng Settings (hình bánh răng cưa) ở góc trên bên phải.
3. Ở menu bên trái, chọn mục Resources -> WSL Integration.
4. Tại đây, bạn sẽ thấy danh sách các bản phân phối WSL (WSL Distros) đang có trên máy của bạn (ví dụ: Ubuntu, Debian,...).
5. Tìm đến bản phân phối WSL mà bạn đang sử dụng để code, sau đó bật công tắc (Enable) sang màu xanh cho nhấp nháy.
6. Nhấn nút Apply & Restart ở góc dưới cùng bên phải để Docker Desktop lưu cấu hình và khởi động lại dịch vụ.

Sau khi Docker Desktop khởi động xong, bạn hãy quay lại cửa sổ Terminal của WSL 2, đóng tab cũ mở lại (hoặc chạy lệnh kiểm tra docker --version), mọi thứ sẽ hoạt động trơn tru ngay lập tức!

3. Phương án xử lý thay thế (Cài đặt Docker Engine trực tiếp trong Linux)

Trong một số trường hợp đặc biệt (ví dụ: bạn dùng các server Linux thuần, hoặc không muốn bật Docker Desktop vì nặng máy), bạn có thể chọn giải pháp cài đặt Docker Engine trực tiếp bên trong môi trường WSL 2 thay vì dùng chung với Docker Desktop.

Bạn sẽ cần chạy các lệnh cài đặt thủ công trên Ubuntu:

# Cập nhật lại kho lưu trữ hệ thống
sudo apt-get update
sudo apt-get install ca-certificates curl gnupg

# Thêm GPG key chính thức của Docker
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg

# Thiết lập repository cho Docker
echo \
  "deb [arch="$(dpkg --print-architecture)" signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \
  "$(. /etc/os-release && echo "$VERSION_CODENAME")" stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# Cài đặt Docker Engine và Docker Compose
sudo apt-get update
sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

Tuy nhiên, với phần lớn anh em lập trình viên sử dụng Windows + Docker Desktop, Cách 2 (Bật WSL Integration) vẫn là giải pháp tối ưu, nhẹ nhàng và ít tốn công sức nhất!

Lời kết

Lỗi thiếu lệnh docker trong WSL 2 thực chất chỉ là vấn đề cấu hình phân quyền chia sẻ môi trường giữa Windows và Linux. Nắm vững bản chất này, bạn sẽ tự xử lý gọn gàng trong vòng chưa đầy 1 phút để tiếp tục tập trung vào việc code hệ thống Backend!