{"id":869,"library":"google-cloud-firestore","title":"Google Cloud Firestore Python Client","description":"The `google-cloud-firestore` client library provides a Pythonic interface for interacting with Google Cloud Firestore. Firestore is a fully-managed, scalable NoSQL document database for mobile, web, and server development, offering real-time data synchronization and offline support. It is currently at version 2.26.0 and receives regular updates as part of the broader `google-cloud-python` client libraries.","status":"active","version":"2.26.0","language":"python","source_language":"en","source_url":"https://github.com/googleapis/google-cloud-python/tree/main/packages/google-cloud-firestore","tags":["google-cloud","firestore","nosql","database","serverless","firebase"],"install":[{"cmd":"pip install --upgrade google-cloud-firestore","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Required for gRPC transport by the Firestore API; often a transitive dependency but can cause ImportError if not present or incorrectly installed.","package":"grpcio","optional":false}],"imports":[{"note":"Use `google.cloud.firestore` for direct Google Cloud Firestore API access. `firebase_admin.firestore` is part of the Firebase Admin SDK, which has different use cases and authentication flows, though it internally uses `google-cloud-firestore`.","wrong":"import firebase_admin.firestore\ndb = firebase_admin.firestore.client()","symbol":"firestore.Client","correct":"from google.cloud import firestore\ndb = firestore.Client()"}],"quickstart":{"code":"import os\nfrom google.cloud import firestore\n\n# Ensure GOOGLE_APPLICATION_CREDENTIALS environment variable is set\n# e.g., export GOOGLE_APPLICATION_CREDENTIALS=\"/path/to/your/service_account_key.json\"\n# Or set programmatically (less secure for production):\n# from google.oauth2 import service_account\n# credentials = service_account.Credentials.from_service_account_file('path/to/your/service_account_key.json')\n# db = firestore.Client(credentials=credentials)\n\ndef quickstart_firestore():\n    # Initialize Firestore DB client. It automatically uses Application Default Credentials.\n    # Make sure you have created a Firestore database in your GCP project first.\n    db = firestore.Client()\n\n    # Add a new document to a collection 'users'\n    doc_ref = db.collection('users').document('alovelace')\n    doc_ref.set({\n        'first': 'Ada',\n        'last': 'Lovelace',\n        'born': 1815\n    })\n    print(f\"Added document: {doc_ref.id}\")\n\n    # Read a single document\n    doc = doc_ref.get()\n    if doc.exists:\n        print(f\"Document data: {doc.to_dict()}\")\n    else:\n        print(\"No such document!\")\n\n    # Query for documents\n    users_ref = db.collection('users')\n    docs = users_ref.where('born', '<', 1900).stream()\n    print(\"Users born before 1900:\")\n    for doc in docs:\n        print(f\"{doc.id} => {doc.to_dict()}\")\n\nif __name__ == '__main__':\n    # Placeholder for environment variable setup for local testing\n    # In production environments (e.g., GCE, Cloud Functions), credentials are often auto-discovered.\n    if not os.environ.get('GOOGLE_APPLICATION_CREDENTIALS'):\n        print(\"WARNING: GOOGLE_APPLICATION_CREDENTIALS environment variable not set. \"\n              \"Using default credentials if available, or client might fail.\")\n    quickstart_firestore()","lang":"python","description":"This quickstart demonstrates how to initialize the Firestore client, add a new document to a collection, retrieve a single document, and perform a basic query for documents. It assumes 'Application Default Credentials' are set up (e.g., via `gcloud auth application-default login` or by setting the `GOOGLE_APPLICATION_CREDENTIALS` environment variable to a service account key file path)."},"warnings":[{"fix":"Review the 2.0.0 migration guide in the official documentation. The library may ship `fixup_firestore_v1_keywords.py` and `fixup_firestore_admin_v1_keywords.py` scripts to assist with code modification.","message":"Version 2.0.0 introduced significant interface changes due to a next-gen code generator. Method calls shifted from positional/keyword parameters to a single `request` parameter. Code using `google.cloud.firestore_v1.gapic` namespaces will likely be incompatible. Python 3.6+ became a hard requirement.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Ensure that Application Default Credentials are valid and up-to-date. For local development, run `gcloud auth application-default login` regularly. For production, ensure service account permissions and key validity.","message":"The Firestore client can hang indefinitely on authentication errors, especially when local `gcloud CLI` authentication tokens expire. This can manifest as scripts freezing without clear error messages.","severity":"gotcha","affected_versions":"All versions"},{"fix":"When encountering index errors, follow the link provided in the error message to the Firebase/Google Cloud console to create the necessary composite index. Plan for index creation during development for complex queries.","message":"Queries involving multiple fields or specific operators (like `array-contains-any`, `in`) often require a composite index to be created in the Firestore console. Failing to do so results in a `FailedPrecondition: 400 The query requires an index` error at runtime.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Choose the appropriate library based on your project's needs: `google-cloud-firestore` for direct Google Cloud integration, `firebase-admin` for projects heavily leveraging Firebase services (Authentication, Realtime Database, etc.).","message":"Confusing `google-cloud-firestore` with `firebase-admin`. While `firebase-admin` internally uses `google-cloud-firestore` for its Firestore interactions, they serve different purposes. `google-cloud-firestore` is the lower-level client for general GCP projects, while `firebase-admin` is tailored for Firebase-specific services and authentication, particularly for server-side code in a Firebase project.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure your Python environment is running Python 3.7 or higher. For new projects, consider Python 3.10+ for better forward compatibility.","message":"Support for older Python versions is progressively dropped. As of `firebase-admin` v7.0.0, Python 3.7 and 3.8 were dropped, and 3.9 was deprecated. `google-cloud-firestore` itself requires Python >= 3.7.","severity":"deprecated","affected_versions":"<3.7"}],"env_vars":null,"last_verified":"2026-05-12T20:34:28.882Z","next_check":"2026-06-29T00:00:00.000Z","problems":[{"fix":"Ensure the library is installed using pip: `pip install google-cloud-firestore`. If the issue persists, try upgrading pip and setuptools, or reinstalling `grpcio`: `pip install --upgrade pip setuptools` then `pip install --no-cache-dir --force-reinstall -Iv grpcio==1.45.0` (adjust grpcio version as needed).","cause":"The `google-cloud-firestore` library, or one of its dependencies, is not correctly installed or is not accessible in the current Python environment.","error":"ModuleNotFoundError: No module named 'google.cloud.firestore' OR ImportError: Failed to import the Cloud Firestore library for Python."},{"fix":"To create or update a document, first get a `DocumentReference` using `.document('document_id')`. For example, `db.collection('my_collection').document('my_doc').set({'field': 'value'})`. To add a new document with an auto-generated ID to a collection, use `.add()`: `db.collection('my_collection').add({'field': 'value'})`. For ordering, use `order_by()` instead of `orderBy`.","cause":"You are attempting to use a method meant for a `DocumentReference` (like `set()`) or using an incorrect method name on a `CollectionReference` object. `CollectionReference` objects manage collections, while `DocumentReference` objects manage individual documents. Also, method names often use underscores in Python (e.g., `order_by` instead of `orderBy`).","error":"AttributeError: 'CollectionReference' object has no attribute 'set' (or 'doc', 'orderBy', 'stream')"},{"fix":"Always check if the `DocumentSnapshot` object `exists` before attempting to access its data. For example: `doc_ref = db.collection('users').document('user_id')`; `doc_snapshot = doc_ref.get()`; `if doc_snapshot.exists: print(doc_snapshot.to_dict()) else: print('Document not found.')`.","cause":"This error typically occurs when you call `.get()` on a `DocumentReference`, but the document does not exist in Firestore. In such cases, `DocumentReference.get()` returns `None`, and subsequent attempts to access attributes like `to_dict()` or `exists` on `None` will raise this error.","error":"AttributeError: 'NoneType' object has no attribute 'to_dict' (or 'get', 'exists')"},{"fix":"Ensure your environment is authenticated correctly. For local development, set the `GOOGLE_APPLICATION_CREDENTIALS` environment variable to the path of your service account JSON key file. For deployment on Google Cloud (e.g., Cloud Functions, App Engine), ensure the service account associated with the environment has the appropriate Firestore roles (e.g., 'Cloud Datastore User').","cause":"Your application lacks the necessary authentication credentials or IAM permissions to access the Firestore database. This can happen if service account keys are misconfigured, environment variables (like `GOOGLE_APPLICATION_CREDENTIALS`) are not set, or the assigned service account does not have the 'Cloud Datastore User' or 'Cloud Datastore Owner' role.","error":"google.api_core.exceptions.PermissionDenied: 403 Missing or insufficient permissions. OR google.auth.exceptions.DefaultCredentialsError: Your default credentials were not found."}],"ecosystem":"pypi","meta_description":null,"install_score":95,"install_tag":"verified","quickstart_score":null,"quickstart_tag":null,"pypi_latest":"2.27.0","cli_name":"","cli_version":null,"install_checks":{"last_tested":"2026-05-12","tag":"verified","tag_description":"installs cleanly on critical runtimes, fast import, recently tested","installed_version":"2.27.0","pypi_latest":"2.27.0","is_stale":false,"results":[{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"--upgrade","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"noisy","install_time_s":null,"import_time_s":1.92,"mem_mb":28,"disk_size":"72.7M"},{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"--upgrade","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":1.83,"mem_mb":27.5,"disk_size":"71.5M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"--upgrade","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"noisy","install_time_s":6.2,"import_time_s":1.12,"mem_mb":23.1,"disk_size":"71M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"--upgrade","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":1.36,"mem_mb":22.6,"disk_size":"69M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"--upgrade","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":null,"import_time_s":2.42,"mem_mb":30,"disk_size":"77.9M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"--upgrade","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":2.87,"mem_mb":29.5,"disk_size":"76.6M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"--upgrade","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":5.3,"import_time_s":1.63,"mem_mb":25.6,"disk_size":"76M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"--upgrade","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":1.58,"mem_mb":25.1,"disk_size":"74M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"--upgrade","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":null,"import_time_s":2.54,"mem_mb":29.7,"disk_size":"69.3M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"--upgrade","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":2.8,"mem_mb":29.3,"disk_size":"68.0M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"--upgrade","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":4.5,"import_time_s":2.01,"mem_mb":25.4,"disk_size":"67M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"--upgrade","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":2.05,"mem_mb":24.9,"disk_size":"66M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"--upgrade","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":null,"import_time_s":2.34,"mem_mb":30.2,"disk_size":"68.9M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"--upgrade","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":2.62,"mem_mb":29.8,"disk_size":"67.6M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"--upgrade","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":4.6,"import_time_s":1.89,"mem_mb":25.7,"disk_size":"67M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"--upgrade","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":2.1,"mem_mb":25.4,"disk_size":"65M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"--upgrade","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"noisy","install_time_s":null,"import_time_s":1.77,"mem_mb":28.1,"disk_size":"72.8M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"--upgrade","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":1.66,"mem_mb":27.7,"disk_size":"71.6M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"--upgrade","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"noisy","install_time_s":6.8,"import_time_s":1.27,"mem_mb":23.2,"disk_size":"71M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"--upgrade","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":1.17,"mem_mb":22.9,"disk_size":"69M"}]},"quickstart_checks":{"last_tested":"2026-04-24","tag":null,"tag_description":null,"results":[{"runtime":"python:3.10-alpine","exit_code":1},{"runtime":"python:3.10-slim","exit_code":1},{"runtime":"python:3.11-alpine","exit_code":1},{"runtime":"python:3.11-slim","exit_code":1},{"runtime":"python:3.12-alpine","exit_code":1},{"runtime":"python:3.12-slim","exit_code":1},{"runtime":"python:3.13-alpine","exit_code":1},{"runtime":"python:3.13-slim","exit_code":1},{"runtime":"python:3.9-alpine","exit_code":1},{"runtime":"python:3.9-slim","exit_code":1}]}}