# Run functions with Functions Framework

Cloud Run functions uses the open-source
[Functions Framework](https://docs.cloud.google.com/functions/1stgendocs/functions-framework.md.txt) libraries to
wrap your deployed functions in a persistent HTTP application.

The Functions Framework can also run on any other platform that supports the
language itself, including your local machine, on-premises servers,
[Compute Engine](https://cloud.google.com/products/compute), and [Cloud Run](https://docs.cloud.google.com/run).

> [!NOTE]
> **Note:** if you're interested in building locally runnable *containers* , see [Using the Functions Emulator](https://docs.cloud.google.com/functions/1stgendocs/running/functions-emulator.md.txt).

## Install dependencies

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

See the [Java Functions Framework library](https://github.com/GoogleCloudPlatform/functions-framework-java)
for more information.

### Node.js

> [!NOTE]
> **Note:** This library is automatically included when deploying your function if you do not specify it in your function's dependencies.

<br />

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

### Python

> [!NOTE]
> **Note:** This library is automatically included when deploying your function if you do not specify it in your function's dependencies.

<br />

```bash
pip install functions-framework
```

### Go

> [!NOTE]
> **Note:** This library is automatically included when deploying your function if you do not specify it in your function's dependencies.

<br />

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

### Java

> [!NOTE]
> **Note:** This library is automatically included when deploying your function if you do not specify it in your function's dependencies.

<br />

#### Maven

If you're using [Maven](http://maven.apache.org/install.html), add the
following to your `pom.xml` file:

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

#### Gradle

If you're using [Gradle](https://gradle.org/), add the following to your
`build.gradle` file:

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

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

### C#

The commands below use .NET Templates to create a new .NET Cloud Run function
codebase with the
[.NET Functions Framework library](https://github.com/GoogleCloudPlatform/functions-framework-dotnet)
as a dependency:

```bash
# 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 Run functions:

```bash
bundle add functions_framework
```

### PHP

> [!NOTE]
> **Note:** This library is automatically included when deploying your function if you do not specify it in your function's dependencies.

<br />

```bash
composer require google/cloud-functions-framework
```

## Configure the Functions 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.

#### Supported function types

The Functions Framework supports all three types of functions
supported by Cloud Run functions 1st gen. All language runtimes
support `http` and one of either `event` or `cloudevent`.

| Function type | Signature type | Description | Supporting Runtimes |
|---|---|---|---|
| [HTTP-triggered functions](https://docs.cloud.google.com/functions/1stgendocs/writing/write-http-functions.md.txt) | `http` | Functions that receive and respond to HTTP requests. | All runtimes |
| [Background functions](https://docs.cloud.google.com/functions/1stgendocs/writing/write-event-driven-functions.md.txt#background-functions) | `event` | Cloud Run functions-specific event format | [Node.js](https://docs.cloud.google.com/functions/1stgendocs/concepts/nodejs-runtime.md.txt), [Python](https://docs.cloud.google.com/functions/1stgendocs/concepts/python-runtime.md.txt), [Go](https://docs.cloud.google.com/functions/1stgendocs/concepts/go-runtime.md.txt), [Java](https://docs.cloud.google.com/functions/1stgendocs/concepts/java-runtime.md.txt) |
| [CloudEvent functions](https://docs.cloud.google.com/functions/1stgendocs/writing/write-event-driven-functions.md.txt#cloudevent-functions) | `cloudevent` | Industry-standard event format | [.NET](https://docs.cloud.google.com/functions/1stgendocs/concepts/dotnet-runtime.md.txt), [Ruby](https://docs.cloud.google.com/functions/1stgendocs/concepts/ruby-runtime.md.txt), [PHP](https://docs.cloud.google.com/functions/1stgendocs/concepts/php-runtime.md.txt) |

#### Specify 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](https://docs.cloud.google.com/functions/1stgendocs/concepts/java-runtime.md.txt) and
[.NET](https://docs.cloud.google.com/functions/1stgendocs/concepts/dotnet-runtime.md.txt) 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 `export`ed function to be invoked. (Default: `function`) |
| `--signature-type` | `FUNCTION_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 `export`ed function to be invoked. (Default: `function`) |
| `--signature-type` | `FUNCTION_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`) |

<br />

> [!NOTE]
> **Note:** the Go Functions Framework automatically detects your function's signature type.

### 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 `export`ed function to be invoked. (Default: `function`) |

> [!NOTE]
> **Note:** the Java Functions Framework automatically detects your function's signature type.

### 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`) |

> [!NOTE]
> **Note:** the .NET Functions Framework automatically detects your function's signature type.

### Ruby

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

### PHP

| Environment Variable | Description |
|---|---|
| `FUNCTION_TARGET` | The name of the function to be invoked. (Default: `function`) |
| `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](https://github.com/GoogleCloudPlatform/functions-framework-nodejs/#configure-the-functions-framework).

> [!NOTE]
> **Note:** command-line arguments take precedence over environment variables when running the Node.js Functions Framework.

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.

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

The same can be done using environment variables:

```bash
"scripts": {
  "start": "FUNCTION_TARGET=YOUR_FUNCTION_NAME FUNCTION_SIGNATURE_TYPE=YOUR_SIGNATURE_TYPE npx functions-framework"
}
```

Replace <var translate="no">YOUR_FUNCTION_NAME</var> with the method name of your function, and
<var translate="no">YOUR_SIGNATURE_TYPE</var> (if applicable) with the signature type of your
function as shown in the [table above](https://docs.cloud.google.com/functions/1stgendocs/running/function-frameworks.md.txt#function_types).

### Python

The Python Functions Framework allows you to specify your function's name and
signature type as command line arguments
or [environment variables](https://github.com/GoogleCloudPlatform/functions-framework-python/#configure-the-functions-framework). Command-line arguments must be specified when you
[run the framework](https://docs.cloud.google.com/functions/1stgendocs/running/function-frameworks.md.txt#running_the_framework).

> [!NOTE]
> **Note:** command-line arguments take precedence over environment variables when running the Python Functions 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:

```bash
-Drun.functionTarget=YOUR_FUNCTION_NAME
```

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

```bash
-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:

```bash
# 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:

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

Replace `<functionTarget>` 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`. This is relative to the parent build file
- either `pom.xml` or `build.gradle`).

#### Gradle

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

```java
// 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)
  }
}
```

### 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](https://docs.cloud.google.com/functions/1stgendocs/running/function-frameworks.md.txt#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](https://googlecloudplatform.github.io/functions-framework-ruby/v0.9.0/file.running-a-functions-server.html#configuring-the-server). Command-line arguments must be specified when you
[run the framework](https://docs.cloud.google.com/functions/1stgendocs/running/function-frameworks.md.txt#running_the_framework).

> [!NOTE]
> **Note:** command-line arguments take precedence over environment variables when running the Ruby Functions Framework.

### PHP

The PHP Functions Framework allows you to specify
[environment variables](https://github.com/GoogleCloudPlatform/functions-framework-php#configure-the-functions-framework) 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.

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

Replace <var translate="no">YOUR_FUNCTION_NAME</var> with the name of your function, and
<var translate="no">YOUR_SIGNATURE_TYPE</var> (if applicable) with the signature type of your
function as shown in the [table above](https://docs.cloud.google.com/functions/1stgendocs/running/function-frameworks.md.txt#function_types).

## Run the Functions 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

```bash
npm start
```

### Python

Using command line arguments:

```bash
functions-framework --target=YOUR_FUNCTION_NAME
```

<br />

Using environment variables:

```bash
FUNCTION_TARGET=YOUR_FUNCTION_NAME functions-framework
```

<br />

Replace <var translate="no">YOUR_FUNCTION_NAME</var> with your function's method name.

### Go

> [!NOTE]
> **Note:** First create a `cmd/main.go` file as described on the [Functions Framework for Go](https://github.com/GoogleCloudPlatform/functions-framework-go#quickstart-hello-world-on-your-local-machine) site.

```bash
cd cmd
go build
./cmd
```

Using environment variables:

```bash
cd cmd
go build
PORT=8080 ./cmd
```

<br />

### Java

#### Maven

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

```bash
mvn function:run
```

<br />

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

```bash
mvn function:run -Drun.functionTarget=YOUR_FUNCTION_NAME
```

<br />

Use the following command to run a function specified as an environment variable:

```bash
FUNCTION_TARGET=YOUR_FUNCTION_NAME mvn function:run
```

<br />

Replace <var translate="no">YOUR_FUNCTION_NAME</var> with your function's classname.

#### Gradle

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

```bash
./gradlew runFunction
```

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

```bash
./gradlew runFunction -Prun.functionTarget=YOUR_FUNCTION_NAME
```

<br />

Use the following command to run a function specified as an environment variable:

```bash
FUNCTION_TARGET=YOUR_FUNCTION_NAME ./gradlew runFunction
```

<br />

Replace <var translate="no">YOUR_FUNCTION_NAME</var> 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.)

```bash
dotnet run
```

<br />

> [!NOTE]
> **Note:** the .NET runtime detects functions by searching for classes that implement one of the Functions Framework interfaces (`IHttpFunction` or `ICloudEventFunction`).

If your .NET project contains multiple functions, use the following command to
run a specific function. Replace <var translate="no">YOUR_FUNCTION_CLASSNAME</var> with your
function's classname, including the namespace.

```bash
dotnet run YOUR_FUNCTION_CLASSNAME
```

<br />

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`.

Using command line arguments:

```bash
dotnet run --target YOUR_FUNCTION_CLASSNAME --port 8080
```

<br />

Using environment variables:

```bash
FUNCTION_TARGET=YOUR_FUNCTION_CLASSNAME PORT=8080 dotnet run
```

<br />

### Ruby

Using command line arguments:

```bash
bundle exec functions-framework-ruby --target YOUR_FUNCTION_NAME
```

<br />

Using environment variables:

```bash
FUNCTION_TARGET=YOUR_FUNCTION_NAME bundle exec functions-framework-ruby
```

<br />

Replace <var translate="no">YOUR_FUNCTION_NAME</var> with your function's method name.

### PHP

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

Replace <var translate="no">YOUR_FUNCTION_NAME</var> with your function's name.

## Call your function

See the [calling local functions](https://docs.cloud.google.com/functions/1stgendocs/running/calling.md.txt) page for
instructions on how to interact with your locally-running function.

## Clean up

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