A Django app for face recognition authentication using DeepFace and pgvector.
- 🔐 Face recognition authentication alongside traditional password authentication
- 📸 Capture face images via webcam or file upload
- 🚀 Fast face matching using pgvector similarity search
- 👤 Support for multiple face images per user (up to 4)
- 🎨 Modern, responsive UI with Bootstrap 5
- 🔒 Secure storage and processing of biometric data
There is a demo app that shows how you can get started with this library. The app adds the ability to count successful use of image upload, storing the browser agent string for analysis. This helps check if users in your company can use image capture and on what devices, before making the decision to implement it.
- Python 3.8+ (less than 3.12 due to tensorflow wheels and instruction set issues)
- Django 4.2+
- PostgreSQL with pgvector extension
- A working webcam (for face capture features)
- Install the package (recommended with uv):
# Using uv (recommended)
uv pip install django-deepface
# Or using pip
pip install django-deepface- Install system dependencies for face recognition:
# On Ubuntu/Debian
sudo apt-get update
sudo apt-get install -y libgl1-mesa-glx libglib2.0-0
sudo apt-get install -y libhdf5-dev libhdf5-serial-dev
sudo apt-get install -y python3-h5py
sudo apt-get install -y libopenblas-dev
# On macOS
brew install cmake
brew install hdf5- Install tf-keras (required for TensorFlow 2.19.0+):
uv pip install tf-keras
# or
pip install tf-keras- Set up PostgreSQL with pgvector:
# Install pgvector extension
sudo apt-get install postgresql-14-pgvector # Adjust version as needed
# Create extension in your database
psql -U postgres -d your_database -c "CREATE EXTENSION IF NOT EXISTS vector;"- Add
django_deepfaceto yourINSTALLED_APPS:
INSTALLED_APPS = [
...
'django_deepface',
...
]- Configure your database to use PostgreSQL:
DATABASES = {
'default': {
'ENGINE': 'django.db.backends.postgresql',
'NAME': 'your_database',
'USER': 'your_user',
'PASSWORD': 'your_password',
'HOST': 'localhost',
'PORT': '5432',
}
}- Add URL patterns:
from django.urls import path, include
urlpatterns = [
...
path('auth/', include('django_deepface.urls')),
...
]- Run migrations:
python manage.py migrate django_deepface- Configure media files settings:
MEDIA_URL = '/media/'
MEDIA_ROOT = BASE_DIR / 'media'- Add media URL patterns (development only):
from django.conf import settings
from django.conf.urls.static import static
if settings.DEBUG:
urlpatterns += static(settings.MEDIA_URL, document_root=settings.MEDIA_ROOT)- Navigate to
/auth/profile/ - Upload up to 4 face images for better recognition accuracy
- Images are processed and stored as embeddings for fast matching
- Navigate to
/auth/login/ - Enter your username
- Check "Use Face Login"
- Allow webcam access and capture your face
- Click "Login"
Add face images from a directory tree:
python manage.py add_image_tree /path/to/faces --clearDirectory structure should be:
/path/to/faces/
├── username1/
│ ├── face1.jpg
│ └── face2.jpg
└── username2/
└── face1.jpg
# Maximum number of face images per user
DEEPFACE_MAX_FACES = 4
# Face recognition model (default: VGG-Face)
DEEPFACE_MODEL = "VGG-Face"
# Detection backend (default: retinaface)
DEEPFACE_DETECTOR = "retinaface"
# Similarity threshold (default: 0.3)
DEEPFACE_THRESHOLD = 0.3The app provides two main models:
UserProfile: Extends the User model (optional)Identity: Stores face embeddings and images
face_login: Handle face-based authenticationprofile_view: Manage user's face imagesdelete_face: Remove a specific face image
FaceLoginForm: Combined username/password/face login formFaceImageUploadForm: Face image upload form
# Clone the repository
git clone https://github.com/topiaruss/django-deepface.git
cd django-deepface
# Create virtual environment
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
# Install development dependencies (recommended with uv)
uv pip install -e ".[dev]"
# or
pip install -e ".[dev]"
# Run tests
pytest
# Run with coverage
pytest --cov=django_deepface# Run all tests
pytest
# Run with coverage report
pytest --cov=django_deepface --cov-report=html
# Run specific test
pytest django_deepface/tests/test_views.py::TestProfileView- Fork the repository
- Create your feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add some amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
- Face embeddings are stored as vectors, not actual images
- Always use HTTPS in production
- Consider privacy regulations (GDPR, etc.) when storing biometric data
- Implement proper access controls and audit logging
- Regular security updates for dependencies
This project includes portions of code that were generated with the assistance of large language models—specifically , Claude 3.7 Sonnet, Claude 4 Opus. These tools were used to accelerate scaffolding, explore idiomatic patterns, and propose implementations for specific challenges.
All AI-generated code has been reviewed, integrated, and tested by the author. Transparency is important: this project makes no attempt to conceal the involvement of generative AI, and welcomes scrutiny and feedback.
If you're curious about the design, want to critique the use of AI in open-source development, or have experience with similar approaches, the author invites comments and contributions from both the AI and broader developer communities.
Your insights—technical, ethical, or otherwise—are welcome.
This project is licensed under the MIT License - see the LICENSE file for details.