Installing Django 5.2 Locally (Mac)

This document describes how to run Django 5.2 on your Mac and expose it to the internet using localhost.run so that DJ4E autograders can test your work.

When you complete this, you will have a URL from localhost.run (e.g. https://xxxxx.lhr.lt) that you can submit to the "Install" autograder.

Other platforms: Windows · WSL · Linux · Overview

Prerequisites

You need the following installed on your computer:

  1. Python 3.10, 3.11, 3.12, or 3.13 – Download Python
    On Mac, python3 is often pre-installed, or use Homebrew: brew install python

  2. Git – Download Git
    brew install git or Xcode Command Line Tools

  3. SSH – Used by localhost.run (no signup required). SSH is pre-installed on Mac.

We use the same folder structure as on Linux: ~/django_projects for your Django apps and ~/dj4e-samples for the sample code. The virtual environment lives in ~/.ve52.

Creating a Virtual Environment

Create and activate a virtual environment for Django 5.2 in your home directory:

cd ~
python3 -m venv .ve52
source .ve52/bin/activate

If python3 is not found, install Python or use a specific version (e.g. python3.12 -m venv .ve52).

Once activated, your prompt should show (.ve52) at the start. Verify Python and install Django:

pip install --upgrade pip
pip install django==5.2
python -m django --version

The Django version should be 5.2 or higher.

Installing dj4e-samples and Requirements

Make sure your virtual environment is activated (you should see (.ve52) in your prompt). If you opened a new terminal, activate it again as shown above.

Clone the DJ4E sample code and install its dependencies:

cd ~
git clone https://github.com/csev/dj4e-samples
cd dj4e-samples
git checkout django52
git pull origin django52
pip install --upgrade pip
pip install -r requirements52.txt

Verify the installation:

python manage.py check

Expected output includes:

System check identified no issues (0 silenced).

Then run migrations:

python manage.py makemigrations
python manage.py migrate

The dj4e-samples folder is reference material for the course. To pull updates later:

cd ~/dj4e-samples
git pull origin django52

Building Your Django Application

Ensure your virtual environment is activated. Create your project folder and Django project:

cd ~
mkdir -p django_projects
cd django_projects
django-admin startproject mysite

Edit mysite/mysite/settings.py and set:

ALLOWED_HOSTS = [ '*' ]

Leave DEBUG = True. Save the file.

Adding the Polls Application

Create the polls app and add the initial view:

cd ~/django_projects/mysite
python manage.py startapp polls

Edit mysite/polls/views.py and replace its contents with:

from django.http import HttpResponse

def index(request):
    return HttpResponse("Hello, world. You're at the polls index.")

Create mysite/polls/urls.py with:

from django.urls import path
from . import views

urlpatterns = [
    path("", views.index, name="index"),
]

Edit mysite/mysite/urls.py and replace its contents with:

from django.contrib import admin
from django.urls import include, path

urlpatterns = [
    path("polls/", include("polls.urls")),
    path("admin/", admin.site.urls),
]

Verify:

python manage.py check

Running Your Server and Exposing with localhost.run

You need two terminal windows (or tabs).

Terminal 1 – Django server

cd ~
source .ve52/bin/activate
cd django_projects/mysite
python manage.py runserver

Leave this running. The server listens on http://127.0.0.1:8000/.

Terminal 2 – localhost.run tunnel

Open a second terminal and run:

ssh -R 80:localhost:8000 localhost.run

Leave this running. localhost.run will print a public URL, for example:

Forwarding HTTP traffic from https://xxxxx-xx-xx-xx-xx.lhr.lt

That URL is what you submit to the Install autograder. It forwards traffic to your local Django server.

Testing locally

You should see: "Hello, world. You're at the polls index."

Submitting to the Autograder

  1. Keep Terminal 1 (runserver) and Terminal 2 (ssh tunnel) running
  2. Copy the full localhost.run URL (e.g. https://xxxxx.lhr.lt)
  3. Submit that URL to the DJ4E Install autograder

The autograder will fetch your site through localhost.run. Each time you restart the SSH tunnel, the URL may change; if it does, submit the new URL.

Workflow: Change, Check, Restart, Test

When you change code:

  1. Run python manage.py check to catch errors
  2. Stop the server (Ctrl+C in Terminal 1) and start it again: python manage.py runserver
  3. Test at http://127.0.0.1:8000/ or your localhost.run URL

The tunnel (Terminal 2) can stay running; you only need to restart the Django server.

Checkup Tool

We provide a checkup script in dj4e-samples:

bash ~/dj4e-samples/tools/checkup.sh

Possible Errors

See Fixing Common Django Errors for troubleshooting.

If ssh -R 80:localhost:8000 localhost.run fails:

Starting Over

To remove everything and start fresh:

cd ~
rm -rf .ve52
rm -rf dj4e-samples
rm -rf django_projects

Then follow this document from the beginning.

About Django 4.2

As of January 2026, this course uses Django 5.2. If you prefer Django 4.2, follow the Django 4.2 install instructions and adapt the local steps from this document.