Running Functions with Function Frameworks

Internally, Cloud Functions uses open-source libraries called Function Frameworks that wrap user functions within a persistent HTTP application.

The Function Frameworks can also run on any other platform that supports the language itself, including your local machine, on-prem servers, Compute Engine, and Cloud Run.

Installing dependencies

In your function's directory, install the Functions Framework library for your language:

Node.js

npm install --save-dev @google-cloud/functions-framework

Python

pip install functions-framework

Go

go install github.com/GoogleCloudPlatform/functions-framework-go/funcframework

Java

Maven

If you're using Maven, add the following to your pom.xml file:

<dependency>
  <groupId>com.google.cloud.functions</groupId>
  <artifactId>functions-framework-api</artifactId>
  <version>1.0.4</version>
  <scope>provided</scope>
</dependency>

Gradle

If you're using Gradle, add the following to your build.gradle file:

dependencies {
  // Every function needs this dependency to get the Functions Framework API.
  compileOnly 'com.google.cloud.functions:functions-framework-api:1.0.4'

  // To run function locally using Functions Framework's local invoker
  invoker 'com.google.cloud.functions.invoker:java-function-invoker:1.0.2'
}

C#

The commands below use .NET Templates to create a new .NET Cloud Function codebase with the .NET Functions Framework library as a dependency:

# HTTP functions
dotnet new gcf-http

# CloudEvent functions
dotnet new gcf-event

Ruby

In Ruby the functions framework must be added to your function's dependencies in order to deploy it to Cloud Functions:

bundle add functions_framework

PHP

composer require google/cloud-functions-framework

Configuring the framework

Before running a function using the Functions Framework, you'll first need to specify both the type and the name of the function you want to run. These attributes can be specified as either command-line interface (CLI) flag or as environment variables.

Function types

Collectively, the Functions Frameworks support three types of functions supported by Cloud Functions itself. Each language runtime typically supports only two of these formats: http, and one of event or cloudevent.

Function type Signature type Description Supporting Runtimes
HTTP-triggered functions http Functions that receive and respond to HTTP requests. All
Background functions event Cloud Functions-specific event format Java, Node, Go, and Python
CloudEvent Functions cloudevent Industry-standard event format PHP, Ruby and .NET

Specifying which function to run

Before running a function with the Functions Framework, you must first specify which function within your code should be run. For most languages, you can do this by specifying the target function's method name as shown in the tables below. (Exceptions to this rule such as Java and .NET are also shown below.)

Per-language instructions

See the table below for a list of configuration options supported by each language.

Node.js

CLI Argument Environment Variable Description
--port PORT The port to listen for requests on. (Default: 8080)
--target FUNCTION_TARGET The name of the exported function to be invoked. (Default: function)
--signature-type SIGNATURE_TYPE The signature type used by your function. Can be one of http (the default), event, or cloudevent.

Python

CLI Argument Environment Variable Description
--port PORT The port to listen for requests on. (Default: 8080)
--target FUNCTION_TARGET The name of the exported function to be invoked. (Default: function)
--signature-type SIGNATURE_TYPE The signature type used by your function. Can be one of http (the default), event, or cloudevent.

Go

Environment Variable Description
PORT The port to listen for requests on. (Default: 8080)

Java

Argument Name Environment Variable Description
run.port PORT The port to listen for requests on. (Default: 8080)
run.functionTarget FUNCTION_TARGET The name of the exported function to be invoked. (Default: function)

C#

CLI Argument Environment Variable Description
--port PORT The port to listen for requests on. (Default: 8080)
--target (or only argument) FUNCTION_TARGET The classname of the function to be invoked. (Default: function)

Ruby

CLI Argument Environment Variable Description
--port PORT The port to listen for requests on. (Default: 8080)
--target FUNCTION_TARGET The name of the exported function to be invoked. (Default: function)

PHP

Environment Variable Description
FUNCTION_TARGET The name of the function to be invoked. (Default: function)
SIGNATURE_TYPE The signature type used by your function. Can be one of http (the default), event, or cloudevent.

Follow the instructions below to configure and run the Functions Framework:

Node.js

The Node.js Functions Framework allows you to specify your function's name and signature type as command line arguments or environment variables.

You can also specify these values in the package.json buildfile by adding a start script with the required CLI arguments as shown in the example below.

"scripts": {
  "start": "npx functions-framework --target=YOUR_FUNCTION_NAME [--signature-type=YOUR_SIGNATURE_TYPE]"
}

Replace YOUR_FUNCTION_NAME with the method name of your function, and YOUR_SIGNATURE_TYPE (if applicable) with the signature type of your function as shown in the table above.

Python

The Python Functions Framework allows you to specify your function's name and signature type as command line arguments or environment variables. Command-line arguments must be specified when you run the framework.

Go

The Go Functions Framework uses funcframework.RegisterHTTPFunctionContext to specify the function target and signature type.

Java

The Java Functions Framework accepts configuration data from three different sources, in the following priority order (most specific to least specific):

  • Command-line arguments
  • Buildfiles
  • Environment variables

