aioapns is an efficient and asynchronous APNs (Apple Push Notification service) client library for Python, built on asyncio. It allows developers to send push notifications to iOS, macOS, watchOS, and tvOS devices. The current version is 4.0, and it generally follows a moderate release cadence, with major versions introducing significant changes.
Install & Compatibility
Where this runs
tested against v4.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
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 1.094s · 36.4MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 2.7s · import 1.113s · 37MB
35MB installed
● package 35MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
APNs
✓ from aioapns import APNs
NotificationRequest
✓ from aioapns import NotificationRequest
This quickstart demonstrates how to initialize the APNs client and send a simple push notification using an asynchronous context. It requires your APNs authentication key content, key ID, team ID, app bundle ID, and a device token. Remember to use the `use_sandbox=False` for production environments.
import asyncio
import os
from aioapns import APNs, NotificationRequest
async def main():
# Ensure you have these environment variables set or replace with actual values
# APNS_KEY_CONTENT: The content of your .p8 private key file (NOT the path)
# APNS_KEY_ID: Your 10-character key ID from Apple Developer website
# APNS_TEAM_ID: Your 10-character Team ID from Apple Developer website
# APNS_TOPIC: Your app's bundle ID (e.g., com.example.app)
# APNS_DEVICE_TOKEN: A valid device token obtained from an iOS/macOS device
key_content = os.environ.get('APNS_KEY_CONTENT', '-----BEGIN PRIVATE KEY-----\nYOUR_P8_KEY_CONTENT_HERE\n-----END PRIVATE KEY-----')
key_id = os.environ.get('APNS_KEY_ID', 'YOUR_KEY_ID')
team_id = os.environ.get('APNS_TEAM_ID', 'YOUR_TEAM_ID')
topic = os.environ.get('APNS_TOPIC', 'com.example.app')
device_id = os.environ.get('APNS_DEVICE_TOKEN', 'your_device_token_here')
if 'YOUR_P8_KEY_CONTENT_HERE' in key_content or 'YOUR_KEY_ID' == key_id or 'YOUR_TEAM_ID' == team_id or 'com.example.app' == topic or 'your_device_token_here' == device_id:
print("Please set APNS_KEY_CONTENT, APNS_KEY_ID, APNS_TEAM_ID, APNS_TOPIC, and APNS_DEVICE_TOKEN environment variables or replace placeholders in the code.")
return
try:
apns_client = APNs(
key=key_content, # For v4.0+, this is the key content (string), not a path
key_id=key_id,
team_id=team_id,
topic=topic,
use_sandbox=True, # Set to False for production environment
)
request = NotificationRequest(
device_id=device_id,
message={
'aps': {
'alert': 'Hello from aioapns!',
'sound': 'default',
'badge': 1
},
'custom_data': 'some_value'
}
)
response = await apns_client.send_notification(request)
if response.is_successful:
print(f"Notification successfully sent to {device_id}!")
else:
print(f"Failed to send notification. Status: {response.status}, Reason: {response.reason}")
except Exception as e:
print(f"An error occurred: {e}")
if __name__ == '__main__':
asyncio.run(main())
Debug
Known issues
breakingIn v4.0, the `key` argument for `APNs` and `APNsKeyConnectionPool` classes changed from expecting a file path to expecting the *content* of the .p8 private key file as a string. Passing a path will now cause errors.fixIf upgrading from v3.x, read your `.p8` key file into a string and pass the string content to the `key` argument instead of the file path. Example: `key=Path('key.p8').read_text()` affects: 4.0.0+
breakingSupport for Python 3.6 and 3.7 was dropped in v3.2. Attempting to use aioapns v3.2 or newer with these Python versions will result in compatibility issues or installation failures.fixUpgrade your Python environment to 3.8 or newer to ensure compatibility.
affects: 3.2.0+
gotchaEarlier versions (prior to v3.0) had a known issue with deadlocks following timeouts. While fixed in v3.0, users on older versions might experience unresponsiveness under certain network conditions.fixUpgrade to v3.0 or later to benefit from deadlock fixes and improved stability.
affects: 1.x - 2.x
gotchaThe `h2` library is a critical underlying dependency for HTTP/2 communication. While `aioapns` specifies `h2>=4.0.0`, conflicts with other libraries that might pin older `h2` versions can lead to unexpected behavior or runtime errors.fixEnsure your environment's `h2` package meets or exceeds the required version, and resolve any dependency conflicts if other libraries require an older version (consider virtual environments).
affects: All versions requiring h2>=4.0.0
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'aioapns'
The 'aioapns' package is not installed in the Python environment.
fixInstall the package using pip: 'pip install aioapns'.
ImportError: cannot import name 'APNs' from 'aioapns'
The import statement is incorrect or the 'APNs' class has been renamed or removed in the current version.
fixUse the correct import statement: 'from aioapns import APNs'.
TypeError: send_notification() missing 1 required positional argument: 'request'
The 'send_notification' method was called without the required 'request' argument.
fixEnsure that 'send_notification' is called with a 'NotificationRequest' object: 'await apns.send_notification(request)'.
ValueError: Invalid device token
The device token provided is invalid or does not match the environment (sandbox or production).
fixVerify that the device token is correct and corresponds to the appropriate environment.
ssl.SSLError: [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed
The SSL certificate verification failed, possibly due to an expired or invalid certificate.
fixEnsure that the APNs certificate is valid and correctly configured.
Audit
Dependencies
h2requiredRequired for HTTP/2 communication with APNs. Version 4.0.0 or newer is required.