How to Set Up Docker Desktop with WSL2 on Windows for FastAPI Apps (Step-by-Step Guide)

Views: 21

Docker is a powerful tool for containerizing applications, and FastAPI is a modern, fast Python web framework. If you’re a beginner trying to run Docker on your Windows machine to containerize a FastAPI app, this guide is for you.

In this tutorial, we’ll cover:

• Prerequisites
• Enabling virtualization
• Installing WSL2 and Docker Desktop
• Testing the Docker installation
• Building a Docker image from a FastAPI app

---

🧰 Prerequisites

• Windows 10 (2004+) or Windows 11
• Administrator access
• A FastAPI project folder with a Dockerfile and requirements.txt

---

🔧 Step 1: Enable Virtualization in BIOS

Docker Desktop with WSL2 on Windows requires virtualization to be enabled.

1. Restart your computer and enter the BIOS setup. This is usually done by pressing F2, DEL, or ESC during startup.
2. Find Virtualization Technology (VT-x or AMD-V) and enable it.
3. Save and exit BIOS.

💡 You can confirm it’s enabled by opening Task Manager > Performance > CPU and checking “Virtualization: Enabled.”

---

🖥️ Step 2: Enable Required Windows Features

Run PowerShell as Administrator and execute:

dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart
dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart

Then restart your PC.

---

🐧 Step 3: Install WSL2 and Set as Default

Run the following command in PowerShell:

wsl --install

If already installed, set WSL2 as the default version:

wsl --set-default-version 2

---

🐳 Step 4: Download and Install Docker Desktop

1. Go to Docker Desktop for Windows
2. Download and run the installer.
3. During setup:
   • Select “Use WSL2 instead of Hyper-V”
   • Ensure that Docker Desktop installs the WSL2 backend and “docker-desktop” distro.

---

✅ Step 5: Confirm Docker Installation

Run the following command in a terminal:

docker version

You should see both Client and Server details.

If you see an error like Docker Engine stopped, ensure:

• WSL2 is running
• Docker Desktop is open
• Virtualization is enabled

---

🚀 Step 6: Build Docker Image for FastAPI App

Assuming your FastAPI folder contains:

• main.py
• Dockerfile
• requirements.txt

Example Dockerfile:

FROM python:3.10

WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY . .
CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]

Run the build command:

docker build -t fastapi-app .

Once built, you can run the container with:

docker run -d -p 8000:8000 fastapi-app

Open http://localhost:8000 to access your app.

---

🧼 Optional Cleanup Commands

List images:

docker images

Remove an image:

docker rmi image_id

---

📌 Conclusion

Setting up Docker Desktop with WSL2 on Windows might seem daunting at first, but once you configure the system correctly, containerizing applications like FastAPI becomes seamless. With Docker, you can easily build, test, and deploy your apps in isolated environments.

---

🔗 References:

• Docker Desktop WSL2 Backend
• Microsoft Docs – WSL Installation
• FastAPI Documentation
• Enable Virtualization in BIOS