# Understanding how Lambda manages runtime version updates
<a name="runtimes-update"></a>

Lambda keeps each managed runtime up to date with security updates, bug fixes, new features, performance enhancements, and support for minor version releases. These runtime updates are published as *runtime versions*. Lambda applies runtime updates to functions by migrating the function from an earlier runtime version to a new runtime version.

By default, for functions using managed runtimes, Lambda applies runtime updates automatically. With automatic runtime updates, Lambda takes on the operational burden of patching the runtime versions. For most customers, automatic updates are the right choice. You can change this default behavior by [configuring runtime management settings](runtime-management-configure-settings.md).

Lambda also publishes each new runtime version as a container image. To update runtime versions for container-based functions, you must [create a new container image](images-create.md) from the updated base image and redeploy your function.

Each runtime version is associated with a version number and an ARN (Amazon Resource Name). Runtime version numbers use a numbering scheme that Lambda defines, independent of the version numbers that the programming language uses. Runtime version numbers are not always sequential. For example, version 42 might be followed by version 45. The runtime version ARN is a unique identifier for each runtime version. You can view the ARN of your function's current runtime version in the Lambda console, or the [`INIT_START` line of your function logs](runtime-management-identify.md).

Runtime versions should not be confused with runtime identifiers. Each runtime has a unique **runtime identifier**, such as `python3.14` or `nodejs24.x`. These correspond to each major programming language release. Runtime versions describe the patch version of an individual runtime.

**Note**  
The ARN for the same runtime version number can vary between AWS Regions and CPU architectures.

**Topics**
+ [

## Backward compatibility
](#runtime-update-compatibility)
+ [

## Runtime update modes
](#runtime-management-controls)
+ [

## Two-phase runtime version rollout
](#runtime-management-two-phase)
+ [

# Configuring Lambda runtime management settings
](runtime-management-configure-settings.md)
+ [

# Rolling back a Lambda runtime version
](runtime-management-rollback.md)
+ [

# Identifying Lambda runtime version changes
](runtime-management-identify.md)
+ [

# Understanding the shared responsibility model for Lambda runtime management
](runtime-management-shared.md)
+ [

# Controlling Lambda runtime update permissions for high-compliance applications
](runtime-management-hc-applications.md)

## Backward compatibility
<a name="runtime-update-compatibility"></a>

Lambda strives to provide runtime updates that are backward compatible with existing functions. However, as with software patching, there are rare cases in which a runtime update can negatively impact an existing function. For example, security patches can expose an underlying issue with an existing function that depends on the previous, insecure behavior.

When building and deploying your function, it is important to understand how to manage your dependencies to avoid potential incompatibilities with a future runtime update. For example, suppose your function has a dependency on package A, which in turn depends on package B. Both packages are included in the Lambda runtime (for example, they could be parts of the SDK or its dependencies, or parts of the runtime system libraries).

Consider the following scenarios:


| Deployment | Patching compatible | Reason | 
| --- | --- | --- | 
|  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/lambda/latest/dg/runtimes-update.html)  | Yes | Future runtime updates to packages A and B are backward compatible. | 
|  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/lambda/latest/dg/runtimes-update.html)  | Yes | Your deployment takes precedence, so future runtime updates to packages A and B have no effect. | 
|  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/lambda/latest/dg/runtimes-update.html)  | Yes\$1 |  Future runtime updates to package B are backward compatible. \$1If A and B are tightly coupled, compatibility issues can occur. For example, the `boto3` and `botocore` packages in the AWS SDK for Python should be deployed together.  | 
|  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/lambda/latest/dg/runtimes-update.html)  | No | Future runtime updates to package A might require an updated version of package B. However, the deployed version of package B takes precedence, and might not be forward compatible with the updated version of package A. | 

To maintain compatibility with future runtime updates, follow these best practices:
+ **When possible, package all dependencies:** Include all required libraries, including the AWS SDK and its dependencies, in your deployment package. This ensures a stable, compatible set of components.
+ **Use runtime-provided SDKs sparingly:** Only rely on the runtime-provided SDK when you can't include additional packages (for example, when using the Lambda console code editor or inline code in an AWS CloudFormation template).
+ **Avoid overriding system libraries:** Don't deploy custom operating system libraries that may conflict with future runtime updates.

## Runtime update modes
<a name="runtime-management-controls"></a>

