# aws lambda publish-version

AWS CLI commands · Updated 16 November 2026

**Short answer:** aws lambda publish-version --function-name my-function --description "release 1.4.2" freezes the current $LATEST code and configuration as a new numbered version. Versions are immutable; point an alias at the number to release it, and note that if nothing changed since the last version, Lambda returns that existing version instead of creating a new one.

## What the command does

Each published version is a read-only snapshot with its own ARN ending in `:N`. Numbers only go up and are never reused, even after a version is deleted. Invoking a version always runs exactly the code and settings it was published with, which is what makes aliases, safe rollbacks and features like SnapStart and provisioned concurrency possible.

## Syntax

```
aws lambda publish-version --function-name my-function \
  [--description "release 1.4.2"] \
  [--code-sha256 <expected hash>] \
  [--revision-id <expected revision>]
```

The response is the new version's configuration; the number is in `Version`.

## Worked examples

**Publish and capture the number:**

```
V=$(aws lambda publish-version --function-name my-function \
  --description "release $(git rev-parse --short HEAD)" \
  --query Version --output text)
echo "published version $V"
```

**Publish only if `$LATEST` holds the code you just built**, guarding against a concurrent deploy:

```
SHA=$(openssl dgst -sha256 -binary function.zip | base64)
aws lambda publish-version --function-name my-function --code-sha256 "$SHA"
```

If the hash does not match, the call fails rather than freezing someone else's code.

**Promote it** by pointing the alias your triggers use:

```
aws lambda update-alias --function-name my-function --name live --function-version "$V"
```

**Check what each alias currently points at**:

```
aws lambda list-aliases --function-name my-function \
  --query "Aliases[].[Name,FunctionVersion]" --output table
```

## Versions vs aliases vs $LATEST

| | Mutable? | Use for |
|---|---|---|
| `$LATEST` | Yes, every deploy changes it | Development, simple functions without staged releases |
| Version (`:7`) | No | Exact, reproducible deployments; rollback targets |
| Alias (`:live`) | Pointer can move | What triggers and callers should reference |

## Gotchas

- **"Why didn't I get a new version?"** Lambda skips publishing when neither code nor configuration changed since the last published version and returns that one. Scripts that expect a fresh number every time should compare `CodeSha256`.
- **Wait for updates first.** Publishing while a code or configuration update is in progress fails with `ResourceConflictException`. Run `aws lambda wait function-updated` beforehand.
- **Old versions use storage.** Each version's package counts towards the regional code storage quota; CI pipelines that publish on every commit eventually hit [CodeStorageExceededException](https://cloudconsole.dev/errors/lambda-codestorageexceeded).
- **Environment variables are frozen too.** To change a setting on a live version, update `$LATEST`, publish a new version and move the alias.
- **Permissions are per qualifier.** Resource-policy grants made on an alias do not automatically apply to other versions.
- **SnapStart applies to versions.** With SnapStart enabled, Lambda initialises the function and takes a snapshot during publishing, so the call takes longer and invocations of `$LATEST` do not benefit; only published versions and aliases pointing at them do.
- **Keep descriptions meaningful.** A build number or commit hash in `--description` is what makes a later rollback decision quick.

## Questions

### What is the difference between publish-version and publish-layer-version?

publish-version snapshots a function. publish-layer-version uploads a new version of a layer, which is a shared library package that functions reference.

### Can I edit a published Lambda version?

No. Versions are immutable. Change $LATEST, publish a new version and move your alias to it.

### How do I publish a version when deploying code?

Add --publish to update-function-code; it publishes a version once the code update completes.

## When this happens away from your desk

Knowing which version is live matters most when you are rolling one back under pressure. CloudConsole, a phone app for AWS, is built to show function errors and recent changes on a phone, with guardrails around production.

[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-version](https://docs.aws.amazon.com/cli/latest/reference/lambda/publish-version.html)
- [AWS Lambda Developer Guide](https://docs.aws.amazon.com/lambda/latest/dg/welcome.html)

## Related

- [aws lambda update-alias](https://cloudconsole.dev/cli/lambda-update-alias)
- [aws lambda list-versions-by-function](https://cloudconsole.dev/cli/lambda-list-versions-by-function)
- [How to roll back a Lambda version](https://cloudconsole.dev/how-to/roll-back-lambda-version)
- [aws lambda update-function-code](https://cloudconsole.dev/cli/lambda-update-function-code)
- [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-version

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