Skip to main content
Loss of provenance

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.

PyPI version Python Support Django Support License: MIT AI-assisted

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

  1. Install the package (recommended with uv):
# Using uv (recommended)
uv pip install django-deepface

# Or using pip
pip install django-deepface
  1. 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
  1. Install tf-keras (required for TensorFlow 2.19.0+):
uv pip install tf-keras
# or
pip install tf-keras
  1. 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

  1. Add django_deepface to your INSTALLED_APPS:
INSTALLED_APPS = [
    ...
    'django_deepface',
    ...
]
  1. 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',
    }
}
  1. Add URL patterns:
from django.urls import path, include

urlpatterns = [
    ...
    path('auth/', include('django_deepface.urls')),
    ...
]
  1. Run migrations:
python manage.py migrate django_deepface
  1. Configure media files settings:
MEDIA_URL = '/media/'
MEDIA_ROOT = BASE_DIR / 'media'
  1. 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

  1. Navigate to /auth/profile/
  2. Upload up to 4 face images for better recognition accuracy
  3. Images are processed and stored as embeddings for fast matching

Face Login

  1. Navigate to /auth/login/
  2. Enter your username
  3. Check "Use Face Login"
  4. Allow webcam access and capture your face
  5. 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 authentication
  • profile_view: Manage user's face images
  • delete_face: Remove a specific face image

Forms

  • FaceLoginForm: Combined username/password/face login form
  • FaceImageUploadForm: 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

  1. Fork the repository
  2. Create your feature branch (git checkout -b feature/amazing-feature)
  3. Commit your changes (git commit -m 'Add some amazing feature')
  4. Push to the branch (git push origin feature/amazing-feature)
  5. 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)

Source distribution for django-deepface 0.0.7
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)

Table of built distributions (wheels) for django-deepface 0.0.7
File Interpreter ABI Platform Actions
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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page