How to target Azure Functions runtime versions
A function app runs on a specific version of the Azure Functions runtime. By default, function apps are created in latest 4.x version of the Functions runtime. Your function apps are only supported when running on a supported major version. This article explains how to configure a function app in Azure to target, or pin to, a specific version when required.
The way that you target a specific version depends on whether you're running Windows or Linux. This version of the article supports Windows. Choose your operating system at the top of the article.
The way that you target a specific version depends on whether you're running Windows or Linux. This version of the article supports Linux. Choose your operating system at the top of the article.
Important
When possible, you should always run your functions on the latest supported version of the Azure Functions runtime. You should only pin your app to a specific version when instructed to do so because of an issue in the latest version. You should always move up to the latest runtime version as soon as your functions can run correctly.
During local development, your installed version of Azure Functions Core Tools must match major runtime version used by the function app in Azure. For more information, see Core Tools versions.
Update your runtime version
When possible, you should always run your function apps on the latest supported version of the Azure Functions runtime. If your function app is currently running on an older version of the runtime, you should migrate your app to version 4.x
When your app has existing functions, you must take precautions before moving to a later major runtime version. The following articles detail breaking changes between major versions, including language-specific breaking changes. They also provide you with step-by-step instructions for a successful migration of your existing function app.
To determine your current runtime version, see View the current runtime version.
View the current runtime version
You can view the current runtime version of your function app in one of these ways:
Use the following procedure to view and update the runtime version currently used by a function app.
In the Azure portal, browse to your function app.
Under Settings, choose Configuration. In the Function runtime settings tab, locate the Runtime version. Note the specific runtime version. In the example below, the version is set to
~4
.
Pinning to a specific version
Azure Functions lets you use the FUNCTIONS_EXTENSION_VERSION
application setting to target the runtime version used by a given function app. When you specify only the major version (~4
), the function app is automatically updated to new minor versions of the runtime when they become available. Minor version updates are done automatically because new minor versions shouldn't introduce breaking changes.
Linux apps use the linuxFxVersion
site setting along with FUNCTIONS_EXTENSION_VERSION
to determine the correct Linux base image in which to run your functions. When you create a new funtion app on Linux, the runtime automatically chooses the correct base image for you based on the runtime version of your language stack.
Pinning to a specific runtime version causes your function app to restart.
When you specify a specific minor version (such as 4.0.12345
) in FUNCTIONS_EXTENSION_VERSION
, the function app is pinned to that specific version of the runtime until you explicitly choose to move back to automatic updates. You should only pin to a specific minor version long enough to resolve any issues with your function app that prevent you from targeting the major version. Older minor versions are regularly removed from the production environment. When you're pinned to a minor version that gets removed, your function app is instead run on the closest existing version instead of the version set in FUNCTIONS_EXTENSION_VERSION
. Minor version removals are announced in App Service announcements.
Note
When you try to publish from Visual Studio to an app that is pinned to a specific minor version of the runtime, a dialog prompts you to update to the latest version or cancel the publish. To avoid this check when you must use a specific minor version, add the <DisableFunctionExtensionVersionUpdate>true</DisableFunctionExtensionVersionUpdate>
property in your .csproj
file.
Use one of these methods to temporarily pin your app to a specific version of the runtime:
Use the following procedure to view and update the runtime version currently used by a function app.
In the Azure portal, browse to your function app.
Under Settings, choose Configuration. In the Function runtime settings tab, locate the Runtime version. Note the specific runtime version. In the example below, the version is set to
~4
.
To pin your app to a specific minor version, select Application settings > FUNCTIONS_EXTENSION_VERSION, change Value to your required minor version, and select OK.
Select Save > Continue to apply changes and restart the app.
The function app restarts after the change is made to the application setting.
To pin your function app to a specific runtime version on Linux, you set a version-specific base image URL in the linuxFxVersion
site setting in the format DOCKER|<PINNED_VERSION_IMAGE_URI>
.
Important
Pinned function apps on Linux don't receive regular security and host functionality updates. Unless recommended by a support professional, use the FUNCTIONS_EXTENSION_VERSION
setting and a standard linuxFxVersion
value for your language and version, such as Python|3.9
. For valid values, see the linuxFxVersion
reference article.
Pinning to a specific runtime isn't currently supported for Linux function apps running in a Consumption plan.
The following is an example of the linuxFxVersion
value required to pin a Node.js 16 function app to a specific runtime version of 4.14.0.3:
DOCKER|mcr.microsoft.com/azure-functions/node:4.14.0.3-node16
When needed, a support professional can provide you with a valid base image URI for your application.
Use the following Azure CLI commands to view and set the linuxFxVersion
. You can't currently set linuxFxVersion
in the portal or by using Azure PowerShell.
To view the current runtime version, use with the az functionapp config show command.
az functionapp config show --name <function_app> \ --resource-group <my_resource_group> --query 'linuxFxVersion' -o tsv
In this code, replace
<function_app>
with the name of your function app. Also replace<my_resource_group>
with the name of the resource group for your function app. The current value oflinuxFxVersion
is returned.To update the
linuxFxVersion
setting in the function app, use the az functionapp config set command.az functionapp config set --name <FUNCTION_APP> \ --resource-group <RESOURCE_GROUP> \ --linux-fx-version <LINUX_FX_VERSION>
Replace
<FUNCTION_APP>
with the name of your function app. Also replace<RESOURCE_GROUP>
with the name of the resource group for your function app. Finally, replace<LINUX_FX_VERSION>
with the value of a specific image provided to you by a support professional.
You can run these commands from the Azure Cloud Shell by choosing Open Cloud Shell in the preceding code examples. You can also use the Azure CLI locally to execute this command after executing az login
to sign in.
The function app restarts after the change is made to the site config.
Next steps
Feedback
https://aka.ms/ContentUserFeedback.
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see:Submit and view feedback for