Buildpack for Lambda

The buildpack packaging type (BuildpackLambdaPackaging) builds a Python, Java, Go, Ruby, .NET or Rust Lambda function from its source. Stacktape picks the language from the entry file's extension and the toolchain version from the function's runtime. It installs dependencies and compiles the code in Docker, then zips the result into the deployment package.

For JavaScript and TypeScript functions, use js-bundle.

The Lambda buildpack is a separate builder from the container buildpack. It produces a Lambda zip on the Lambda build image of the function's runtime, and has its own options.

When to use

Use buildpack for Lambda functions in Python, Java, Go, Ruby, .NET or Rust with a standard dependency file.

Use custom-artifact instead when your CI already produces the deployment package, or when the build needs tools that the buildpack does not run.

PHP is not supported as a Lambda function. Run PHP applications as a container service with the container buildpack.

Basic example

entryfilePath is the only required property. It is relative to the Stacktape configuration file.

export default defineConfig(() => {
  const processor = new LambdaFunction({
    packaging: new BuildpackLambdaPackaging({
      entryfilePath: './src/process.py'
    }),
    runtime: 'python3.13',
    memory: 512,
    timeout: 60
  });

  return {
    resources: { processor }
  };
});

memory and timeout are Lambda function settings, not packaging options.

Supported languages

LanguageEntry fileDependencies read fromRuntimeOptions
Python.pypyproject.toml, uv.lock, requirements.txt, Pipfilepython3.xpython
Java.javabuild.gradle, pom.xmljavaXXjava
Go.gogo.modprovided.al2023None
Ruby.rbGemfilerubyX.XNone
.NET.cs*.csprojdotnetXdotnet
Rust.rsCargo.tomlprovided.al2023None

Stacktape uses the dependency file nearest to the entry file. The build runs in Docker, so Docker must be running.

Runtime and language versions

The function's runtime property decides the language version. The build uses the Lambda build image of that runtime, so the artifact matches the environment it runs in. When runtime is not set, Stacktape selects a default runtime from the entry file's extension: python3.13, java25, ruby4.0, dotnet10, or provided.al2023 for Go and Rust. Python defaults to 3.13 rather than 3.14 because many pinned packages with native code, such as psycopg-binary 3.2.3 or pydantic-core 2.27, have no wheels for 3.14. Set runtime explicitly to pin a version.

A Python build also compiles the .py files it packages with the function's Python version. A syntax error in the entry file or in a project module it imports, directly or through other modules, stops the build with the file and line, instead of failing every request after the deployment. A file the entry file does not import, such as a script, a test fixture or a template, only produces a warning; leave it out with excludeFiles to silence it. Imports made at run time, for example with importlib, are not followed.

runtime: 'java21',

See Lambda function runtime for the list of runtime identifiers.

Handler function

handlerFunction names the function in the entry file that Lambda invokes. It is ignored for Go and Rust, where the compiled binary is the handler.

Stacktape builds the full Lambda handler from the entry file:

LanguageLambda handlerhandlerFunction default
Python<module>.<handlerFunction>, for example src.main.handlerhandler
Ruby<file>.<handlerFunction>, for example src/handler.handlerhandler
Java<package>.<Class>::<handlerFunction>, for example com.example.Handler::handleRequesthandleRequest
.NET<Assembly>::<Namespace>.<Class>::<handlerFunction>, for example Orders::Orders.Api.Function::FunctionHandlerFunctionHandler

For Java, the class is the entry file's class in the package its package line declares: src/main/java/com/example/Handler.java with package com.example; is com.example.Handler. A capitalized handlerFunction such as Other names another class of the same package and calls its handleRequest; 'Other::handle' also names the method, and a fully qualified com.example.Other::handle is used as written.

For .NET, the assembly is the project's AssemblyName, or the .csproj file name when the project sets none. The namespace comes from the entry file, and the class is the one named like the file. A handlerFunction that contains :: is a complete handler and is used as written. An entry file with top-level statements and no class is an executable assembly; its handler is the assembly name.

Python

Stacktape resolves and installs Python dependencies with uv. It finds the dependency file automatically; set python.packageManagerFile when it is somewhere else.

OptionPurpose
packageManagerFilePath to requirements.txt, Pipfile, pyproject.toml or uv.lock. When both pyproject.toml and uv.lock exist, the lock file is used.
uvOptionalDependenciesExtras from pyproject.toml to include. Passed to uv pip compile as --extra.
uvWithGroupsDependency groups to include. Passed as --group.
uvWithoutGroupsDependency groups to exclude. Passed as --no-group.
uvOnlyGroupsInclude only these groups, without the project dependencies and default groups. Passed as --only-group.
packaging: new BuildpackLambdaPackaging({
  entryfilePath: './app/main.py',
  python: {
    packageManagerFile: './pyproject.toml',
    uvWithGroups: ['lambda']
  }
}),

Java

Stacktape builds a Java function with Maven when the project's nearest build file is a pom.xml, and with Gradle otherwise. Set java.useMaven to choose explicitly. java.packageManagerFile points to the build.gradle or pom.xml build file.

packaging: new BuildpackLambdaPackaging({
  entryfilePath: './src/main/java/Handler.java',
  java: {
    useMaven: true,
    packageManagerFile: './pom.xml'
  }
}),
runtime: 'java21',

Java functions start more slowly than interpreted languages because of JVM startup. 1024 MB of memory is a reasonable starting point.

Go and Ruby

Go and Ruby have no language options. Point entryfilePath to the Go main package file or the Ruby handler file. Go modules and Bundler dependencies are installed from go.mod and Gemfile.

.NET

dotnet.projectFile points to the function's .csproj project file.

packaging: new BuildpackLambdaPackaging({
  entryfilePath: './src/Handler.cs',
  dotnet: {
    projectFile: './src/MyFunction.csproj'
  }
}),
runtime: 'dotnet8',

Rust

Rust functions are built with cargo-lambda. Set entryfilePath to src/main.rs and runtime to provided.al2023. The compiled binary becomes the function's bootstrap file, and handlerFunction is ignored.

export default defineConfig(() => {
  const resizer = new LambdaFunction({
    packaging: new BuildpackLambdaPackaging({
      entryfilePath: './src/main.rs'
    }),
    runtime: 'provided.al2023',
    architecture: 'arm64',
    memory: 256
  });

  return {
    resources: { resizer }
  };
});

Including and excluding files

includeFiles adds files that the function reads at runtime, such as templates or model files. excludeFiles removes files from the deployment package. Both take glob patterns relative to the Stacktape configuration file.

Build caching

Stacktape caches deployment packages by a checksum of their inputs. When the source, dependencies and options have not changed, the function is not built again.

API reference

BuildpackLambdaPackagingProps
Click a property in the tree to see its description, default value, and full type.

Python options

PythonBuildpackConfig
Click a property in the tree to see its description, default value, and full type.

Java options

JavaBuildpackConfig
Click a property in the tree to see its description, default value, and full type.

.NET options

DotnetBuildpackConfig
Click a property in the tree to see its description, default value, and full type.

Buildpack for Lambda FAQ

Where did pythonVersion and the other version options go?

The function's runtime decides the language version. Set runtime: 'python3.12', runtime: 'java21' or runtime: 'dotnet8' on the function. See Upgrading from v3.

Can I build a PHP Lambda function?

No. Run PHP as a container with the container buildpack, which detects Composer and Laravel projects.