Write Cloud Run functions

This page provides an introduction for writingCloud Run functions with the Functions Framework.

When writing functions source code, you must use theFunctions Framework,an open source library for writing Cloud Run functions. With theFunctions Framework, you can write lightweight functions that run inCloud Run and in other environments, including your local developmentmachine and Knative-based environments.

The Functions Framework lets you:

  • Invoke a Cloud Run function in response to a request.
  • Automatically unmarshal events conforming to theCloudEvents spec, an industry-standardspecification for describing event data in a common way.
  • Start a local development server for quick testing.

Write functions with the Functions Framework

The Functions Framework provides an interface for building modular services. Touse the Functions Framework in your source code, specify the following:

Function entry point

Your source code must define an entry point for your function, which is theparticular code executed when the Cloud Run function isinvoked. You specify this entry point when you deploy your function.

How you define the entry point depends on the language runtime you use. Somelanguages use a function as their entry point, while others use a class.

Signature Type

When you write the source code of a function with the Functions Framework, youmust specify one of the two signature types:

  • HTTP functions: A function that registers an HTTP handler function. SeeWrite HTTP functions for more information.
  • Event-driven functions (also calledCloudEvents functions): A functionthat registers a CloudEvents handler function. SeeWrite event-driven functionsfor more information.

Use an HTTP function when you need your function to have a URL endpoint andrespond to HTTP requests, such as for webhooks. Use an event-driven functionwhen your function should be triggered directly in response to events withinyour Google Cloud project, such as messages on a Pub/Sub topic or changes ina Cloud Storage bucket.

Source directory structure

The Functions Framework is supported in a number of programming languages. Thelanguage runtime you choose and the type of function you want to writedetermines how to structure your code and implement your function.

For Cloud Run to locate your function definition, eachlanguage runtime has requirements for structuring your source code.

Node.js

The basic directory structure for Node.js functions is as follows:

.├── index.js└── package.json

By default, Cloud Run attempts to load source code from a filenamedindex.js at the root of your function directory. To specify a differentmain source file, use themain field in yourpackage.json file.

Yourpackage.json file must also include theFunctions Framework for Node.jsas a dependency:

{"main":"index.js","dependencies":{"@google-cloud/functions-framework":"^3.0.0"}}
Note: You can add the Functions Framework dependency withnpm by runningnpm install @google-cloud/functions-framework.

The code in your main file must define yourfunction entry pointand can import other code and Node.js modules. The main file can alsodefine multiple function entry points that can be deployed separately.

See theNode.js runtime overview and theFunctions Framework for Node.jsfor more details.

Python

The basic directory structure for Python functions is as follows:

.├── main.py└── requirements.txt

Cloud Run loads source code from a file namedmain.py at theroot of your function directory. You must name your main filemain.py.

Yourrequirements.txt file must include theFunctions Framework for Pythonas a dependency:

functions-framework==3.*

The code in yourmain.py file must define yourfunction entry point and can import other code and externaldependencies as normal. Themain.py file can also define multiple functionentry points that can be deployed separately.

See thePython runtime overview and theFunctions Framework for Pythonfor more details.

Go

The basic directory structure for Go functions is as follows:

.├── myfunction.go└── go.mod

Your function must be in a Go package at the root of your project. The packageand its source files can have any name, except your function cannot be inpackage main. If you need amain package, for example for local testing,you can create one in a subdirectory:

.├── myfunction.go├── go.mod└── cmd/  └── main.go

Yourgo.mod file must include theFunctions Framework for Goas a dependency:

moduleexample.com/my-modulerequire(github.com/GoogleCloudPlatform/functions-framework-gov1.5.2)
Note: You can add the Functions Framework dependency by runninggo get github.com/GoogleCloudPlatform/functions-framework-go.

The code in your root package must define yourfunction entry point and can import other code from subpackagesand dependencies as normal. Your package can also define multiple functionentry points that can be deployed separately.

Note: For an example of setting up a basic Cloud Run project in Go,see theFunctions Framework for Go Quickstart on GitHub.

See theGo runtime overview and theFunctions Framework for Gofor more details.

Java

The basic directory structure for Java functions is as follows:

.├── pom.xml└── src/  └── main/      └── java/          └── MyFunction.java

Your Java source files must be under thesrc/main/java/ directory and can haveany name. If your source files declare a package, add an extra directory undersrc/main/java with the name of the package:

.├── pom.xml└── src/  └── main/      └── java/          └── mypackage/              └── MyFunction.java

We recommend putting associated tests under asrc/test/java/ subdirectory.

Note: If you're working with another JVM language (such as Groovy, Kotlin, orScala), rename thejava directories to language-appropriate names (such asgroovy,kotlin, orscala).

Yourpom.xml file must include theFunctions Framework for Javaas a dependency:

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

The code in your source files must define yourfunction entry point and can import other code and externaldependencies as normal. Your source files can also define multiple functionentry points that can be deployed separately.

See theJava runtime overview and theFunctions Framework for Javafor more details.

.NET

The basic directory structure for .NET functions is as follows:

.├── MyFunction.cs└── MyProject.csproj

You can structure your projects as you would any other .NET source code.Your source files can have any name.

Note: The same pattern applies if you use F# or Visual Basic, but withappropriate file extensions (.fs and.fsproj for F#,.vb and.vbprojfor Visual Basic).

Your project file must include theFunctions Framework for .NETas a dependency:

...<PackageReferenceInclude="Google.Cloud.Functions.Hosting"Version="1.0.0"/>...

The code in your source files must define yourfunction entry point and can import other code and externaldependencies as normal. Your source files can also define multiple functionentry points that can be deployed separately.

Note: For information about file structure in relation to functions that usemultiple local .NET projects, seeDeploying a function with a local project dependency.

See the.NET runtime overview and theFunctions Framework for .NETfor more details.

Ruby

The basic directory structure for Ruby functions is as follows:

.├── app.rb├── Gemfile└── Gemfile.lock

Cloud Run loads source code from a file namedapp.rb at theroot of your function directory. Your main file must be namedapp.rb.

YourGemfile file must include theFunctions Framework for Rubyas a dependency:

source "https://rubygems.org"gem "functions_framework", "~> 1.0"
Note: You can add the Functions Framework dependency withBundler by runningbundle add functions_framework.

The code in yourapp.rb file must define yourfunction entry point and can import other code and externaldependencies as normal. Theapp.rb file can also define multiple functionentry points that can be deployed separately.

See theRuby runtime overview and theFunctions Framework for Rubyfor more details.

PHP

The basic directory structure for PHP functions is as follows:

.├── index.php└── composer.json

Cloud Run loads source code from a file namedindex.php at theroot of your function directory. You must name your main fileindex.php.

Yourcomposer.json file must include theFunctions Framework for PHPas a dependency:

{"require":{"google/cloud-functions-framework":"^1.1"}}
Note: You can add the Functions Framework dependency withComposer by runningcomposer require google/cloud-functions-framework.

The code in yourindex.php file must define yourfunction entry point and can import other code andexternal dependencies as normal. Theindex.php file can also define multiplefunction entry points that can be deployed separately.

See thePHP runtime overview and theFunctions Framework for PHPfor more details.

If you group multiple functions into a single project, be aware that everyfunction might end up sharing the same set of dependencies. However, some of thefunctions might not need all of the dependencies.

Where possible, we recommend splitting up large multi-function codebases andputting each function in its own top-level directory as shown in the precedingexamples, with its own source and project configuration files. This approachminimizes the number of dependencies required for a particular function, whichin turn reduces the amount of memory your function needs.

What's next

Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2025-07-09 UTC.