CodingBowl

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. 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: Characters will not appear on the screen when typing your password; this is a standard Linux security feature.

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 Pipenv

WSL comes with Python, but we need to install the package manager and Pipenv:

sudo apt install python3-pip -y

sudo apt install python3-pytest -y

Modern Linux prevents global pip installs to protect the system. Install pipx to safely manage Pipenv:

sudo apt update
sudo apt install pipx -y
pipx ensurepath
# RESTART YOUR TERMINAL NOW
pipx install pipenv

Part 2: VS Code Integration

5. Install VS Code and the WSL Extension

Download Visual Studio Code on Windows. Open it, 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 (><) in the bottom-left corner and select Connect to WSL. The bottom-left should now display "WSL: Ubuntu".

7. Install Python Extension (WSL Side)

In the WSL-connected window, go to the Extensions view and click "Install in WSL: Ubuntu" for the Python extension. This is critical for VS Code to recognize your virtual environments.

Part 3: Project Initialization

8. Create a Project Directory

Inside your WSL terminal, create a folder and enter it:

mkdir my_django_project && cd my_django_project

9. Install Django with Pipenv

Initialize your environment and install dependencies in one step:

pipenv install django psycopg2-binary

This creates a Pipfile and Pipfile.lock, which track your project's specific versions.

10. Fix the "ImportError: Couldn't import Django"

To avoid the common PYTHONPATH error, you must execute commands inside the Pipenv environment. You have two choices:

• The Shell Method: Run

  pipenv shell

  to activate the virtual environment (you will see your project name in the prompt).
• The Run Method: Prefix commands with

  pipenv run

  .

11. Initialize the Django Project

Using the run method to create the project structure:

pipenv run django-admin startproject core .

12. Select the Interpreter in VS Code

To ensure VS Code's terminal and debugger use Pipenv: Press Ctrl+Shift+P, type "Python: Select Interpreter", and select the path that includes .local/share/virtualenvs.

Part 4: Launching

13. Run the Development Server

Start your project to verify the setup:

pipenv run python manage.py runserver

Navigate to http://127.0.0.1:8000 in your browser. You should see the Django success page.

---

Troubleshooting: Installing xhtml2pdf in WSL

The xhtml2pdf package often fails during installation because it requires specific Linux C-libraries to compile PDF components and has strict version requirements for its dependencies.

Step 1: Install Ubuntu System Dependencies

Before running Pipenv, you must install the binary headers required for image and PDF processing in Ubuntu:

sudo apt update && sudo apt install -y build-essential python3-dev libssl-dev libffi-dev libxml2-dev libxslt1-dev zlib1g-dev libjpeg-dev libfreetype6-dev liblcms2-dev libwebp-dev

Step 2: Reset the Environment

If you have previously encountered a ResolutionFailure, you must clear the "stuck" state of your project:

rm Pipfile.lock

pipenv --rm

Step 3: Install xhtml2pdf with Backtracking

Use the backtrack flag to allow Pipenv to search for a compatible combination of sub-dependencies (like html5lib and reportlab):

pipenv install xhtml2pdf --backtrack

Step 4: Forced Version Resolution (If Step 3 Fails)

If Pipenv still cannot find a match, you can manually specify a known working version combination for the dependencies that usually cause the conflict:

pipenv install "html5lib==1.1" "reportlab<4.0" xhtml2pdf

Critical Note on File Systems

If your project is located on the Windows drive (e.g., /mnt/c/Users/...), Pipenv may timeout during the "locking" phase. For the best results, ensure your project folder is located in the native Linux home directory:

cp -r /mnt/c/path/to/project ~/project

cd ~/project