{"id":8432,"library":"plyer","title":"Plyer","description":"Plyer is a platform-independent Python API that provides a unified interface for accessing hardware features and platform-dependent functionalities across various operating systems, including Android, iOS, macOS, Linux, and Windows. It is actively managed by the Kivy Team and, while suitable for Kivy applications, can be used independently. The library wraps existing platform-specific APIs and often leverages external tools like PyJNIus for Android and PyObjus for iOS/macOS to achieve its cross-platform compatibility. The current version is 2.1.0, with ongoing development and maintenance by the Kivy community.","status":"active","version":"2.1.0","language":"en","source_language":"en","source_url":"https://github.com/kivy/plyer","tags":["cross-platform","API wrapper","mobile","desktop","hardware access","kivy","notifications"],"install":[{"cmd":"pip install plyer","lang":"bash","label":"Standard Installation"},{"cmd":"pip install plyer[tests]","lang":"bash","label":"Installation with Test Dependencies"}],"dependencies":[{"reason":"Required for accessing Java APIs on Android platforms.","package":"pyjnius","optional":true},{"reason":"Required for accessing Objective-C APIs on iOS/macOS platforms.","package":"pyobjus","optional":true},{"reason":"Often used with Kivy apps, though Plyer can be used independently.","package":"kivy","optional":true}],"imports":[{"note":"Imports the notification facade, providing cross-platform desktop and mobile notifications.","symbol":"notification","correct":"from plyer import notification"},{"note":"Imports the GPS facade for location services. Note that GPS requires platform-specific permissions on mobile.","symbol":"gps","correct":"from plyer import gps"},{"note":"Imports the battery facade to access battery status and information.","symbol":"battery","correct":"from plyer import battery"},{"note":"Imports the filechooser facade for native file dialogs.","symbol":"filechooser","correct":"from plyer import filechooser"}],"quickstart":{"code":"from plyer import notification\nimport time\n\nif __name__ == '__main__':\n    print(\"Sending desktop notification...\")\n    try:\n        notification.notify(\n            title='Hello from Plyer!',\n            message='This is a cross-platform notification example.',\n            app_name='Plyer Quickstart',\n            # app_icon='path/to/icon.ico', # On Windows, must be .ico format\n            timeout=5  # Notification will disappear after 5 seconds\n        )\n        print(\"Notification sent. Check your system tray.\")\n    except Exception as e:\n        print(f\"Failed to send notification: {e}\")\n        print(\"Ensure your system supports desktop notifications and any backend dependencies are met.\")\n\n    # Example for a mobile-focused feature (conceptual, won't run on desktop without backend)\n    # from plyer import battery\n    # try:\n    #     info = battery.status\n    #     print(f\"Battery Status: {info['percent']}% {'(charging)' if info['isCharging'] else ''}\")\n    # except Exception as e:\n    #     print(f\"Could not get battery info: {e}\")","lang":"python","description":"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."},"warnings":[{"fix":"Always 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.","message":"Not 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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"For 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.","message":"When 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`).","severity":"breaking","affected_versions":"All versions, especially when migrating from desktop-only to mobile development."},{"fix":"Familiarize 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.","message":"Some 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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Verify 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.","cause":"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.","error":"AttributeError: 'NoneType' object has no attribute 'notify' (or similar for other features)"},{"fix":"Convert 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.","cause":"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.","error":"Notifications do not appear on Windows or have a generic icon."},{"fix":"For 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.","cause":"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).","error":"GPS/Camera/Vibrator features are not working on Android/iOS."}]}