View a markdown version of this page

Runtime versions - AWS Lambda

Runtime versions

A runtime version holds the contents of a customer-managed runtime. You publish it from a container image in Amazon Elastic Container Registry (Amazon ECR). Each time you update your runtime, for example to apply a patch, you publish a new runtime version. This topic is for runtime publishers. It explains how runtime versions work and how to manage them.

For an overview of customer-managed runtimes, see Customer-managed runtimes.

How runtime versions work

A runtime version is a child of a runtime. An image in Amazon ECR defines what each version contains. Versions are immutable. After you create a version, you can't change its image or capabilities. To change the runtime, you create a new version.

Each version has two identifiers:

  • Version name – A name that you choose when you create the version, such as v8.3.1. For more information, see Version names.

  • Version ARN – An Amazon Resource Name (ARN) that Lambda builds from the runtime ARN and the version name. The format is arn:aws:lambda:region:account-id:runtime/runtime-name/version/version-name.

    For example: arn:aws:lambda:us-east-1:123456789012:runtime/companyphp8/version/v8.3.1

No function uses a new version until you point a runtime alias to it. As a result, you can test a new version before you release it. How you test depends on whether this is the first version of the runtime:

To release the version, point an alias to it. For more information, see Runtime aliases.

After you create a runtime version, you can change only its release notes. For more information, see Update release notes.

Version names

You choose a name for each runtime version. The name is part of the version ARN. Names must meet the following requirements:

  • Contain 1–128 characters

  • Contain only uppercase and lowercase letters, numbers, underscores (_), periods (.), and hyphens (-)

  • Start and end with a letter, number, or underscore

  • Be unique within the runtime

We recommend names that show the order of your releases. Common schemes include the following:

  • Semantic versioning – For example, v8.3.1. Use this scheme when names track the language or your own release numbers.

  • Date-based versioning – For example, 2026-01-25.1. Use this scheme when you rebuild the runtime on a schedule, such as for security patches.

How Lambda processes your container image

When you create a version, you give the URI of an image in Amazon ECR. The URI can use a tag, such as companyphp8:v8.3.1, or a digest. Lambda then does the following:

  1. Resolves the URI to an image digest, and returns it in the ResolvedUri field. The version always uses this digest. If you later move the tag to a new image, the version doesn't change.

  2. Reads the platforms from the image manifest, and returns them in the Platforms field. Lambda uses them to find the supported architectures.

  3. Reads the compatibility settings from the image. For more information, see Runtime version compatibility.

  4. Ingests and optimizes the image for use with functions. During this step, the version is in the CREATING state. When it's done, the version moves to ACTIVE or FAILED.

The ResolvedUri, Platforms, and Compatibility fields appear as soon as you create the version. They don't change when the version becomes ACTIVE.

Supported architectures

Lambda reads the supported instruction set architectures from the image. You don't set them yourself.

  • Single-architecture image – The version supports one architecture: x86_64 or arm64.

  • Multi-architecture image – If the URI points to a manifest list (image index) with both architectures, the version supports x86_64 and arm64. Lambda uses the image that matches each function's architecture.

A version shows architectures in two fields, which use different names:

  • Platforms – Lists each platform in the image manifest. The Architecture value uses Open Container Initiative (OCI) names, such as amd64 and arm64.

  • Compatibility.Architectures – Lists the architectures in Lambda terms, such as x86_64 and arm64. The OCI name amd64 is the same as x86_64 in Lambda.

A new version can support different architectures than earlier versions. For example, you can add arm64 by publishing a multi-architecture version. However, you can point an alias to a version only if the version supports at least the architectures that the alias declares. For more information, see Alias compatibility. For instructions on building multi-architecture images, see Building runtime images.

Runtime version compatibility

Each version has a Compatibility object. It shows which features and architectures the version works with, such as the integration model, the supported architectures, and whether functions on Lambda Managed Instances can use the version. Lambda reads these values from the labels and platforms in the version's container image. If the image doesn't declare an integration model, Lambda uses RuntimeAPI. For more information about the labels that set a runtime's compatibility, see Architectures and feature compatibility.

