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

sudo apt update
sudo apt install -y libcairo2-dev pkg-config python3-dev build-essential

Step 2: Clear Pipenv Cache and Regenerate Lockfile

cd ~/project_app
pipenv lock --clear

Step 3: Run install

pipenv install --dev

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