# aws lambda publish-layer-version

AWS CLI commands · Updated 16 November 2026

**Short answer:** aws lambda publish-layer-version --layer-name deps --content S3Bucket=my-artifacts,S3Key=layers/deps.zip --compatible-runtimes python3.13 creates a new, immutable version of a Lambda layer. Functions do not pick it up automatically: update each function's --layers to the new version ARN.

## What the command does

A layer is a zip of libraries, runtimes or data that Lambda extracts into `/opt` in the execution environment. Every publish creates a new version number with its own ARN (`...:layer:deps:8`); existing versions never change. The response returns `LayerVersionArn`, which is what you attach to functions.

## Syntax

```
aws lambda publish-layer-version --layer-name deps \
  --content S3Bucket=my-artifacts,S3Key=layers/deps.zip \
  [--compatible-runtimes python3.12 python3.13] \
  [--compatible-architectures x86_64 arm64] \
  [--description "requests 2.32, pydantic 2.9"] \
  [--license-info MIT]
```

For small zips the CLI also accepts a local file with `--zip-file fileb://deps.zip` in place of `--content`.

## Worked examples

**Build a Python dependencies layer**. The zip must contain a `python/` folder at its root:

```
mkdir -p build/python
pip install -r requirements.txt -t build/python \
  --platform manylinux2014_aarch64 --only-binary=:all: --python-version 3.13
(cd build && zip -r ../deps.zip python)
aws s3 cp deps.zip s3://my-artifacts/layers/deps.zip
ARN=$(aws lambda publish-layer-version --layer-name deps \
  --content S3Bucket=my-artifacts,S3Key=layers/deps.zip \
  --compatible-runtimes python3.13 --compatible-architectures arm64 \
  --query LayerVersionArn --output text)
```

**Attach it to a function**. `--layers` replaces the whole list, so include any other layers the function uses:

```
aws lambda update-function-configuration --function-name my-function --layers "$ARN"
```

**List versions of a layer**:

```
aws lambda list-layer-versions --layer-name deps \
  --query "LayerVersions[].[Version,CreatedDate,Description]" --output table
```

**Share a layer version with another account**:

```
aws lambda add-layer-version-permission --layer-name deps --version-number 8 \
  --statement-id share-210987654321 --action lambda:GetLayerVersion \
  --principal 210987654321
```

## Folder layout by runtime

| Runtime | Path inside the zip |
|---|---|
| Python | `python/` (or `python/lib/python3.x/site-packages/`) |
| Node.js | `nodejs/node_modules/` |
| Java | `java/lib/` |
| Binaries and shared libraries | `bin/` and `lib/` |

A wrong top-level folder is the most common reason a function cannot import a package that is "in the layer".

## Gotchas

- **Size limits are shared.** The function's code plus all its layers must fit within the unzipped deployment package limit (250 MB at the time of writing), and a function can use at most five layers.
- **Native wheels must match.** Packages with compiled code need to be built for Amazon Linux and the function's architecture; building on a Mac usually produces the wrong binaries.
- **`--compatible-runtimes` is metadata.** It filters layer choices in the console but does not stop you attaching an incompatible layer.
- **Old versions stay until deleted** and count towards code storage. Remove unused ones with `delete-layer-version`; functions already using a deleted version keep working.
- **Layer references always include a version.** When attaching a layer you must give the full version ARN; there is no "latest" alias for layers, so pipelines need to pass the new ARN to every function that should use it.

## Questions

### How do I publish a Lambda layer from the CLI?

Zip your files in the runtime's expected folder, upload to S3 (or use --zip-file fileb:// for small zips) and run publish-layer-version with --layer-name and --content.

### Do functions update automatically when I publish a new layer version?

No. Each function references a specific layer version ARN; update its --layers to use the new one.

### How do I publish a new function version rather than a layer?

Use aws lambda publish-version --function-name my-function.

## When this happens away from your desk

Dependency problems from a new layer usually show up as import errors right after a deploy. CloudConsole, a phone app for AWS, is built to show function errors and the log lines behind them on a phone.

[About the CloudConsole app](https://cloudconsole.dev/aws-console-app) · [Download on the App Store](https://apps.apple.com/app/cloudconsole-for-aws/id6835419710)

## Sources

- [AWS CLI Command Reference: lambda publish-layer-version](https://docs.aws.amazon.com/cli/latest/reference/lambda/publish-layer-version.html)
- [AWS Lambda Developer Guide](https://docs.aws.amazon.com/lambda/latest/dg/welcome.html)

## Related

- [aws lambda update-function-configuration](https://cloudconsole.dev/cli/lambda-update-function-configuration)
- [aws lambda publish-version](https://cloudconsole.dev/cli/lambda-publish-version)
- [Unzipped size must be smaller than 262144000 bytes](https://cloudconsole.dev/errors/lambda-unzipped-size-too-large)
- [Runtime.ImportModuleError: Unable to import module](https://cloudconsole.dev/errors/lambda-runtime-importmoduleerror)
- [CodeStorageExceededException: Code storage limit exceeded](https://cloudconsole.dev/errors/lambda-codestorageexceeded)
- [aws lambda add-permission](https://cloudconsole.dev/cli/lambda-add-permission)

---

Source: https://cloudconsole.dev/cli/lambda-publish-layer-version

CloudConsole is an independent iPhone and Android app for Amazon Web Services by Cloudconcur Ltd. It is not affiliated with Amazon Web Services.