You can't set the Compatibility object in the CreateRuntimeVersion request, and you can't change it after you create the version. The Compatibility object is read-only on a version. To change a version's compatibility, build a new image and publish a new version.

To view a version's compatibility, use the get-runtime-version command and check the Compatibility field. For more information, see View runtime versions.

Runtime version states

The State field shows the status of a version. The following table describes each state.

Runtime version states
State Description
CREATING Lambda is processing the image. You can't point an alias to the version or edit its release notes yet.
ACTIVE The version is ready. You can point an alias to it, pin a function to it, and edit its release notes.
FAILED Lambda couldn't process the image. You can't use the version. For more information, see If the version fails.
PENDING_DELETION The version is scheduled for deletion. Functions can't use it, and you can't modify it. You can restore it until the waiting period ends. For more information, see Resources scheduled for deletion.
DELETING Lambda is deleting the version.

An alias can point only to an ACTIVE version. Wait until the version is ACTIVE before you point an alias to it.

When you delete a version, Lambda schedules it for deletion and permanently deletes it after a waiting period that you choose, from 7 to 30 days. The default is 30 days. For more information, see Deleting and restoring runtimes.

Amazon ECR requirements

The image for a runtime version must meet the following requirements:

  • Repository location – The Amazon ECR repository must be in the same AWS Region as the runtime. The repository can be in a different AWS account. To use a runtime in more than one Region, replicate the image to a repository in each Region. For more information, see Deploying runtimes in multiple Regions.

  • Lambda access – The repository policy must grant the Lambda service principal permission to read the image. For instructions, see Grant Lambda access to your Amazon ECR repository.

  • Image retention – You must keep the image in Amazon ECR while the version exists. If you delete the image, functions that use the version become Inactive. This change can take up to 24 hours. Existing execution environments continue to handle invocations, but invocations that require a cold start fail. Deleting the repository or removing Lambda's access to the image has the same effect. The functions recover automatically after you restore the image. The version refers to the image by digest (ResolvedUri), so the restored image must have an identical digest. For more information, see Container images and charges. Standard Amazon ECR storage charges apply. Lambda doesn't charge for runtime versions. For more information, see Amazon ECR pricing.

  • Image size – For the maximum size of a runtime image, see Customer-managed runtimes in Lambda quotas.

Runtime consumers don't need access to your Amazon ECR images. They need only permission to use the runtime. For more information, see Sharing and controlling access to customer-managed runtimes.

Required permissions

To manage runtime versions, your IAM identity needs the following permissions:

  • lambda:CreateRuntimeVersion – Create a runtime version.

  • ecr:BatchGetImage and ecr:GetDownloadUrlForLayer on the Amazon ECR repository that contains the image – Create a runtime version from the image. The resource is the repository ARN, for example arn:aws:ecr:us-east-1:123456789012:repository/companyphp8.

  • lambda:GetRuntimeVersion – View a runtime version.

  • lambda:ListRuntimeVersions – List the versions of a runtime.

  • lambda:UpdateRuntimeVersion – Edit the release notes of a version.

  • lambda:DeleteRuntimeVersion – Delete a runtime version.

To create a runtime version, you need both Amazon ECR actions in addition to lambda:CreateRuntimeVersion. This requirement also applies to dry runs. Your identity needs these Amazon ECR permissions even after you grant Lambda access in the repository policy. If your identity lacks either Amazon ECR action, the request fails.

To grant Lambda access to your repository, you also need ecr:SetRepositoryPolicy. For more information about permissions, see Sharing and controlling access to customer-managed runtimes.

Prerequisites

Before you start, you need the following:

  • A runtime. For instructions, see Creating a runtime.

  • A runtime image pushed to an Amazon ECR repository. For instructions, see Building runtime images.

  • The AWS CLI, if you use the command line. The examples use a runtime and an Amazon ECR repository named companyphp8 in us-east-1.

Grant Lambda access to your Amazon ECR repository

Lambda must be able to read your runtime image from Amazon ECR. To allow this, add a repository policy for the Lambda service principal. You do this one time for each repository.

