Registry / web-framework / django-push-notifications

django-push-notifications

JSON →
library3.3.0pypypiunverified

django-push-notifications is a Django library for sending push notifications to mobile devices via services like FCM (Firebase Cloud Messaging), APNS (Apple Push Notification service), and to WebPush-enabled browsers (Chrome, Firefox, Opera). It simplifies device registration and message sending within a Django project. The current version is 3.3.0, and the project maintains an active release cadence with regular updates.

pip install django-push-notifications
INSTALL
IMPORT
SIG · DJANGO-PUSH-NOTIFI
D
django-push-notifications
web-frameworkpythonv3.3.0
Install
3.5s avg
Import
Disk
66MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v3.3.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.920 runs
installs and imports cleanly · install 0.0s · import 0.000s · 66.7MB
glibc
py 3.103.920 runs
installs and imports cleanly · install 3.5s · import 0.000s · 67MB
66MB installed
● package 66MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

GCMDevice
from push_notifications.models import GCMDevice
from push_notifications.models import GCMDevice

This quickstart demonstrates how to configure settings, register devices, and send notifications using both FCM (Firebase Cloud Messaging, via GCMDevice) and APNS (Apple Push Notification service) models. Note: The `settings.configure` and `apps.populate` lines are for running this example script standalone. In a typical Django project, you'd configure `settings.py` and then directly import and use the device models.

import os from django.conf import settings from django.apps import apps from push_notifications.models import GCMDevice, APNSDevice # --- Minimal Django settings for standalone execution --- # In a real Django project, these settings would be in your settings.py # and you would simply import and use the Device models after Django is initialized. if not apps.ready: settings.configure( INSTALLED_APPS=[ 'django.contrib.auth', 'django.contrib.contenttypes', 'push_notifications' ], # Minimal database settings for demo DATABASES={'default': {'ENGINE': 'django.db.backends.sqlite3', 'NAME': ':memory:'}}, PUSH_NOTIFICATIONS_SETTINGS={ "APNS_AUTH_KEY_PATH": os.environ.get("APNS_AUTH_KEY_PATH", "/path/to/apns_key.p8"), "APNS_AUTH_KEY_ID": os.environ.get("APNS_AUTH_KEY_ID", "YOUR_APNS_KEY_ID"), "APNS_TEAM_ID": os.environ.get("APNS_TEAM_ID", "YOUR_APNS_TEAM_ID"), "APNS_APP_ID": os.environ.get("APNS_APP_ID", "com.example.app"), "GCM_API_KEY": os.environ.get("GCM_API_KEY", "YOUR_LEGACY_FCM_SERVER_KEY"), # For legacy GCM "FCM_API_KEY": os.environ.get("FCM_API_KEY", "/path/to/fcm_v1_credentials.json"), # For FCM v1 }, DEFAULT_AUTO_FIELD='django.db.models.BigAutoField', # Recommended for Django 3.2+ ) apps.populate(settings.INSTALLED_APPS) # --- End of minimal Django settings --- print("Registering a GCM (FCM) device and sending a message...") # Replace 'your_fcm_device_token' with an actual device token device_gcm, created_gcm = GCMDevice.objects.get_or_create( registration_id="your_fcm_device_token", active=True, user=None # Link to a Django User object if applicable ) if created_gcm: print(f"Created new GCM device: {device_gcm}") else: print(f"Found existing GCM device: {device_gcm}") try: response_gcm = device_gcm.send_message( "Hello from FCM!", badge=1, extra={"custom_data": "value"} ) print(f"FCM message sent. Response: {response_gcm}") except Exception as e: print(f"Error sending FCM message: {e}") print("\nRegistering an APNS device and sending a message...") # Replace 'your_apns_device_token' with an actual device token device_apns, created_apns = APNSDevice.objects.get_or_create( registration_id="your_apns_device_token", active=True, user=None ) if created_apns: print(f"Created new APNS device: {device_apns}") else: print(f"Found existing APNS device: {device_apns}") try: response_apns = device_apns.send_message( message="Hello from APNS!", badge=1, sound="default", category="my_category", mutable_content=1, # Note: integer 1 or 0 for >=3.2.1 extra={"custom_data": "value"} ) print(f"APNS message sent. Response: {response_apns}") except Exception as e: print(f"Error sending APNS message: {e}") # For WebPush, you would typically handle subscription via JavaScript in the frontend # and then create/use a WebPushDevice instance similarly to send notifications.
Debug
Known issues
breakingThe `aioapns` dependency was pinned to `<4.0` in `django-push-notifications` version 3.3.0 to prevent breaking changes introduced in `aioapns` v4. If you have `aioapns` v4 installed, this could lead to import errors or unexpected behavior.
fix
Ensure `aioapns` is installed at a version less than 4.0. You may need to reinstall `django-push-notifications` to get the correct transitive dependency (`pip install -U django-push-notifications`).
affects: >=3.3.0
breakingThe `mutable_content` field type for APNS messages changed from boolean `True` to integer `1` (or `0` for `False`) in version 3.2.1. Passing a boolean will raise a `TypeError`.
fix
Update your APNS send calls to pass `mutable_content=1` instead of `mutable_content=True` (or `mutable_content=0` instead of `mutable_content=False`).
affects: >=3.2.1
gotchaVersion 3.3.0 introduced an explicit Django `AppConfig` and sets `default_auto_field`. For older Django versions (pre-3.2) or custom configurations, you might encounter `AutoField` related warnings if `DEFAULT_AUTO_FIELD` is not explicitly set in your Django project.
fix
It is best practice to ensure `DEFAULT_AUTO_FIELD` is set in your Django `settings.py` (e.g., `DEFAULT_AUTO_FIELD = 'django.db.models.BigAutoField'`) for Django 3.2+ projects.
affects: All
deprecatedFCM v1 API support was added in version 3.1.0. The legacy GCM API is deprecated by Google and may be removed in future `django-push-notifications` versions. It is highly recommended to migrate to FCM v1.
fix
Configure `PUSH_NOTIFICATIONS_SETTINGS` to use `FCM_API_KEY` with your Firebase service account credentials for FCM v1. Consult the official documentation for detailed FCM v1 setup instructions.
affects: >=3.1.0
breakingSupport for Python versions less than 3.4 was dropped in version 1.4.0. The library currently requires Python 3.7+.
fix
Ensure your project runs on Python 3.7 or newer before upgrading to recent versions of `django-push-notifications`.
affects: <1.4.0
Upgrade
Version history
3.3.0latest on PyPI · released Nov 16, 2025
Audit
Dependencies
firebase-adminoptionalOptional, required for FCM v1 API.
aioapnsrequiredRequired for APNS (async). Pinned to <4.0 in version 3.3.0 due to breaking changes in aioapns v4.
Agent activity
19 hits · last 30 days
node
18
OpenAI (training)
1
Resources
django-push-notifications — pip install django-push-notifications · libregistry