Install & Compatibility
Where this runs
tested against v0.6.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
py 3.9
✕ build_error
✕ build_error
101MB installed
● package 101MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
https_fn
✓ from firebase_functions import https_fn
firestore_fn
✓ from firebase_functions import firestore_fn
options
✓ from firebase_functions import options
initialize_app
✓ from firebase_admin import initialize_app
✗ import firebase_admin; initialize_app()
You must explicitly import `firebase_admin` before calling `initialize_app()` or you will encounter a `NameError`. Ensure `firebase_admin` is also in your `requirements.txt`.
This quickstart defines a simple HTTP-triggered function that responds with a greeting. It demonstrates initializing the Firebase Admin SDK (which is automatic in Cloud Functions environments) and handling basic request parameters. To deploy, save this as `main.py` in your functions directory, add `firebase-functions` and `firebase-admin` to `requirements.txt`, and run `firebase deploy --only functions`.
import os
from firebase_functions import https_fn
from firebase_admin import initialize_app
# Initialize the Firebase Admin SDK. When deployed to Cloud Functions,
# the SDK automatically detects the environment's service account credentials.
initialize_app()
@https_fn.on_request()
def hello_world(request: https_fn.Request) -> https_fn.Response:
"""Responds to an HTTP request with a 'Hello from Python!' message."""
# Example of accessing environment variables (if any are set during deployment)
message_prefix = os.environ.get('MESSAGE_PREFIX', 'Hello')
# Check for a 'name' query parameter or use a default.
name = request.args.get('name', 'World')
return https_fn.Response(f"{message_prefix}, {name} from Python!")
Debug
Known issues
gotchaPython support for Cloud Functions for Firebase is in Public Preview. This means the functionality might change in backward-incompatible ways, is not subject to any SLA or deprecation policy, and may receive limited support.fixBe aware of potential changes and review release notes carefully. Consider stability requirements for production applications.
affects: All versions (as of 0.5.0)
breakingThe `firebase-functions` library requires Python 3.10 or higher. The `firebase-admin` SDK (a common dependency) also dropped support for Python 3.7 and 3.8, and deprecated 3.9, with version 7.0.0. Ensure your local environment and deployment runtime are on a supported Python version (3.10-3.13).fixUpdate your Python environment to Python 3.10 or newer. When deploying, ensure `runtime` is explicitly set to `python310`, `python311`, `python312`, or `python313` if not using the default (which is currently 3.13).
affects: firebase-functions >= 0.1.0, firebase-admin >= 7.0.0
gotchaWhen using `firebase-admin` within your functions, you must explicitly `import firebase_admin` (in addition to any submodules like `firebase_admin.auth`) before calling `firebase_admin.initialize_app()`. Failure to do so will result in a `NameError`. Also, ensure `firebase-admin` is listed in your `requirements.txt`.fixAlways include `import firebase_admin` at the top of your function file, even if you only use submodules. Ensure `firebase-admin` is in `requirements.txt`.
affects: All versions
gotchaTo avoid 'cold start' performance issues, reuse expensive objects (like database connections, API clients, or large data structures) by declaring them as global variables outside of your function handler. They will be initialized once per container instance, rather than on every function invocation.fixMove resource-intensive initialization code to the global scope of your `main.py` file.
affects: All versions
gotchaEnsure all Python package dependencies are correctly specified in `requirements.txt` within your functions directory. Missing or incorrect dependencies can lead to deployment failures or runtime errors in your deployed functions.fixDouble-check `requirements.txt` for all necessary packages, including `firebase-functions` and `firebase-admin`. Use `pip freeze > requirements.txt` in a clean virtual environment to capture exact versions.
affects: All versions
gotchaDeployment region needs to be explicitly specified for optimal performance and compliance. If not set, functions will deploy to the default `us-central1`. You can set a global region using `options.set_global_options(region=options.SupportedRegion.YOUR_REGION)` or per function.fixSet a global region via `options.set_global_options()` or specify `region` argument in the function decorator (e.g., `@https_fn.on_request(region='europe-west1')`).
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'firebase_functions'
The `firebase_functions` package or other required dependencies are not correctly installed in the virtual environment or are not being recognized during deployment or local emulation. This often happens if `pip install -r requirements.txt` was not run within the `functions` directory's virtual environment, or if the virtual environment is not correctly configured for Firebase to detect.
fixNavigate into your `functions` directory, activate your virtual environment (e.g., `source venv/bin/activate` on Linux/macOS or `.\venv\Scripts\activate` on Windows), and then run `pip install -r requirements.txt`. Ensure all necessary packages are listed in `requirements.txt`. If `venv` is missing, create it first using `python3 -m venv venv`.
Failed to find location of Firebase Functions SDK. Did you forget to run '. "./functions/venv/bin/activate" && python3.XX -m pip install -r requirements.txt'?
Firebase CLI is unable to locate or properly initialize the Python virtual environment and its installed dependencies, often due to an incorrect virtual environment setup, a mismatch in Python versions (e.g., expecting `python3.12` but `python3.11` is present), or the virtual environment not being created in the correct `functions` directory.
fixEnsure your virtual environment is created *inside* the `functions` directory. Activate the virtual environment and install dependencies: `cd functions && python3 -m venv venv && source venv/bin/activate && pip install -r requirements.txt`. Verify that the Python version used (`python3.XX` in the error message) matches your installed Python version, or explicitly configure the `runtime` in `firebase.json` (e.g., `'runtime': 'python311'`).
AttributeError: 'Event' object has no attribute 'after'
This error typically occurs in Firebase Firestore trigger functions (2nd gen) when trying to access `event.after` without correctly typing the `event` parameter as `firestore_fn.Event[firestore_fn.DocumentSnapshot | None]` or when incorrectly assuming the structure of the `Event` object for a particular trigger type.
fixEnsure the `event` parameter in your Firestore trigger function is correctly type-hinted and you are accessing the `data()` method if retrieving document data. For example, for an `on_document_updated` trigger, the signature should be `def my_function(event: firestore_fn.Event[firestore_fn.DocumentSnapshot | None]): updated_data = event.after.data()`.
Error: runtime field is required but was not found in firebase.json or package.json.
The Firebase CLI cannot determine the runtime for your functions because the `runtime` field is missing in your `firebase.json` file. When using Python, the runtime should be explicitly set in `firebase.json`, and `package.json` (used for Node.js) should ideally be removed from the `functions` directory to avoid conflicts.
fixAdd the `runtime` field to the `functions` section of your `firebase.json` file, specifying the Python version you are using (e.g., `'runtime': 'python311'`). Also, remove any `package.json` file from your `functions` directory if it exists, as it can conflict with Python runtime detection.
User code failed to load. Cannot determine backend specification.
This is a generic deployment error that often indicates a problem with the function's initialization code, a missing `requirements.txt` or uninstalled dependencies, or a syntax error preventing the function from being loaded correctly. It can also occur if the function's global scope takes too long to execute during deployment.
fixReview `firebase-debug.log` for more specific errors. Ensure all dependencies are listed in `requirements.txt` and installed in the virtual environment. Check your function's `main.py` for syntax errors or long-running initialization logic. Consider deferring initialization logic using `onInit()` if long global scope execution is suspected.
Upgrade
Version history
0.6.0latest on PyPI · released Jun 4, 2026
Audit
Dependencies
firebase-adminrequiredRequired for interacting with most Firebase services (e.g., Firestore, Authentication) within Cloud Functions and for app initialization.