{"id":8482,"library":"pyfcm","title":"PyFCM - Firebase Cloud Messaging Client","description":"PyFCM is an active Python client library for Firebase Cloud Messaging (FCM), currently at version 2.1.0. It provides a convenient interface for sending push notifications and data messages to Android, iOS, and web clients. The library's release cadence is tied to significant FCM API changes, ensuring compatibility with the latest Firebase services.","status":"active","version":"2.1.0","language":"en","source_language":"en","source_url":"https://github.com/olucurious/pyfcm","tags":["fcm","firebase","push notifications","android","ios","web"],"install":[{"cmd":"pip install pyfcm","lang":"bash","label":"Install from PyPI"}],"dependencies":[{"reason":"HTTP requests to FCM API.","package":"requests","optional":false},{"reason":"Dependency of requests, requires version >=1.26.0.","package":"urllib3","optional":false},{"reason":"Required for FCM v1 API authentication using service accounts or Google OAuth2 credentials, version >=2.22.0.","package":"google-auth","optional":false},{"reason":"Used for asynchronous HTTP requests, version >=3.8.6.","package":"aiohttp","optional":false}],"imports":[{"symbol":"FCMNotification","correct":"from pyfcm import FCMNotification"}],"quickstart":{"code":"import os\nfrom pyfcm import FCMNotification\n\n# For FCM v1 API, authentication uses a service account JSON file.\n# Set GOOGLE_APPLICATION_CREDENTIALS environment variable to the path of your service account JSON file.\n# Ensure your service account has 'Firebase Cloud Messaging API' enabled and 'Firebase Cloud Messaging Sender' role.\n# A project_id is also required.\n\nservice_account_path = os.environ.get('GOOGLE_APPLICATION_CREDENTIALS', '')\nproject_id = os.environ.get('FCM_PROJECT_ID', 'your-project-id') # Replace with your Firebase Project ID\nfcm_token = os.environ.get('FCM_DEVICE_TOKEN', 'YOUR_DEVICE_REGISTRATION_ID') # Replace with a device token\n\nif not service_account_path:\n    print(\"WARNING: GOOGLE_APPLICATION_CREDENTIALS environment variable not set. Using dummy service_account_file for example.\")\n    # For a runnable example without actual auth, you might provide a non-existent path,\n    # but real usage *requires* a valid service account file.\n    # For testing, ensure you have a valid service_account_path and project_id.\n\n# Initialize FCMNotification with service account file and project ID for FCM v1 API\ntry:\n    push_service = FCMNotification(service_account_file=service_account_path, project_id=project_id)\n\n    # Send a notification message to a single device\n    notification_title = \"Test Notification\"\n    notification_body = \"This is a test message from PyFCM!\"\n\n    result = push_service.notify(\n        fcm_token=fcm_token,\n        notification_title=notification_title,\n        notification_body=notification_body\n    )\n\n    print(\"Notification sent. Result:\", result)\n\n    # Send a data message (handled by the client app)\n    data_payload = {\"score\": \"100\", \"time\": \"10:00\"}\n    data_result = push_service.notify(\n        fcm_token=fcm_token,\n        data_payload=data_payload\n    )\n    print(\"Data message sent. Result:\", data_result)\n\nexcept Exception as e:\n    print(f\"An error occurred: {e}\")","lang":"python","description":"This quickstart demonstrates how to send both notification and data messages to a single FCM device using PyFCM's `FCMNotification` class. It leverages the FCM v1 API, requiring a Firebase service account JSON file (specified via `GOOGLE_APPLICATION_CREDENTIALS` environment variable) and your Firebase project ID for authentication. The `notify()` method is the unified entry point for sending messages."},"warnings":[{"fix":"Update your code to use the new `notify()` method and configure `FCMNotification` with `service_account_file` and `project_id` (or `credentials`). Consult the `README.md` for `2.x` for updated usage patterns. Ensure your Firebase project uses the FCM v1 API and relevant permissions.","message":"Version 2.0.1 migrated to the FCM v1 HTTP API, deprecating the legacy HTTP API. This involves significant changes to method signatures and authentication. Old methods like `notify_single_device`, `notify_multiple_devices`, and `notify_topic_subscribers` were renamed to a single `notify()` method with unified parameters. Authentication now prefers Google service account credentials over a simple API key.","severity":"breaking","affected_versions":"2.0.1 and later"},{"fix":"Review the `README.md` or release notes for your specific `1.x` version to understand the exact response structure and adjust parsing logic accordingly.","message":"Prior to 2.0.1, versions like 1.4.0 and 1.2.0 introduced changes to the structure of the response dict returned by notification sending methods. Ensure your code correctly parses the `multicast_ids`, `success`, `failure`, `canonical_ids`, and `results` keys.","severity":"breaking","affected_versions":"1.2.0 - 1.4.x"},{"fix":"Obtain a service account JSON key file from your Firebase project settings (Project settings -> Service accounts -> Generate new private key). Set the `GOOGLE_APPLICATION_CREDENTIALS` environment variable to the path of this file and pass your `project_id` to `FCMNotification` initializer. Ensure the associated service account has the necessary FCM permissions.","message":"Authentication with FCM v1 API requires proper Google Cloud credentials, typically a service account key file, and the correct Firebase project ID. Using an outdated or invalid legacy 'Server Key' (API key) with PyFCM v2.x will lead to authentication failures.","severity":"gotcha","affected_versions":"2.0.1 and later"},{"fix":"For Django projects, evaluate if `fcm-django` is a better fit. If using `fcm-django`, note that it replaces `pyfcm` and requires `firebase-admin` credentials (e.g., `GOOGLE_APPLICATION_CREDENTIALS` for service account path) instead of `pyfcm`'s direct API key or service account file parameters.","message":"If you are working within a Django project, consider using `fcm-django` (a separate library) instead of `pyfcm` directly. `fcm-django` provides deeper integration with Django models and often handles authentication with `firebase-admin` (not `pyfcm`) which has its own migration path for FCM v1.","severity":"gotcha","affected_versions":"All versions (contextual)"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"For PyFCM v2.x, ensure you are using a valid Firebase service account JSON key file, that the `GOOGLE_APPLICATION_CREDENTIALS` environment variable points to it, and you've provided the correct `project_id` to `FCMNotification`. Verify the service account has the 'Firebase Cloud Messaging API' enabled and 'Firebase Cloud Messaging Sender' role. If you are on an older PyFCM version, ensure your legacy Server Key is correct.","cause":"The Firebase API key (or service account credentials) provided is invalid, missing, or lacks the necessary permissions for your project, or you are attempting to use a legacy API key with FCM v1 API.","error":"pyfcm.errors.AuthenticationError: There was an error authenticating the sender account"},{"fix":"First, check the Firebase status dashboard for any ongoing service outages. If the service is operational, ensure you have upgraded PyFCM to version 2.x to utilize the FCM v1 HTTP API, as the legacy APIs began deprecation and shutdown in 2024.","cause":"This error typically indicates an issue with the Firebase Cloud Messaging service itself or that the legacy FCM API endpoints you might be hitting (if using an older `pyfcm` version) have been shut down.","error":"FCMServerError: FCM server is temporarily unavailable"},{"fix":"Migrate your code to use the unified `push_service.notify()` method. All previous functionality is now accessed via parameters to this single method (e.g., `fcm_token` for single device, `registration_ids` for multiple, `topic_name` for topics).","cause":"You are likely using PyFCM version 2.0.1 or later, which refactored the message sending methods. The individual `notify_single_device`, `notify_multiple_devices`, and `notify_topic_subscribers` methods were removed.","error":"AttributeError: 'FCMNotification' object has no attribute 'notify_single_device'"},{"fix":"Install the library using pip: `pip install pyfcm`. If using a virtual environment, ensure it's activated before installation.","cause":"The `pyfcm` library is not installed in your current Python environment or the environment where your script is being executed.","error":"ModuleNotFoundError: No module named 'pyfcm'"}]}