In AWS Lambda, what does attaching a layer actually do to the function's execution environment, and what limits and gotchas come with layers?

## What a layer is A Lambda layer is a .zip archive of libraries, a custom runtime, configuration files or executables that you publish as its own resource, independent of any function. A function then references specific **layer versions** by ARN. At most five. The mechanism is deliberately dumb, which is the key to reasoning about it: when Lambda creates an execution environment for a function, it extracts each referenced layer into the `/opt` directory before your initialization code runs. That is the whole feature. Everything else follows from where the runtime happens to look. ## Why /opt makes the libraries visible Each managed runtime is preconfigured with `/opt` paths on its search path, so a correctly structured layer needs no configuration at all: | Runtime | Path inside the layer .zip | |---|---| | Python | `python/` or `python/lib/python3.12/site-packages/` | | Node.js | `nodejs/node_modules/` | | Java | `java/lib/` | | Ruby | `ruby/lib/` | | Any (executables) | `bin/` — ends up on `PATH` | | Any (shared objects) | `lib/` — ends up on `LD_LIBRARY_PATH` | Getting this structure wrong is the single most common layer bug: a layer built by zipping `site-packages` directly, without the `python/` prefix, extracts to `/opt/<package>` and the import fails. The fix is always to check the archive listing before publishing. ```bash pip install requests -t python/ zip -r layer.zip python/ aws lambda publish-layer-version --layer-name shared-http \ --zip-file fileb://layer.zip --compatible-runtimes python3.12 ``` The `bin/` and `lib/` rows are the interesting ones: a layer is how you get a static `ffmpeg` binary or a compiled shared object into a zip-packaged function. Those binaries must be built for the runtime's operating system and CPU architecture — Amazon Linux for the managed runtimes, and `x86_64` versus `arm64` matters — which is why native layers are usually built inside a matching container. ## The limits - **Five layer versions per function.** A hard cap, not a soft one. - **250 MB unzipped, combined.** Function code plus every attached layer, measured after extraction. This is the limit people misunderstand most: layers do not enlarge the budget, they only move where the bytes are stored so the deployed artifact stays small and several functions can share one copy. - **Not available to container-image functions.** With an image you bake the same content in. - **Merge order matters.** Layers are extracted in the order listed on the function, so when two layers contain the same path, the later one wins. Relying on that is fragile; avoid overlapping layers. ## Immutability and the update problem Publishing a layer creates a new, immutable **layer version** with a monotonically increasing number, and functions reference `arn:aws:lambda:<region>:<account>:layer:<name>:<version>`. There is no "latest" alias. Republishing a fixed dependency therefore does *not* patch anything: every function referencing the old version keeps running the old bytes until someone updates its configuration and redeploys. This cuts both ways. It is a genuine safety property — nobody can change what your function loads out from under you, and deleting a layer version does not break functions already using it (though no new function can then attach it). It is also the operational cost of layers: a security fix in a shared layer becomes a fan-out task across every consumer, and without automation the fleet drifts. Teams that adopt layers heavily usually end up building exactly the tracking they were trying to avoid. ## Sharing across accounts A layer version carries a resource policy. `AddLayerVersionPermission` grants `lambda:GetLayerVersion` to another account, to an entire AWS Organization via the organization ID, or to everyone (`*`) for a public layer. That is how AWS itself distributes things like its parameter-and-secret caching extension, and how a platform team publishes a shared runtime helper once for all workload accounts. Treat making a layer public as a deliberate decision — you can't unpublish bytes people have already pulled. ## When a layer is the right tool — and when it isn't Good fits: an AWS-provided or vendor extension; a shared client wrapper, logging configuration or tracing bootstrap used by dozens of small functions; a native binary that would otherwise be duplicated in every artifact; a custom runtime. Poor fits: a layer used as a package manager. There is no dependency resolution, no version constraint solving, and no detection of a conflict between a library in a layer and the same library in the function package — the runtime simply finds whichever comes first on its search path, which produces mystifying behaviour. If your build tool can already vendor dependencies reproducibly into the artifact, and the artifact fits, that is usually the simpler answer.