# aws lambda list-versions-by-function

AWS CLI commands · Updated 16 November 2026

**Short answer:** aws lambda list-versions-by-function --function-name my-function lists $LATEST and every published version with its description, code hash, size and date. Combine it with list-aliases to find versions nothing points to, which you can delete to free code storage.

## What the command does

The response's `Versions[]` holds one full configuration object per version, starting with `$LATEST` and then published versions in ascending order. Each entry carries `Version`, `Description`, `CodeSha256`, `CodeSize`, `LastModified`, `Runtime` and the rest of the frozen settings. The CLI follows pagination automatically (the API returns at most 50 per page).

## Syntax

```
aws lambda list-versions-by-function --function-name my-function [--max-items 50] [--query ...]
```

A trimmed entry for one published version looks like this:

```
{
  "FunctionName": "my-function",
  "FunctionArn": "arn:aws:lambda:eu-west-2:123456789012:function:my-function:14",
  "Version": "14",
  "Description": "release 9f3c2ab",
  "Runtime": "python3.13",
  "CodeSize": 2483021,
  "CodeSha256": "kq0Yx3b1vQh5J1m0dQ0b6r8l2Gf9yQb8m0W2n3r4s5Q=",
  "LastModified": "2026-11-12T16:41:09.112+0000"
}
```

The `$LATEST` entry has an unqualified ARN, and its `LastModified` moves with every deploy, while published versions keep the timestamp from when they were created. That difference is a quick way to tell whether `$LATEST` has drifted from the newest published version: if its `CodeSha256` matches the highest version's, nothing has been deployed since the last publish.

## Worked examples

**Published versions as a table** (the backslash stops the shell expanding `$LATEST`):

```
aws lambda list-versions-by-function --function-name my-function \
  --query "Versions[?Version!='\$LATEST'].[Version,LastModified,Description,CodeSize]" \
  --output table
```

**Highest version number**. Versions are strings, so convert before taking the maximum:

```
aws lambda list-versions-by-function --function-name my-function \
  --query "max(Versions[?Version!='\$LATEST'].to_number(Version))" --output json
```

**Versions referenced by aliases** (including canary weights):

```
aws lambda list-aliases --function-name my-function \
  --query "Aliases[].[Name,FunctionVersion,join(',',keys(RoutingConfig.AdditionalVersionWeights || \`{}\`))]" \
  --output text
```

**Delete old versions nobody uses**, keeping the newest five and anything an alias points to. Review the list before uncommenting the delete:

```
FN=my-function
KEEP=$(aws lambda list-aliases --function-name $FN \
  --query "Aliases[].FunctionVersion" --output text)
for v in $(aws lambda list-versions-by-function --function-name $FN \
    --query "Versions[?Version!='\$LATEST'].Version" --output json \
    | jq -r '.[]' | sort -n | head -n -5); do
  case " $KEEP " in *" $v "*) continue;; esac
  echo "would delete $FN:$v"
  # aws lambda delete-function --function-name $FN --qualifier $v
done
```

`head -n -5` is GNU syntax; on macOS use `ghead` or `sed '$d'` repeatedly.

## Fields worth checking

| Field | Why |
|---|---|
| `CodeSha256` | Identical hashes across versions mean only configuration changed. |
| `CodeSize` | Each version counts towards the regional code storage quota. |
| `Runtime` | Old versions can sit on deprecated runtimes long after `$LATEST` was upgraded. |
| `Description` | Put a build ID or Git SHA here when publishing so this listing is meaningful. |

## Gotchas

- **Deleting a version an alias uses fails**, which is a safety net, but deleting one that an event source mapping or API integration references by version ARN breaks that caller.
- **Version numbers are never reused.** After deleting version 12, the next publish is still 13 or higher.
- **Text output applies queries per page**, so `max()` needs JSON output on functions with more than 50 versions.
- **Not a list of triggers.** To see what invokes a version, check event source mappings and the resource policy for that qualifier.

## Questions

### How do I get the latest Lambda version number?

Query max(Versions[?Version!='$LATEST'].to_number(Version)) with JSON output, escaping the $ in your shell.

### How do I delete old Lambda versions?

Use aws lambda delete-function --function-name my-function --qualifier N for each unused version. Aliased versions cannot be deleted until the alias moves.

### How do I list all Lambda functions rather than versions?

Use aws lambda list-functions --query "Functions[].FunctionName" --output text.

## When this happens away from your desk

When you need to roll back, the first question is which version was good. CloudConsole, a phone app for AWS, is built to show functions, versions and their error rates 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 list-versions-by-function](https://docs.aws.amazon.com/cli/latest/reference/lambda/list-versions-by-function.html)
- [AWS Lambda Developer Guide](https://docs.aws.amazon.com/lambda/latest/dg/welcome.html)

## Related

- [aws lambda publish-version](https://cloudconsole.dev/cli/lambda-publish-version)
- [aws lambda update-alias](https://cloudconsole.dev/cli/lambda-update-alias)
- [CodeStorageExceededException: Code storage limit exceeded](https://cloudconsole.dev/errors/lambda-codestorageexceeded)
- [How to roll back a Lambda version](https://cloudconsole.dev/how-to/roll-back-lambda-version)
- [aws lambda list-functions](https://cloudconsole.dev/cli/lambda-list-functions)
- [aws lambda add-permission](https://cloudconsole.dev/cli/lambda-add-permission)

---

Source: https://cloudconsole.dev/cli/lambda-list-versions-by-function

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