Setting Up Django on Windows 11 with VS Code, WSL2, and Docker

Published on 19 Dec 2025Development

Developing a Django application on Windows 11 using the Windows Subsystem for Linux (WSL) provides a professional-grade Linux environment while keeping the ease of use of Windows. Here are the 12 steps to set up your environment from scratch.

Part 1: System & Environment Setup

1. Enable WSL2 on Windows 11

Open PowerShell as an Administrator and run:

wsl --install

This command enables the necessary virtual machine features and installs Ubuntu by default. Restart your computer once the process completes.

2. Configure your Linux User

After restarting, the Ubuntu terminal will launch. Follow the prompts to create a Username and Password.

Note: When typing your password, characters will not appear on the screen (blind typing). This is a standard security feature in Linux.

3. Update the Linux Packages

Ensure your Linux distribution is up to date by running:

sudo apt update && sudo apt upgrade -y

4. Install Python and Pip

While WSL usually comes with Python, you need the package manager and virtual environment tools. Run:

sudo apt install python3-pip python3-venv -y

Part 2: VS Code Integration

5. Install VS Code and the WSL Extension

Download and install Visual Studio Code on Windows 11. Once open, go to the Extensions view (Ctrl+Shift+X) and install the WSL extension by Microsoft.

6. Connect VS Code to WSL

Click the green "Remote" button (two brackets ><) in the bottom-left corner of VS Code. Select Connect to WSL. A new window will open; check the bottom-left corner to see "WSL: Ubuntu" (or your specific distro).

7. Install Python Extension (WSL Side)

In the new WSL-connected window, go back to the Extensions view. You will see a button that says "Install in WSL: Ubuntu" for the Python extension. This is required for VS Code to "see" the Python version inside Linux.

Part 3: Docker and Database Integration

8. Install Docker Desktop and Enable WSL Integration

Download and install Docker Desktop for Windows 11. Once installed, open Settings > Resources > WSL Integration. Ensure your Ubuntu distribution is toggled on. This allows you to run Docker commands directly from your WSL terminal.

9. Create Project Configuration Files

In your WSL terminal, create the core files needed for a containerized environment:

touch Dockerfile docker-compose.yml requirements.txt

Inside requirements.txt, add

django

and

psycopg2-binary

to support PostgreSQL.

10. Configure the Docker Environment

Define your Python environment in the Dockerfile and your services (Web and DB) in docker-compose.yml. Use the official

postgres

image for your database service to ensure data persistence.

11. Initialize Django and Database Settings

Run the initialization command through Docker:

docker compose run web django-admin startproject myproject .

Open

settings.py

and update the DATABASES section. Set the 'HOST' to

'db'

(matching your docker-compose service name) and use the PostgreSQL engine.

12. Launch the Development Environment

Start your containers and run migrations to set up the database schema:

docker compose up -d

docker compose exec web python manage.py migrate

Navigate to

http://localhost:8000

in your Windows browser to confirm the setup is complete.