Layers & Shared Dependencies

A layer is a ZIP of code or dependencies that many functions can share instead of each bundling its own copy.

Publishing a shared library, a set of third-party packages, or a common runtime dependency once - then attaching it to every function that needs it - keeps deployment packages small and updates consistent. This page shows how to publish a layer and wire it onto functions from both SDKs, plus the versioning and size rules that trip people up.

Recipe

Publish the layer version, capture its ARN, then attach that ARN to the function's configuration.

# --- Python (boto3) ---
import boto3
 
lam = boto3.client("lambda")
with open("shared-deps.zip", "rb") as f:
    layer = lam.publish_layer_version(
        LayerName="shared-deps",
        Content={"ZipFile": f.read()},
        CompatibleRuntimes=["python3.12"],
        CompatibleArchitectures=["x86_64"],
    )
 
lam.update_function_configuration(
    FunctionName="my-func",
    Layers=[layer["LayerVersionArn"]],
)

// --- TypeScript (AWS SDK v3) ---
import {
  LambdaClient,
  PublishLayerVersionCommand,
  UpdateFunctionConfigurationCommand,
} from "@aws-sdk/client-lambda";
import { readFileSync } from "node:fs";
 
const lam = new LambdaClient({});
const layer = await lam.send(new PublishLayerVersionCommand({
  LayerName: "shared-deps",
  Content: { ZipFile: readFileSync("shared-deps.zip") },
  CompatibleRuntimes: ["nodejs20.x"],
  CompatibleArchitectures: ["x86_64"],
}));
 
await lam.send(new UpdateFunctionConfigurationCommand({
  FunctionName: "my-func",
  Layers: [layer.LayerVersionArn!],
}));

When to reach for this:

• Several functions depend on the same libraries and you want one copy to maintain.
• Your deployment package is bloated by dependencies that rarely change.
• You want to update a shared dependency by publishing a new layer version, not redeploying every function's code.
• You need a common set of tools (an SDK extension, a monitoring agent) available under /opt.

Working Example

A realistic flow: publish a layer from an artifact already staged in S3, attach it alongside an existing layer, and wait for the function to become active again.

# --- Python (boto3) ---
import boto3
 
lam = boto3.client("lambda")
 
layer = lam.publish_layer_version(
    LayerName="data-utils",
    Description="pandas + pyarrow, built for 3.12",
    Content={"S3Bucket": "my-artifacts", "S3Key": "layers/data-utils-1.zip"},
    CompatibleRuntimes=["python3.12"],
    CompatibleArchitectures=["arm64"],
)
new_arn = layer["LayerVersionArn"]
 
# Keep an existing layer and add the new one (max 5 total).
current = lam.get_function_configuration(FunctionName="etl")
existing = [l["Arn"] for l in current.get("Layers", [])]
lam.update_function_configuration(FunctionName="etl", Layers=[*existing, new_arn])
 
lam.get_waiter("function_updated_v2").wait(FunctionName="etl")
print("attached", new_arn)

// --- TypeScript (AWS SDK v3) ---
import {
  LambdaClient,
  PublishLayerVersionCommand,
  GetFunctionConfigurationCommand,
  UpdateFunctionConfigurationCommand,
  waitUntilFunctionUpdatedV2,
} from "@aws-sdk/client-lambda";
 
const lam = new LambdaClient({});
 
const layer = await lam.send(new PublishLayerVersionCommand({
  LayerName: "data-utils",
  Description: "sharp image lib, built for 20.x",
  Content: { S3Bucket: "my-artifacts", S3Key: "layers/data-utils-1.zip" },
  CompatibleRuntimes: ["nodejs20.x"],
  CompatibleArchitectures: ["arm64"],
}));
const newArn = layer.LayerVersionArn!;
 
const current = await lam.send(new GetFunctionConfigurationCommand({ FunctionName: "etl" }));
const existing = (current.Layers ?? []).map((l) => l.Arn!);
await lam.send(new UpdateFunctionConfigurationCommand({
  FunctionName: "etl",
  Layers: [...existing, newArn],
}));
 
await waitUntilFunctionUpdatedV2({ client: lam, maxWaitTime: 120 }, { FunctionName: "etl" });
console.log("attached", newArn);

What this demonstrates:

• Large layers ship from S3 (S3Bucket/S3Key), avoiding the inline ZipFile request-size limit.
• Layers on UpdateFunctionConfiguration replaces the whole list, so you must re-include layers you want to keep.
• Reading the current config first is how you preserve existing attachments before adding a new one.
• The architecture (arm64 here) must match the function's architecture.

Deep Dive

How Layers Land at Runtime

When a function starts, Lambda extracts each attached layer into /opt in the execution environment, in the order you listed them. Later layers overlay earlier ones, so ordering matters if two layers ship the same path. The runtime already searches conventional subpaths under /opt, so a layer only "just works" if its ZIP uses the right internal structure:

• Python: python/ or python/lib/python3.12/site-packages/
• Node.js: nodejs/node_modules/
• Any runtime, executables on PATH: bin/

Layers Are Immutable and Versioned

PublishLayerVersion always creates a new numbered version and returns a LayerVersionArn ending in :<version>. You never mutate an existing version. To roll out an update, publish a new version and repoint functions at the new ARN; to roll back, repoint them at the old one. Because the ARN is version-pinned, a function's behavior does not change until you explicitly move it.

Listing and Cleaning Up Versions

Old versions accumulate. Use list_layer_versions to enumerate and delete_layer_version to prune ones nothing references.

# --- Python (boto3) ---
import boto3
 
lam = boto3.client("lambda")
paginator = lam.get_paginator("list_layer_versions")
for page in paginator.paginate(LayerName="data-utils"):
    for v in page["LayerVersions"]:
        print(v["Version"], v["LayerVersionArn"])

// --- TypeScript (AWS SDK v3) ---
import { LambdaClient, paginateListLayerVersions } from "@aws-sdk/client-lambda";
 
const lam = new LambdaClient({});
for await (const page of paginateListLayerVersions({ client: lam }, { LayerName: "data-utils" })) {
  for (const v of page.LayerVersions ?? []) console.log(v.Version, v.LayerVersionArn);
}

Sharing Across Accounts

add_layer_version_permission grants another account (or the whole organization) permission to use a layer version. This is how a platform team publishes a base layer once and lets every account attach it.

Gotchas

• Attaching a bare layer name. Layers needs the full versioned ARN, not the layer name. Fix: use the LayerVersionArn returned by PublishLayerVersion.
• Dropping existing layers on update. UpdateFunctionConfiguration replaces the whole Layers list. Fix: read the current config and re-include the ARNs you want to keep.
• Wrong internal ZIP structure. Imports fail if libraries are not under python/ or nodejs/node_modules/. Fix: build the layer with the runtime's expected subpath.
• Architecture mismatch. An arm64 layer on an x86_64 function (or vice versa) fails. Fix: match CompatibleArchitectures to the function.
• Exceeding the size limit. The function plus all layers must stay under 250 MB unzipped. Fix: trim dependencies or move to a container image.
• More than five layers. A function accepts at most five. Fix: consolidate related dependencies into fewer layers.

Alternatives

FAQs

Related

• Lambda Deep Dive Basics - the UpdateFunctionConfiguration call layers ride on.
• Versions, Aliases & Traffic Shifting - version and route functions that use layers.
• Lambda via SDK Best Practices - deployment package hygiene defaults.
• Lambda's Execution Model for SDK Callers - why package size affects cold starts.

Stack versions: This page was written for boto3 1.43.x (Python 3.10+) and the AWS SDK for JavaScript v3 (Node.js 18+).