Install & Compatibility
Where this runs
tested against v2.1.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.940 runs
installs and imports cleanly · install 0.0s · import 0.012s · 19.2MB
glibcpy 3.10–3.940 runs
installs and imports cleanly · install 1.6s · import 0.010s · 20MB
17MB installed
● package 17MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
notification
✓ from plyer import notification
Imports the notification facade, providing cross-platform desktop and mobile notifications.
gps
✓ from plyer import gps
Imports the GPS facade for location services. Note that GPS requires platform-specific permissions on mobile.
battery
✓ from plyer import battery
Imports the battery facade to access battery status and information.
filechooser
✓ from plyer import filechooser
Imports the filechooser facade for native file dialogs.
This quickstart demonstrates how to send a simple desktop notification using Plyer. The `notification.notify()` method is cross-platform, though specific parameters like `app_icon` may have platform-dependent requirements (e.g., `.ico` format on Windows). It also includes commented-out conceptual code for a mobile-focused feature like battery status, highlighting Plyer's broader capabilities beyond desktop.
from plyer import notification
import time
if __name__ == '__main__':
print("Sending desktop notification...")
try:
notification.notify(
title='Hello from Plyer!',
message='This is a cross-platform notification example.',
app_name='Plyer Quickstart',
# app_icon='path/to/icon.ico', # On Windows, must be .ico format
timeout=5 # Notification will disappear after 5 seconds
)
print("Notification sent. Check your system tray.")
except Exception as e:
print(f"Failed to send notification: {e}")
print("Ensure your system supports desktop notifications and any backend dependencies are met.")
# Example for a mobile-focused feature (conceptual, won't run on desktop without backend)
# from plyer import battery
# try:
# info = battery.status
# print(f"Battery Status: {info['percent']}% {'(charging)' if info['isCharging'] else ''}")
# except Exception as e:
# print(f"Could not get battery info: {e}")
Debug
Known issues
gotchaNot all Plyer APIs are available or fully functional on every platform. For instance, GPS features are primarily for mobile, and some desktop functionalities might be limited.fixAlways check the official Plyer documentation for the specific API you intend to use and its platform support matrix. Implement fallback logic for unsupported platforms or features.
affects: All versions
breakingWhen building for mobile platforms like Android or iOS, `plyer` often requires platform-specific backend libraries (e.g., PyJNIus for Android, PyObjus for iOS/macOS). These are not installed automatically with `pip install plyer` and must be managed by your mobile build toolchain (e.g., `python-for-android`, `kivy-ios`).fixFor Android, add `plyer` to your `buildozer.spec` requirements. For iOS, use `python ./toolchain.py pip install plyer` within your Kivy-iOS directory. Refer to the respective build tool documentation for details.
affects: All versions, especially when migrating from desktop-only to mobile development.
gotchaSome features, particularly sensor-related ones like GPS, are asynchronous and require callbacks to retrieve data. Users expecting immediate, synchronous results may encounter issues or incorrect usage patterns.fixFamiliarize yourself with the callback pattern for asynchronous APIs (e.g., `gps.configure(on_location=...)`, `gps.start()`). Do not expect `gps.get_location()` to block and return immediately.
affects: All versions
Errors
Common errors & fixes
AttributeError: 'NoneType' object has no attribute 'notify' (or similar for other features)
This error typically occurs when Plyer fails to load a backend for the requested API on the current platform, often because the feature is not supported or a necessary underlying system component is missing.
fixVerify that the feature you are trying to use is supported on your operating system. For desktop notifications on Linux, ensure a notification daemon (e.g., `dunst`, `notification-daemon`) is running. For mobile, ensure all required permissions and backend libraries (e.g., PyJNIus, PyObjus) are correctly configured in your mobile build environment.
Notifications do not appear on Windows or have a generic icon.
On Windows, the `app_icon` parameter for `notification.notify()` specifically requires a path to an `.ico` file. Using other image formats (e.g., `.png`, `.jpg`) will result in no icon or a default system icon.
fixConvert your application icon to the `.ico` format and provide the absolute path to this `.ico` file in the `app_icon` parameter. Ensure the path is accessible to the application.
GPS/Camera/Vibrator features are not working on Android/iOS.
Mobile operating systems require explicit permissions from the user for accessing hardware features like GPS, camera, or vibrator. These permissions must be declared in your application's manifest (Android) or `Info.plist` (iOS).
fixFor Android, add relevant permissions (e.g., `android.permission.ACCESS_FINE_LOCATION`, `android.permission.CAMERA`, `android.permission.VIBRATE`) to your `buildozer.spec` file. For iOS, specify privacy-related keys (e.g., `NSLocationWhenInUseUsageDescription`) in your `Info.plist` via `kivy-ios` or directly.
Upgrade
Version history
2.1.0latest on PyPI · released Nov 12, 2022
Audit
Dependencies
pyjniusoptionalRequired for accessing Java APIs on Android platforms.
pyobjusoptionalRequired for accessing Objective-C APIs on iOS/macOS platforms.
kivyoptionalOften used with Kivy apps, though Plyer can be used independently.