Lambda uses ecr:BatchGetImage and ecr:GetDownloadUrlForLayer to read the image. Lambda also needs ecr:DescribeImages when functions that use the runtime run on Lambda Managed Instances.

To grant Lambda access to an Amazon ECR repository (AWS CLI)
  1. Create a file named ecr-policy.json with the following content:

    { "Version": "2012-10-17", "Statement": [ { "Sid": "LambdaReadAccess", "Effect": "Allow", "Principal": { "Service": "lambda.amazonaws.com" }, "Action": [ "ecr:BatchGetImage", "ecr:DescribeImages", "ecr:GetDownloadUrlForLayer" ], "Condition": { "StringEquals": { "aws:SourceAccount": "123456789012" }, "ArnLike": { "aws:SourceArn": "arn:aws:lambda:us-east-1:123456789012:runtime/*" } } } ] }

    The conditions restrict access to runtimes in your account. The value of aws:SourceArn is the runtime ARN, not the runtime version ARN.

  2. Run the following command to apply the policy to your repository:

    aws ecr set-repository-policy \ --repository-name companyphp8 \ --policy-text file://ecr-policy.json \ --region us-east-1

The command returns the repository name and policy. If the repository has a policy, this command replaces it. To keep your current statements, add the LambdaReadAccess statement to your policy instead. For more information, see Setting a private repository policy statement in the Amazon Elastic Container Registry User Guide.

Create a runtime version

You can create a runtime version by using the Lambda console or the AWS CLI. Before you use the version, wait until it's ACTIVE.

Create a runtime version (console)

To create a runtime version (console)
  1. Open the Runtimes page of the Lambda console.

  2. Choose the runtime, and then choose the Versions tab.

  3. Choose Create version.

  4. For Runtime version name, enter a name for the version. The version name must be unique for this runtime.

  5. For Image source, do one of the following:

    • To use an image in your account, make sure that Owned by you is selected. Choose Browse ECR, and then select the Amazon ECR repository and the runtime version image.

    • To use an image that another account shared with you, select Shared with you, and then paste the URI of the container image.

  6. Optionally, enter Release notes for the runtime version.

  7. Choose Create version.

The new runtime version starts in the CREATING state. After Lambda ingests and processes the Amazon ECR image, the version moves to the ACTIVE state and is ready to use.

Create a runtime version (AWS CLI)

To create a runtime version (AWS CLI)
  1. (Optional) To check the request without creating a version, add the --dry-run option:

    aws lambda-core create-runtime-version \ --runtime-name companyphp8 \ --name v8.3.1 \ --image-uri 123456789012.dkr.ecr.us-east-1.amazonaws.com/companyphp8:v8.3.1 \ --dry-run

    A dry run checks the image URI, that the image exists, that Lambda can access it, and that the version name is valid and not in use. If the checks pass, the command returns the version details that Lambda would create, but doesn't create the version. A dry run doesn't check that the runtime exists.

  2. To create the version, run the create-runtime-version command:

    aws lambda-core create-runtime-version \ --runtime-name companyphp8 \ --name v8.3.1 \ --image-uri 123456789012.dkr.ecr.us-east-1.amazonaws.com/companyphp8:v8.3.1 \ --release-notes "Updates PHP to 8.3.1 and applies the latest OS security patches."

    The command uses the following options:

    • --runtime-name – The name or ARN of the runtime.

    • --name – The name of the new version.

    • --image-uri – The image URI in Amazon ECR, with a tag or a digest.

    • --release-notes – (Optional) What changed in this version.

    The following example shows the output for a multi-architecture image. The version is CREATING.

    { "Name": "v8.3.1", "Arn": "arn:aws:lambda:us-east-1:123456789012:runtime/companyphp8/version/v8.3.1", "ResolvedUri": "123456789012.dkr.ecr.us-east-1.amazonaws.com/companyphp8@sha256:9b2c4e7a1d3f5a8c6e0b2d4f6a8c0e2b4d6f8a0c2e4b6d8f0a2c4e6b8d0f2a4c", "State": "CREATING", "ReleaseNotes": "Updates PHP to 8.3.1 and applies the latest OS security patches.", "Platforms": [ { "Architecture": "amd64", "Os": "linux", "Digest": "sha256:3e5a7c9b1d2f4a6c8e0b1d3f5a7c9e1b3d5f7a9c1e3b5d7f9a1c3e5b7d9f1a3e" }, { "Architecture": "arm64", "Os": "linux", "Digest": "sha256:7c1e3a5b9d2f4c6e8a0b2d4f6c8e0a2b4d6f8c0e2a4b6d8f0c2e4a6b8d0f2c4e" } ], "Compatibility": { "IntegrationModels": [ "RuntimeAPI" ], "Architectures": [ "x86_64", "arm64" ], "ManagedInstances": "Supported" }, "Created": "2026-10-05T10:53:38.719Z", "LastModified": "2026-10-05T10:53:39.260Z" }
  3. To wait until the version is ready, run the following command:

    aws lambda-core wait runtime-version-active \ --runtime-name companyphp8 \ --name v8.3.1

    The command returns when the version is ACTIVE. If the version fails, the command returns an error.

  4. To confirm the state, run the get-runtime-version command:

    aws lambda-core get-runtime-version \ --runtime-name companyphp8 \ --name v8.3.1 \ --query State

    You should see the following output:

    "ACTIVE"

