Registry / gcp / functions-framework

functions-framework

library3.10.2pypypi✓ verified 29d ago

Functions Framework for Python is an open-source FaaS (Function as a Service) framework designed for writing portable Python functions. It allows developers to test their Google Cloud Functions locally, run them in other serverless environments, or deploy them directly to Google Cloud. The current version is 3.10.1, and it maintains an active release cadence with frequent patch and minor updates, typically every 1-3 months.

gcp web-framework devops

pip install functions-framework

github ↗package ↗

INSTALL

IMPORT

SIG · FUNCTIONS-FRAMEWOR

functions-framework

gcppythonv3.10.2

Install

3.5s avg

Import

459ms

Disk

30MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v3.10.2 · 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

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.474s · 30.7MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 3.5s · import 0.444s · 31MB

30MB installed

● package 30MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Request

✓ from flask import Request

For HTTP functions, the primary input argument is a Flask Request object. No direct import of `functions_framework` is typically needed in your function code.

CloudEvent

✓ from cloudevents.http import CloudEvent

For CloudEvent functions, the primary input argument is a CloudEvent object. No direct import of `functions_framework` is typically needed in your function code.

Define an HTTP function `hello_http` in a file (e.g., `main.py`). The function receives a `flask.Request` object. Run it locally using the `functions-framework` CLI, specifying the function name with `--target`. By default, it runs on port 8080.

# main.py def hello_http(request): """Responds to any HTTP request. Args: request (flask.Request): The request object. Returns: The response text, or any set of values that can be turned into a Response object using `make_response`. """ request_json = request.get_json(silent=True) request_args = request.args if request_json and 'name' in request_json: name = request_json['name'] elif request_args and 'name' in request_args: name = request_args['name'] else: name = 'World' return f'Hello {name}!' # To run locally: # 1. Save this as main.py # 2. Run from your terminal: functions-framework --target hello_http # 3. Access at http://localhost:8080/

functions-framework --version

Debug

Known issues

breakingFunctions Framework v3.8.3 and later require Flask 2.0 or higher. If your project uses an older version of Flask, you may encounter `ImportError` or other compatibility issues.

fix

Upgrade Flask to version 2.0 or newer: `pip install 'Flask>=2.0'` or ensure your environment satisfies this requirement.

affects: >=3.8.3

gotchaWhen running locally, you must specify the target function using the `--target` flag (e.g., `functions-framework --target my_function`). Failing to do so will result in an error indicating no target was found.

fix

Always provide `--target <your_function_name>` when invoking `functions-framework` from the command line.

affects: All versions

gotchaEnsure your function signature matches the expected type (HTTP or CloudEvent). HTTP functions take a `flask.Request` object. CloudEvent functions take a `cloudevents.CloudEvent` object.

fix

Review the function signature: `def my_http_function(request: Request):` for HTTP or `def my_cloud_event_function(event: CloudEvent):` for CloudEvent types.

affects: All versions

gotchaFor CloudEvents, access the event data via `event.data` for the actual payload. CloudEvents often wrap the original payload (e.g., Pub/Sub messages are nested).

fix

Explicitly access `event.data` for the actual payload. For example, `event_data = event.data` or `message = json.loads(event.data)['message']` for Pub/Sub events.

affects: All versions

breakingVersion 3.10.1 corrected the `cloudevents` dependency to allow `1.11.0`. Older `functions-framework` versions might have had improperly constrained `cloudevents` dependencies, potentially leading to issues if `cloudevents` was upgraded to an incompatible version.

fix

Upgrade to `functions-framework` v3.10.1 or newer to ensure correct `cloudevents` dependency handling. If stuck on an older version, manually pin `cloudevents` to a compatible range (e.g., `<1.11.0` if using an older `functions-framework` version).

affects: <3.10.1

Errors

Common errors & fixes

Provided code is not a loadable module. Could not load the function, shutting down.

The `functions-framework` cannot find or load the specified target function, often due to an incorrect `--target` flag, a missing or misspelled function, or an improperly structured Python file or directory.

fix

Ensure the `--target` flag exactly matches the name of your function, and that your function's Python file (e.g., `main.py`) is in the root of your project or the specified source directory. For example, if your function is `hello_world` in `main.py`, run: `functions-framework --target hello_world`

ModuleNotFoundError: No module named 'functions_framework'

The `functions-framework` package itself or a required dependency for your function is not installed in the Python environment where the function is being executed.

fix

Install `functions-framework` and all your function's dependencies using pip within your virtual environment. For functions-framework: `pip install functions-framework`. For other dependencies, list them in `requirements.txt` and run `pip install -r requirements.txt`.

KeyError: 'some_key'

An HTTP Cloud Function, particularly when processing JSON payloads from `request.get_json()`, attempts to access a key that does not exist in the incoming request's body.

fix

Safely access dictionary keys by using the `.get()` method with a default value, or by explicitly checking for the key's existence before access. Example: `data = request.get_json(); value = data.get('some_key', 'default_value')` or `if 'some_key' in data: value = data['some_key']`.

AttributeError: 'module' object has no attribute 'CloudFunctionsServiceClient'

This error can occur due to version conflicts between the `functions-framework` and the `google-cloud-functions` SDK package, where `functions-framework` might overwrite essential files needed by the SDK.

fix

Adjust the installation order or version pinning of `google-cloud-functions` in your `requirements.txt` to ensure compatibility. If using both, install `google-cloud-functions` *after* `functions-framework`. It might be necessary to use a virtual environment and carefully manage dependency versions.

Upgrade

Version history

3.10.2latest on PyPI · released Jun 17, 2026

Audit

Dependencies

FlaskrequiredUsed for handling HTTP functions. Requires Flask 2.0+ since functions-framework v3.8.3.

cloudeventsoptionalUsed for handling CloudEvent functions. Version ranges are managed by functions-framework.

gunicornrequiredUsed as the default WSGI web server for running functions locally or in deployed environments.

Agent activity

37 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/googlecloudplatform/functions-framework-python ↗

packagehttps://pypi.org/project/functions-framework/ ↗