Facial Recognition

Simple browser-based face login built with Django and OpenCV.

What This Project Does

The app has a simple flow:

1. Register a username and a reference photo
2. Go to login
3. Enter the username
4. Take a new photo or upload one
5. If the face matches, the user is logged in

Tech Used

• Django 5.2
• OpenCV 4.11
• YuNet face detector
• SFace face recognizer

Requirements

• Python 3.11+
• pip

Project Structure

Important paths:

• Django project root: facialrecognition/
• Django entry point: facialrecognition/manage.py
• Media uploads: facialrecognition/facialrecognition/media/
• Face models: facialrecognition/models/

Install

From the repo root:

python3 -m pip install -r requirements.txt

Run The Project

From the repo root:

python3 facialrecognition/manage.py migrate
python3 facialrecognition/manage.py runserver

Then open:

• http://127.0.0.1:8000/

If Port 8000 Is Already In Use

Find what is using the port:

lsof -nP -iTCP:8000 -sTCP:LISTEN

Kill that process:

kill <PID>

If it does not stop:

kill -9 <PID>

Or just run Django on another port:

python3 facialrecognition/manage.py runserver 127.0.0.1:8001

Then open:

• http://127.0.0.1:8001/

Check That It Works

python3 facialrecognition/manage.py check
python3 facialrecognition/manage.py test accounts

Media / Uploaded Images

• Registered profile images are stored on disk in facialrecognition/facialrecognition/media/images/
• Verification images used during login are not stored permanently
• Media files are now ignored by Git so your uploaded images are not pushed to GitHub

Notes

• The app uses the browser camera, not the server camera
• If camera permissions are blocked, you can upload an image instead
• The ONNX face model files are already included in facialrecognition/models/

Common Problems

1. ModuleNotFoundError

Install requirements again:

python3 -m pip install -r requirements.txt

2. Migrations are missing

Run:

python3 facialrecognition/manage.py migrate

3. Port already in use

Use the commands in the "If Port 8000 Is Already In Use" section above.

4. Camera does not open

Make sure:

• you allowed camera access in the browser
• you are using a browser that supports camera access
• or use the upload option instead

References

• Django 5.2 release notes
• OpenCV FaceDetectorYN docs
• OpenCV face recognition tutorial