When the version is ACTIVE, you can test it with a pinned function, and then point an alias to it. For more information, see Next steps.

If the version fails

If Lambda can't process the image, the version enters the FAILED state. You can't use a failed version. To fix it, check the following:

After you fix the issue, create a new version with a new name. You can delete the failed version. Its name stays reserved until Lambda permanently deletes it. After that, you can reuse the name. For more information, see Deleting and restoring runtimes.

View runtime versions

To view a version, including its platforms, run the get-runtime-version command:

aws lambda-core get-runtime-version \ --runtime-name companyphp8 \ --name v8.3.1

The output has the same fields as the output of create-runtime-version.

To list all versions of a runtime, run the list-runtime-versions command:

aws lambda-core list-runtime-versions \ --runtime-name companyphp8

You should see output similar to the following:

{ "Items": [ { "Name": "v8.3.1", "Arn": "arn:aws:lambda:us-east-1:123456789012:runtime/companyphp8/version/v8.3.1", "ResolvedUri": "123456789012.dkr.ecr.us-east-1.amazonaws.com/companyphp8@sha256:9b2c4e7a1d3f5a8c6e0b2d4f6a8c0e2b4d6f8a0c2e4b6d8f0a2c4e6b8d0f2a4c", "State": "ACTIVE", "ReleaseNotes": "Updates PHP to 8.3.1 and applies the latest OS security patches.", "Compatibility": { "IntegrationModels": [ "RuntimeAPI" ], "Architectures": [ "x86_64", "arm64" ], "ManagedInstances": "Supported" }, "Created": "2026-10-05T10:53:38.719Z", "LastModified": "2026-10-05T10:53:46.031Z" } ] }

The list output doesn't include the Platforms field. To see the platforms of a version, use get-runtime-version.

Update release notes

You can change only the release notes of a version. The version must be ACTIVE. The new notes replace the old ones.

Console
To update release notes (console)
  1. Open the Runtimes page of the Lambda console.

  2. Choose the runtime, and then choose the Versions tab.

  3. Select the check box next to the runtime version to update.

  4. Choose Version actions, and then choose Edit release notes.

  5. In the Edit release notes for version dialog box, edit the release notes.

  6. Choose Save.

AWS CLI

To update the release notes, run the update-runtime-version command:

aws lambda-core update-runtime-version \ --runtime-name companyphp8 \ --name v8.3.1 \ --release-notes "Updates PHP to 8.3.1 and applies OS security patches from October 2026."

The output shows the new notes in the ReleaseNotes field.

Delete runtime versions

You can delete versions that you don't need. You can't delete a version while a runtime alias points to it. For more information, see Deleting and restoring runtimes.

Next steps

After your runtime version is ACTIVE, see the following topics: