A previous release had provenance metadata, but this release does not. View details.
Django DeepFace
A Django app for face recognition authentication using DeepFace and pgvector.
Features
- 🔐 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
Demo app
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.
Requirements
- 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)
Installation
- 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;"
Quick Start
- 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)
Usage
User Registration with Face
- Navigate to
/auth/profile/ - Upload up to 4 face images for better recognition accuracy
- Images are processed and stored as embeddings for fast matching
Face Login
- Navigate to
/auth/login/ - Enter your username
- Check "Use Face Login"
- Allow webcam access and capture your face
- Click "Login"
Management Commands
Add face images from a directory tree:
python manage.py add_image_tree /path/to/faces --clear
Directory structure should be:
/path/to/faces/
├── username1/
│ ├── face1.jpg
│ └── face2.jpg
└── username2/
└── face1.jpg
Configuration
Settings
# 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.3
Models
The app provides two main models:
UserProfile: Extends the User model (optional)Identity: Stores face embeddings and images
API Reference
Views
face_login: Handle face-based authenticationprofile_view: Manage user's face imagesdelete_face: Remove a specific face image
Forms
FaceLoginForm: Combined username/password/face login formFaceImageUploadForm: Face image upload form
Development
Setting up development environment
# 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
Running tests
# 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
Contributing
- 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
Security Considerations
- 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
AI-Generated Code Disclosure
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.
License
This project is licensed under the MIT License - see the LICENSE file for details.
Acknowledgments
- DeepFace for face recognition
- pgvector for similarity search
- My friends in the Django and python community for soooo... much goodness
Support
Metadata
Release files for django-deepface 0.0.7
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Loss of provenance
These files do not have provenance metadata, despite files in a prior release including this data.
We recommend further investigation before installing these files. View details.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| django_deepface-0.0.7.tar.gz | 62.3 kB | Without provenance | Details for django_deepface-0.0.7.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| django_deepface-0.0.7-py3-none-any.whl | Python 3 | none | any | Details for django_deepface-0.0.7-py3-none-any.whl |
Total release size: 129.4 kB
Release files / django_deepface-0.0.7.tar.gz
Loss of provenance
This file belongs to a release without provenance metadata, despite a prior release including this data.
We recommend further investigation before installing this file. View details.
| Download URL | django_deepface-0.0.7.tar.gz |
|---|---|
| Size | 62.3 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
c64d9aa828a3df93a2ea9e47ba9555d75665ac9340b6050138bd94c5a27fb9ef
|
|
BLAKE2b-256 checksum How to use checksums |
f88b211425fe66b63e477b4adba56df017056dd9888ff14b9b44b8fc8c88c63e
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.7.10
|
Release files / django_deepface-0.0.7-py3-none-any.whl
Loss of provenance
This file belongs to a release without provenance metadata, despite a prior release including this data.
We recommend further investigation before installing this file. View details.
| Download URL | django_deepface-0.0.7-py3-none-any.whl |
|---|---|
| Size | 67.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
9cbe156759d6d4025496902dd09f689311862f47ddb2d671dad401c83c499f8b
|
|
BLAKE2b-256 checksum How to use checksums |
1391e9ae7466315dde89201c4db2b662cee5ac9a1fa168f29bb7b847e3e55e25
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.7.10
|
Security for django-deepface 0.0.7
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Loss of provenance
A previous release of these files had provenance metadata, but this release does not.
While this could reflect a routine change by the project maintainers, it may also indicate that the release files have been compromised.
Release comparison
- Removed 0.0.5 2 files With provenance
- Added 0.0.7 2 files Without provenance
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.