Command-line arguments

Maven

You can specify the function you want to run by adding the following command-line interface (CLI) flag to your mvn commands:

-Drun.functionTarget=YOUR_FUNCTION_NAME

You can also specify the target port by adding the following CLI flag in a similar manner:

-Drun.port=12345

Gradle

Gradle's CLI flags are nearly identical to Maven's. The only change Gradle makes is to swap the leading -D in each flag for a -P as shown in the example below:

# Maven version
-Drun.functionTarget=...

# Gradle version
-Prun.functionTarget=...

Buildfiles

You can also specify the function you want to run in your project's buildfile. While Maven and Gradle have similar CLI flags, their buildfile clauses differ significantly.

Maven

Maven buildfiles are named pom.xml. Add the following clause to this file to specify a target function:

<plugin>
  <groupId>com.google.cloud.functions</groupId>
  <artifactId>function-maven-plugin</artifactId>
  <version>0.9.7</version>
  <configuration>
    <functionTarget>functions.HelloWorld</functionTarget>
  </configuration>
</plugin>

Replace YOUR_FUNCTION_PACKAGE_NAME with the package name of your function.

Gradle

Gradle buildfiles are named build.gradle. Add the following clause to this file to specify a target function:

// Register a "runFunction" task to run the function locally
tasks.register("runFunction", JavaExec) {
  main = 'com.google.cloud.functions.invoker.runner.Invoker'
  classpath(configurations.invoker)
  inputs.files(configurations.runtimeClasspath, sourceSets.main.output)
  args(
    '--target', project.findProperty('run.functionTarget') ?: '',
    '--port', project.findProperty('run.port') ?: 8080
  )
  doFirst {
    args('--classpath', files(configurations.runtimeClasspath, sourceSets.main.output).asPath)
  }
}

Replace YOUR_FUNCTION_CLASS_NAME with the class name of your function. (For example, a function in package functions with class name HelloCloudFunctions would have a class name of functions.HelloCloudFunctions.)

C#

If you create your project using dotnet new and one of the templates specified above, the .NET Functions Framework will automatically detect your function.

If your project contains multiple functions, see the Running the Framework section for information on how to run a specific function.

Ruby

The Ruby Functions Framework allows you to specify your function's name and signature type as command line arguments or environment variables. Command-line arguments must be specified when you run the framework.

PHP

The PHP Functions Framework allows you to specify environment variables as command line arguments.

You can also specify these values in the composer.json buildfile by adding a start script as shown in the example below.

"scripts": {
   "start": [
       "Composer\\Config::disableProcessTimeout",
       "FUNCTION_TARGET=YOUR_FUNCTION_NAME php -S localhost:${PORT:-8080} vendor/bin/router.php"
    ]
}

Replace YOUR_FUNCTION_NAME with the name of your function, and YOUR_SIGNATURE_TYPE (if applicable) with the signature type of your function as shown in the table above.

Running the framework

Use the following command to run your function with the Functions Framework. By default, your function will be accessible at localhost:8080 unless you explicitly specify a PORT value.

Node.js

npm start

Python

functions_framework --target=YOUR_FUNCTION_NAME

Replace YOUR_FUNCTION_NAME with your function's method name.

Go

go build
./cmd

Java

Maven

Use the following command to run a function specified in pom.xml:

mvn function:run

Use the following command to run a function specified in a command-line argument:

mvn function:run -Drun.functionTarget=YOUR_FUNCTION_NAME

Replace YOUR_FUNCTION_NAME with your function's classname.

Gradle

Use the following command to run a function specified in build.gradle:

./gradlew runFunction

Use the following command to run a function specified in a command-line argument:

./gradlew runFunction -Prun.functionTarget=YOUR_FUNCTION_NAME

Replace YOUR_FUNCTION_NAME with your function's classname.

C#

Use the following command to run your function when exactly one function is present in the current .NET project. (This is the default structure for template-created projects.)

dotnet run

If your .NET project contains multiple functions, use the following command to run a specific function. Replace YOUR_FUNCTION_CLASSNAME with your function's classname, including the namespace.

dotnet run YOUR_FUNCTION_CLASSNAME

If you want to run multiple functions simultaneously, you'll need to run multiple Functions Framework instances. To avoid conflicts between running framework instances, each instance should use a different PORT value. The following command shows how to run a function with a PORT value of 8080.

dotnet run --target YOUR_FUNCTION_CLASSNAME --port 8080

Ruby

bundle exec functions-framework-ruby --target YOUR_FUNCTION_NAME

Replace YOUR_FUNCTION_NAME with your function's method name.

PHP

export FUNCTION_TARGET=YOUR_FUNCTION_NAME
php -S localhost:8080 vendor/bin/router.php

Replace YOUR_FUNCTION_NAME with your function's name.

Calling your function

See the calling running functions page for instructions on how to interact with your locally-running function.

Cleaning up

Once you're finished running your function, stop the running framework instance by pressing CTRL-C.