Lambda strives to provide runtime updates that are backward compatible with existing functions. However, as with software patching, there are rare cases in which a runtime update can negatively impact an existing function. For example, security patches can expose an underlying issue with an existing function that depends on the previous, insecure behavior. Lambda runtime management controls help reduce the risk of impact to your workloads in the rare event of a runtime version incompatibility. For each [function version](configuration-versions.md) (`$LATEST` or published version), you can choose one of the following runtime update modes:
+ **Auto (default)** – Automatically update to the most recent and secure runtime version using [Two-phase runtime version rollout](#runtime-management-two-phase). We recommend this mode for most customers so that you always benefit from runtime updates.
+ **Function update** – Update to the most recent and secure runtime version when you update your function. When you update your function, Lambda updates the runtime of your function to the most recent and secure runtime version. This approach synchronizes runtime updates with function deployments, giving you control over when Lambda applies runtime updates. With this mode, you can detect and mitigate rare runtime update incompatibilities early. When using this mode, you must regularly update your functions to keep their runtime up to date.
+ **Manual** – Manually update your runtime version. You specify a runtime version in your function configuration. The function uses this runtime version indefinitely. In the rare case in which a new runtime version is incompatible with an existing function, you can use this mode to roll back your function to an earlier runtime version. We recommend against using **Manual** mode to try to achieve runtime consistency across deployments. For more information, see [Rolling back a Lambda runtime version](runtime-management-rollback.md).

Responsibility for applying runtime updates to your functions varies according to which runtime update mode you choose. For more information, see [Understanding the shared responsibility model for Lambda runtime management](runtime-management-shared.md).

## Two-phase runtime version rollout
<a name="runtime-management-two-phase"></a>

Lambda introduces new runtime versions in the following order:

1. In the first phase, Lambda applies the new runtime version whenever you create or update a function. A function gets updated when you call the [UpdateFunctionCode](https://docs.aws.amazon.com/lambda/latest/api/API_UpdateFunctionCode.html) or [UpdateFunctionConfiguration](https://docs.aws.amazon.com/lambda/latest/api/API_UpdateFunctionConfiguration.html) API operations.

1. In the second phase, Lambda updates any function that uses the **Auto** runtime update mode and that hasn't already been updated to the new runtime version. 

The overall duration of the rollout process varies according to multiple factors, including the severity of any security patches included in the runtime update.

If you're actively developing and deploying your functions, you will most likely pick up new runtime versions during the first phase. This synchronizes runtime updates with function updates. In the rare event that the latest runtime version negatively impacts your application, this approach lets you take prompt corrective action. Functions that aren't in active development still receive the operational benefit of automatic runtime updates during the second phase.

This approach doesn't affect functions set to **Function update** or **Manual** mode. Functions using **Function update** mode receive the latest runtime updates only when you create or update them. Functions using **Manual** mode don't receive runtime updates.

Lambda publishes new runtime versions in a gradual, rolling fashion across AWS Regions. If your functions are set to **Auto** or **Function update** modes, it's possible that functions deployed at the same time to different Regions, or at different times in the same Region, will pick up different runtime versions. Customers who require guaranteed runtime version consistency across their environments should [use container images to deploy their Lambda functions](images-create.md). The **Manual** mode is designed as a temporary mitigation to enable runtime version rollback in the rare event that a runtime version is incompatible with your function.

# Configuring Lambda runtime management settings
<a name="runtime-management-configure-settings"></a>

You can configure runtime management settings using the Lambda console or the AWS Command Line Interface (AWS CLI).

**Note**  
You can configure runtime management settings separately for each [function version](configuration-versions.md).

**To configure how Lambda updates your runtime version (console)**

1. Open the [Functions page](https://console.aws.amazon.com/lambda/home#/functions) of the Lambda console.

1. Choose the name of a function.

1. On the **Code** tab, under **Runtime settings**, choose **Edit runtime management configuration**.

1. Under **Runtime management configuration**, choose one of the following:
   + To have your function update to the latest runtime version automatically, choose **Auto**.
   + To have your function update to the latest runtime version when you change the function, choose **Function update**.
   + To have your function update to the latest runtime version only when you change the runtime version ARN, choose **Manual**. You can find the runtime version ARN under **Runtime management configuration**. You can also find the ARN in the `INIT_START` line of your function logs.

   For more information about these options, see [Runtime update modes](runtimes-update.md#runtime-management-controls).

1. Choose **Save**.

**To configure how Lambda updates your runtime version (AWS CLI)**

To configure runtime management for a function, run the [put-runtime-management-config](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/lambda/put-runtime-management-config.html) AWS CLI command. When using `Manual` mode, you must also provide the runtime version ARN.

```
aws lambda put-runtime-management-config \
  --function-name my-function \
  --update-runtime-on Manual \
  --runtime-version-arn arn:aws:lambda:us-east-2::runtime:8eeff65f6809a3ce81507fe733fe09b835899b99481ba22fd75b5a7338290ec1
```

You should see output similar to the following:

```
{
  "UpdateRuntimeOn": "Manual",
  "FunctionArn": "arn:aws:lambda:us-east-2:111122223333:function:my-function",
  "RuntimeVersionArn": "arn:aws:lambda:us-east-2::runtime:8eeff65f6809a3ce81507fe733fe09b835899b99481ba22fd75b5a7338290ec1"
}
```

# Rolling back a Lambda runtime version
<a name="runtime-management-rollback"></a>

In the rare event that a new runtime version is incompatible with your existing function, you can roll back its runtime version to an earlier one. This keeps your application working and minimizes disruption, providing time to remedy the incompatibility before returning to the latest runtime version.

Lambda doesn't impose a time limit on how long you can use any particular runtime version. However, we strongly recommend updating to the latest runtime version as soon as possible to benefit from the latest security patches, performance improvements, and features. Lambda provides the option to roll back to an earlier runtime version only as a temporary mitigation in the rare event of a runtime update compatibility issue. Functions using an earlier runtime version for an extended period may eventually experience degraded performance or issues, such as a certificate expiry, which can cause them to stop working properly.

You can roll back a runtime version in the following ways:
+ [Using the Manual runtime update mode](#runtime-management-rollback-manual)
+ [Using published function versions](#runtime-management-rollback-published)

For more information, see [Introducing AWS Lambda runtime management controls](https://aws.amazon.com/blogs/compute/introducing-aws-lambda-runtime-management-controls/) on the AWS Compute Blog.

## Roll back a runtime version using Manual runtime update mode
<a name="runtime-management-rollback-manual"></a>

If you're using the **Auto** runtime version update mode, or you're using the `$LATEST` runtime version, you can roll back your runtime version using the **Manual** mode. For the [function version](configuration-versions.md) you want to roll back, change the runtime version update mode to **Manual** and specify the ARN of the previous runtime version. For more information about finding the ARN of the previous runtime version, see [Identifying Lambda runtime version changes](runtime-management-identify.md).

**Note**  
If the `$LATEST` version of your function is configured to use **Manual** mode, then you can't change the CPU architecture or runtime version that your function uses. To make these changes, you must change to **Auto** or **Function update** mode.

## Roll back a runtime version using published function versions
<a name="runtime-management-rollback-published"></a>

Published [function versions](configuration-versions.md) are an immutable snapshot of the `$LATEST` function code and configuration at the time that you created them. In **Auto** mode, Lambda automatically updates the runtime version of published function versions during phase two of the runtime version rollout. In **Function update** mode, Lambda doesn't update the runtime version of published function versions.

Published function versions using **Function update** mode therefore create a static snapshot of the function code, configuration, and runtime version. By using **Function update** mode with function versions, you can synchronize runtime updates with your deployments. You can also coordinate rollback of code, configuration, and runtime versions by redirecting traffic to an earlier published function version. You can integrate this approach into your continuous integration and continuous delivery (CI/CD) for fully automatic rollback in the rare event of runtime update incompatibility. When using this approach, you must update your function regularly and publish new function versions to pick up the latest runtime updates. For more information, see [Understanding the shared responsibility model for Lambda runtime management](runtime-management-shared.md).

# Identifying Lambda runtime version changes
<a name="runtime-management-identify"></a>

The [runtime version number](runtimes-update.md) and ARN are logged in the `INIT_START` log line, which Lambda emits to CloudWatch Logs each time that it creates a new [execution environment](concepts-basics.md#gettingstarted-concepts-runtime). Because the execution environment uses the same runtime version for all function invocations, Lambda emits the `INIT_START` log line only when Lambda executes the init phase. Lambda doesn't emit this log line for each function invocation. Lambda emits the log line to CloudWatch Logs, but it is not visible in the console. 

**Note**  
Runtime version numbers are not always sequential. For example, version 42 might be followed by version 45.

**Example INIT\$1START log line**  

```
INIT_START Runtime Version: python:3.13.v14    Runtime Version ARN: arn:aws:lambda:eu-south-1::runtime:7b620fc2e66107a1046b140b9d320295811af3ad5d4c6a011fad1fa65127e9e6I
```

Rather than working directly with the logs, you can use [Amazon CloudWatch Contributor Insights](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/ContributorInsights-CreateRule.html) to identify transitions between runtime versions. The following rule counts the distinct runtime versions from each `INIT_START` log line. To use the rule, replace the example log group name `/aws/lambda/*` with the appropriate prefix for your function or group of functions.

```
{
  "Schema": {
    "Name": "CloudWatchLogRule",
    "Version": 1
  },
  "AggregateOn": "Count",
  "Contribution": {
    "Filters": [
      {
        "Match": "eventType",
        "In": [
          "INIT_START"
        ]
      }
    ],
    "Keys": [
      "runtimeVersion",
      "runtimeVersionArn"
    ]
  },
  "LogFormat": "CLF",
  "LogGroupNames": [
    "/aws/lambda/*"
  ],
  "Fields": {
    "1": "eventType",
    "4": "runtimeVersion",
    "8": "runtimeVersionArn"
  }
}
```

The following CloudWatch Contributor Insights report shows an example of a runtime version transition as captured by the preceding rule. The orange line shows execution environment initialization for the earlier runtime version (**python:3.13.v12**), and the blue line shows execution environment initialization for the new runtime version (**python:3.13.v14**).

![\[\]](http://docs.aws.amazon.com/lambda/latest/dg/images/runtime_version_graph.png)


# Understanding the shared responsibility model for Lambda runtime management
<a name="runtime-management-shared"></a>

Lambda is responsible for curating and publishing security updates for all supported managed runtimes and container images. Responsibility for updating existing functions to use the latest runtime version varies depending on which runtime update mode you use.

Lambda is responsible for applying runtime updates to all functions configured to use the **Auto** runtime update mode.

For functions configured with the **Function update** runtime update mode, you're responsible for regularly updating your function. Lambda is responsible for applying runtime updates when you make those updates. If you don't update your function, then Lambda doesn't update the runtime. If you don't regularly update your function, then we strongly recommend configuring it for automatic runtime updates so that it continues to receive security updates.

For functions configured to use the **Manual** runtime update mode, you're responsible for updating your function to use the latest runtime version. We strongly recommend that you use this mode only to roll back the runtime version as a temporary mitigation in the rare event of runtime update incompatibility. We also recommend that you change to **Auto** mode as quickly as possible to minimize the time in which your functions aren't patched.

If you're [using container images to deploy your functions](images-create.md), then Lambda is responsible for publishing updated base images. In this case, you're responsible for rebuilding your function's container image from the latest base image and redeploying the container image.

This is summarized in the following table:


****  

| Deployment mode | Lambda's responsibility | Customer's responsibility | 
| --- | --- | --- | 
| Managed runtime, Auto mode |  Publish new runtime versions containing the latest patches. Apply runtime patches to existing functions.  | Roll back to a previous runtime version in the rare event of a runtime update compatibility issue. Follow best practices for [backward compatibility](runtimes-update.md#runtime-update-compatibility). | 
| Managed runtime, Function update mode | Publish new runtime versions containing the latest patches. |  Update functions regularly to pick up the latest runtime version. Switch a function to **Auto** mode when you're not regularly updating the function. Roll back to a previous runtime version in the rare event of a runtime update compatibility issue. Follow best practices for [backward compatibility](runtimes-update.md#runtime-update-compatibility).  | 
| Managed runtime, Manual mode | Publish new runtime versions containing the latest patches. |  Use this mode only for temporary runtime rollback in the rare event of a runtime update compatibility issue. Switch functions to **Auto** or **Function update** mode and the latest runtime version as soon as possible.  | 
| Container image | Publish new container images containing the latest patches. | Redeploy functions regularly using the latest container base image to pick up the latest patches. | 

For more information about shared responsibility with AWS, see [Shared Responsibility Model](https://aws.amazon.com/compliance/shared-responsibility-model/).

# Controlling Lambda runtime update permissions for high-compliance applications
<a name="runtime-management-hc-applications"></a>

To meet patching requirements, Lambda customers typically rely on automatic runtime updates. If your application is subject to strict patching freshness requirements, you may want to limit use of earlier runtime versions. You can restrict Lambda's runtime management controls by using AWS Identity and Access Management (IAM) to deny users in your AWS account access to the [PutRuntimeManagementConfig](https://docs.aws.amazon.com/lambda/latest/api/API_PutRuntimeManagementConfig.html) API operation. This operation is used to choose the runtime update mode for a function. Denying access to this operation causes all functions to default to the **Auto** mode. You can apply this restriction across your organization by using a [service control policies (SCP)](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_policies_scps.html). If you must roll back a function to an earlier runtime version, you can grant a policy exception on a case-by-case basis.