aws-lambda-go: the Go runtime shim for AWS Lambda handlers

What aws-lambda-go actually removes from your code

Without a runtime library, a Go program running on Lambda has to speak the Lambda Runtime API itself: poll the runtime endpoint for the next invocation, deserialise the event, call your function, serialise the response, POST it back, and loop. aws-lambda-go packages that loop. The README's first example is the whole interface: define a function, then hand it to lambda.Start.

The target audience is narrow and specific. It is Go developers who already deploy to Lambda and want their handler to look like ordinary Go, and teams that want typed event structs rather than hand-rolled JSON. The events package is the second half of the value: it holds type definitions for common AWS event sources, so an SQS or API Gateway payload arrives as a Go struct instead of a map. If you are not on Lambda, or you are writing in another language, nothing here applies to you.

The handler contract and the events package

lambda.Start takes a function and blocks. The runtime library marshals each incoming event into your handler's argument and marshals the return values back out. That is the entire data flow, and the README does not describe a plugin system, a middleware chain or a routing layer on top of it, because there is not one.

The events package is where the shape of your inputs lives. The README points at pkg.go.dev for it and notes that the official documentation has detailed walkthroughs per use case. What the README does not do is enumerate the event types or show a decoding example, so the practical workflow is to open the package documentation and pick the struct matching your trigger. Two consequences follow. First, an event source the library does not model yet means writing your own struct. Second, the repository layout is flat by design: lambda/, events/, lambdacontext/, lambdaurl/, cmd/, cfn/. There is no framework layer to learn, and no framework layer to hide behind when the runtime rejects your payload.

Installing aws-lambda-go and building a first handler

The module path is github.com/aws/aws-lambda-go, and go.mod declares go 1.26, so your toolchain needs to be at least that new. The README's getting-started example is a complete program. Note the return signature: a string and an error, with the error as the second value.

// main.go
package main

import (
	"github.com/aws/aws-lambda-go/lambda"
)

func hello() (string, error) {
	return "Hello λ!", nil
}

func main() {
	lambda.Start(hello)
}

For the provided, provided.al2 or provided.al2023 runtimes, the binary inside the zip must be named bootstrap. Lambda's default architecture is x86_64, so build with GOARCH=amd64 unless you have configured ARM. The README gives exactly this pair of commands.

GOOS=linux GOARCH=amd64 go build -o bootstrap main.go
zip lambda-handler.zip bootstrap

If your build machine is Linux, add CGO_ENABLED=0 to the build. The README explains that Go links against the system libc for some standard library functionality, DNS lookups among them, and that a build machine with a newer GNU libc than the deployment environment can produce a binary that fails at runtime with a GLIBC version error. On Windows, the repository ships a helper, cmd/build-lambda-zip, which produces a zip that marks the binary executable on Linux. Install it and run it as the README shows.

go.exe install github.com/aws/aws-lambda-go/cmd/build-lambda-zip@latest

After the build you should have a lambda-handler.zip containing a single executable named bootstrap. Deployment itself is out of scope for this repository: the README defers to the official documentation on deploying with the AWS CLI, CloudFormation and SAM.

CGO and the GLIBC table are the real constraint

This is the part worth reading twice. If your application requires CGO, the build environment must use a GNU libc version compatible with the target runtime. The README publishes the mapping: provided.al2023 ships GLIBC 2.34, provided.al2 ships 2.26, and provided with go.x ships 2.17. Build against a newer libc than the runtime provides and execution fails with a message naming the missing GLIBC version.

The practical reading is that provided.al2023 is the least restrictive target and the older runtimes are the trap. If you control the build, CGO_ENABLED=0 sidesteps the entire table, and the README notes that most Go applications do not need the system libc. If you genuinely need CGO, you have to pin your build image to a libc at or below the target, which typically means an older base image than your CI defaults to. The README also points at container images as an alternative deployment package to zip files, which is the escape hatch when the zip route becomes a libc negotiation. There is no rollback guidance in the README, and no versioning policy for the runtime API beyond the module's own releases.

Where it is the wrong tool, and what sits next to it

aws-lambda-go is the runtime shim, not a web framework. If you are porting an existing net/http service and want to keep its routing, middleware and handler signatures, this library alone will not do it. That is the gap aws-lambda-go-api-proxy fills: it adapts an http.Handler to the Lambda event model so the same code runs behind API Gateway and on a server. Choosing between them is a question of whether you want to keep the HTTP abstraction or write Lambda-shaped handlers directly. Keeping the abstraction costs an adapter and some fidelity around request context; dropping it means rewriting your handler signatures.

The second boundary is language. The related searches around Go versus Python, Node and Rust point at a real decision, but this repository answers none of it. aws-lambda-go gives you Go's compile-time typing and a single static binary; it does not make cold starts disappear, and the README makes no performance claim of any kind. If your workload is a few lines of glue over another AWS API, the ceremony of cross-compiling a bootstrap binary is a cost you may not want to pay. If your workload is a compiled, typed service where a mismatched event payload should fail loudly, the trade goes the other way.

Maintenance, licence and what an upgrade costs you

The repository is not archived and the last push was on 2026-08-27, which is also the date of the v1.55.0 release. The two releases before it, v1.54.0 and v1.53.0, landed in March 2026, so the cadence is a handful of releases a year rather than a stream. That matters because aws-lambda-go sits underneath your deployed functions: an upgrade changes the code that talks to the Lambda Runtime API, so a bad release is not a library bug, it is a fleet-wide one. Pin the version in go.mod and move deliberately.

The licence situation needs one clarification. The repository carries three licence files: LICENSE, LICENSE-LAMBDACODE and LICENSE-SUMMARY. The project is Apache-2.0, but the presence of a separate LAMBDACODE licence file means the terms are not a single uniform grant across every file in the tree. Read LICENSE-SUMMARY before assuming one licence covers everything you copy, particularly if you lift code out of the samples or the cfn directory rather than importing the module. That is a description of what the repository contains, not legal advice.

One more detail from go.mod: the module retracts v1.39.0. If you are on an old lockfile, that version is explicitly withdrawn by the maintainers.

Editorial conclusion

Adopt aws-lambda-go if you are already writing Go and want Lambda to call your code without an adapter layer; the module is small, Apache-2.0 licensed and its last push was on 2026-08-27. Do not adopt it if your team has no Go toolchain and no cross-compilation story, or if you need a stable ABI against a C library built for an older glibc. Before deploying, verify which runtime you are targeting (provided.al2023, provided.al2, provided, or go.x), confirm the GLIBC version that runtime ships, and decide whether CGO is on. If CGO is on, check the libc version of your build machine against the table in the README first. That single check is the difference between a working zip and a GLIBC_X.YZ not found error in CloudWatch.

Frequently asked questions

Official sources

1. Official README
2. Project repository
3. Release notes