How to target Azure Functions runtime versions

A function app runs on a specific version of the Azure Functions runtime. There are two major versions: 1.x and 2.x. By default, function apps that are created version 2.x of the runtime. This article explains how to configure a function app in Azure to run on the version you choose. For information about how to configure a local development environment for a specific version, see Code and test Azure Functions locally.

Automatic and manual version updates

Azure Functions lets you target a specific version of the runtime by using the FUNCTIONS_EXTENSION_VERSION application setting in a function app. The function app is kept on the specified major version until you explicitly choose to move to a new version.

If you specify only the major version ("~2" for 2.x or "~1" for 1.x), the function app is automatically updated to new minor versions of the runtime when they become available. New minor versions do not introduce breaking changes. If you specify a minor version (for example, "2.0.12345"), the function app is pinned to that specific version until you explicitly change it.

Note

If you pin to a specific version of Azure Functions, and then try to publish to Azure using Visual Studio, a dialog window will pop up prompting you to update to the latest version or cancel the publish. To avoid this, add the <DisableFunctionExtensionVersionUpdate>true</DisableFunctionExtensionVersionUpdate> property in your .csproj file.

When a new version is publicly available, a prompt in the portal gives you the chance to move up to that version. After moving to a new version, you can always use the FUNCTIONS_EXTENSION_VERSION application setting to move back to a previous version.

A change to the runtime version causes a function app to restart.

The values you can set in the FUNCTIONS_EXTENSION_VERSION app setting to enable automatic updates are currently "~1" for the 1.x runtime and "~2" for 2.x.

View and update the current runtime version

You can change the runtime version used by your function app. Because of the potential of breaking changes, you should only change the runtime version before you have created any functions in your function app. Although the runtime version is determined by the FUNCTIONS_EXTENSION_VERSION setting, you should make this change in the Azure portal and not by changing the setting directly. This is because the portal validates your changes and makes other related changes as needed.

From the Azure portal

Use the following procedure to view and update the runtime version currently used by a function app.

  1. In the Azure portal, browse to your function app.

  2. Under Configured Features, choose Function app settings.

    Select function app settings

  3. In the Function app settings tab, locate the Runtime version. Note the specific runtime version and the requested major version. In the example below, the version is set to ~2.

    Select function app settings

  4. To pin your function app to the version 1.x runtime, choose ~1 under Runtime version. This switch is disabled when you have functions in your app.

  5. When you change the runtime version, go back to the Overview tab and choose Restart to restart the app. The function app restarts running on the version 1.x runtime, and the version 1.x templates are used when you create functions.

Note

Using the Azure portal, you can't change the runtime version for a function app that already contains functions.

From the Azure CLI

You can also view and set the FUNCTIONS_EXTENSION_VERSION from the Azure CLI.

Note

Because other settings may be impacted by the runtime version, you should change the version in the portal. The portal automatically makes the other needed updates, such as Node.js version and runtime stack, when you change runtime versions.

Using the Azure CLI, view the current runtime version with the az functionapp config appsettings set command.

az functionapp config appsettings list --name <function_app> \
--resource-group <my_resource_group>

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.

You see the FUNCTIONS_EXTENSION_VERSION in the following output, which has been truncated for clarity:

[
  {
    "name": "FUNCTIONS_EXTENSION_VERSION",
    "slotSetting": false,
    "value": "~2"
  },
  {
    "name": "FUNCTIONS_WORKER_RUNTIME",
    "slotSetting": false,
    "value": "dotnet"
  },
  
  ...
  
  {
    "name": "WEBSITE_NODE_DEFAULT_VERSION",
    "slotSetting": false,
    "value": "8.11.1"
  }
]

You can update the FUNCTIONS_EXTENSION_VERSION setting in the function app with the az functionapp config appsettings set command.

az functionapp config appsettings set --name <function_app> \
--resource-group <my_resource_group> \
--settings FUNCTIONS_EXTENSION_VERSION=<version>

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. Also, replace <version> with a valid version of the 1.x runtime or ~2 for version 2.x.

You can run this command from the Azure Cloud Shell by choosing Try it in the preceding code sample. You can also use the Azure CLI locally to execute this command after executing az login to sign in.

Next steps