docs community resources blog github

Go Buildpack Reference

This reference documentation offers an in-depth description of the behavior and configuration options of the Paketo Go Buildpack. For explanations of how to use the buildpack for several common use-cases, see the Paketo Go Buildpack How To documentation.

Supported Dependencies

The Go Paketo Buildpack supports several versions of Go. For more details on the specific versions supported in a given buildpack version, see the release notes.


The Paketo Go Buildpack is a composite buildpack designed to build applications written in Go.

Package Management

With the Go CNB, there are three options for package management depending on your application:

  • The built-in Go modules feature,
  • No package manager

Support for each of these package managers is mutually-exclusive. You can find specific information for each option below.

Package Management with Go Modules

The buildpack will vendor dependencies using go modules if the app source code contains a go.mod file. During the build phase, the go-mod-vendor buildpack checks to see if the application requires any external modules and if it does, runs the go mod vendor command for your app. The resulting vendor directory will exist in the app’s root directory and will contain all packages required for the build.

No Package Management

The buildpack also supports both self-vendored apps and simpler apps that do not require third-party packages. In this case there is no vendoring step, and the go build command is run on the app source code as it is provided.


The buildpack runs go build to compile Go source code into executables. By default, it sets the flag -buildmode=pie. See the Go tool’s documentation for details about build configuration.

Buildpack-Set Environment Variables

The Go CNB sets a few environment variables during the build and launch phases of the app lifecycle. The sections below describe each environment variable and its impact on your app.


The GOPATH environment variable tells Go where to look for artifacts such as source code and binaries. The Go CNB takes care of setting the GOPATH for you, depending on your app and which package management option your app uses.

  • Set by: go-mod-vendor and go-build
  • Phases: build
  • Value: path to Go workspace

Go Modules

When using Go modules, the Go CNB sets the GOPATH to a cached module layer in the image so that between builds of the app, the dependencies don’t have to be redownloaded. Essentially, the GOPATH is being used to tell the go mod vendor command where to look for dependencies. It’s worth noting that in this case, the GOPATH isn’t persisted beyond vendoring the dependencies and gets overwritten by a subsequent buildpack.


The go-build buildpack participates in the Go CNB in every case, regardless of which package management option is used. The GOPATH is set to a temporary directory which includes the app source code and local sub-packages. The GOPATH is utilized in running go build to compile your app.


The GOCACHE variable specifies where build outputs are stored for reuse in subsequent builds. It gets set to a cached layer in the image by the go-build buildpack, so that it is persisted between builds.

  • Set by: go-build
  • Phases: build
  • Value: Go Cache layer path


Name Required/Optional Purpose
Paketo CA Certificates Buildpack Optional Installs custom CA certificates
Paketo Go Dist Buildpack Required Installs the Golang toolchain
Paketo Go Mod Vendor Buildpack Optional Installs app Go modules
Paketo Go Build Buildpack Required Compiles source code
Paketo Procfile Buildpack Optional Sets a user-specified start command
Paketo Environment Variables Buildpack Optional Sets user-specified launch-time environment variables
Paketo Image Labels Buildpack Optional Adds user-specified labels to app image metadata
Paketo Watchexec Buildpack Optional Installs watchexec
Paketo Git Buildpack Optional Enables git authentication and/or git metadata extraction during builds

Software Bill of Materials

The Go buildpack supports the full software bill of materials (SBOM) in Syft, CycloneDX, and SPDX formats. For apps with a go.mod, this includes Go module data. See Extract Go Module Information from a Build. The Go buildpack also includes limited support for the Paketo-specific SBOM format. This SBOM does not include Go module information.


Last modified: July 18, 2024