Virtual Machines - Install Patches

Service:: Compute

API Version:: 2025-04-01

Installs patches on the VM.

POST https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Compute/virtualMachines/{vmName}/installPatches?api-version=2025-04-01

URI Parameters

Name	In	Required	Type	Description
resourceGroupName	path	True	string minLength: 1 maxLength: 90	The name of the resource group. The name is case insensitive.
subscriptionId	path	True	string minLength: 1	The ID of the target subscription.
vmName	path	True	string	The name of the virtual machine.
api-version	query	True	string minLength: 1	The API version to use for this operation.

Request Body

Name	Required	Type	Description
rebootSetting	True	VMGuestPatchRebootSetting	Defines when it is acceptable to reboot a VM during a software update operation.
linuxParameters		LinuxParameters	Input for InstallPatches on a Linux VM, as directly received by the API
maximumDuration		string (duration)	Specifies the maximum amount of time that the operation will run. It must be an ISO 8601-compliant duration string such as PT4H (4 hours)
windowsParameters		WindowsParameters	Input for InstallPatches on a Windows VM, as directly received by the API

Responses

Name

Type

Description

200 OK

VirtualMachineInstallPatchesResult

Azure operation completed successfully.

202 Accepted

Resource operation accepted.

Headers

Location: string
Retry-After: integer

Other Status Codes

An unexpected error response.

Security

azure_auth

Azure Active Directory OAuth2 Flow.

Type: oauth2
Flow: implicit
Authorization URL: https://login.microsoftonline.com/common/oauth2/authorize

Scopes

Name	Description
user_impersonation	impersonate your user account

Examples

Install patch state of a virtual machine.

Sample request

POST https://management.azure.com/subscriptions/{subscription-id}/resourceGroups/myResourceGroupName/providers/Microsoft.Compute/virtualMachines/myVMName/installPatches?api-version=2025-04-01

{
  "maximumDuration": "PT4H",
  "rebootSetting": "IfRequired",
  "windowsParameters": {
    "classificationsToInclude": [
      "Critical",
      "Security"
    ],
    "maxPatchPublishDate": "2020-11-19T02:36:43.0539904+00:00",
    "patchNameMasksToInclude": [
      "*SQL*"
    ],
    "patchNameMasksToExclude": [
      "*Windows*"
    ]
  }
}


import com.azure.resourcemanager.compute.models.VMGuestPatchClassificationWindows;
import com.azure.resourcemanager.compute.models.VMGuestPatchRebootSetting;
import com.azure.resourcemanager.compute.models.VirtualMachineInstallPatchesParameters;
import com.azure.resourcemanager.compute.models.WindowsParameters;
import java.time.OffsetDateTime;
import java.util.Arrays;

/**
 * Samples for VirtualMachines InstallPatches.
 */
public final class Main {
    /*
     * x-ms-original-file:
     * specification/compute/resource-manager/Microsoft.Compute/ComputeRP/stable/2025-04-01/examples/
     * virtualMachineExamples/VirtualMachine_InstallPatches.json
     */
    /**
     * Sample code: Install patch state of a virtual machine.
     * 
     * @param azure The entry point for accessing resource management APIs in Azure.
     */
    public static void installPatchStateOfAVirtualMachine(com.azure.resourcemanager.AzureResourceManager azure) {
        azure.virtualMachines().manager().serviceClient().getVirtualMachines().installPatches("myResourceGroupName",
            "myVMName",
            new VirtualMachineInstallPatchesParameters().withMaximumDuration("PT4H")
                .withRebootSetting(VMGuestPatchRebootSetting.IF_REQUIRED)
                .withWindowsParameters(new WindowsParameters()
                    .withClassificationsToInclude(Arrays.asList(VMGuestPatchClassificationWindows.CRITICAL,
                        VMGuestPatchClassificationWindows.SECURITY))
                    .withMaxPatchPublishDate(OffsetDateTime.parse("2020-11-19T02:36:43.0539904+00:00"))
                    .withPatchNameMasksToInclude(Arrays.asList("*SQL*"))
                    .withPatchNameMasksToExclude(Arrays.asList("*Windows*"))),
            com.azure.core.util.Context.NONE);
    }
}

To use the Azure SDK library in your project, see this documentation. To provide feedback on this code sample, open a GitHub issue

from azure.identity import DefaultAzureCredential

from azure.mgmt.compute import ComputeManagementClient

"""
# PREREQUISITES
    pip install azure-identity
    pip install azure-mgmt-compute
# USAGE
    python virtual_machine_install_patches.py

    Before run the sample, please set the values of the client ID, tenant ID and client secret
    of the AAD application as environment variables: AZURE_CLIENT_ID, AZURE_TENANT_ID,
    AZURE_CLIENT_SECRET. For more info about how to get the value, please see:
    https://docs.microsoft.com/azure/active-directory/develop/howto-create-service-principal-portal
"""


def main():
    client = ComputeManagementClient(
        credential=DefaultAzureCredential(),
        subscription_id="{subscription-id}",
    )

    response = client.virtual_machines.begin_install_patches(
        resource_group_name="myResourceGroupName",
        vm_name="myVMName",
        install_patches_input={
            "maximumDuration": "PT4H",
            "rebootSetting": "IfRequired",
            "windowsParameters": {
                "classificationsToInclude": ["Critical", "Security"],
                "maxPatchPublishDate": "2020-11-19T02:36:43.0539904+00:00",
                "patchNameMasksToExclude": ["*Windows*"],
                "patchNameMasksToInclude": ["*SQL*"],
            },
        },
    ).result()
    print(response)


# x-ms-original-file: specification/compute/resource-manager/Microsoft.Compute/ComputeRP/stable/2025-04-01/examples/virtualMachineExamples/VirtualMachine_InstallPatches.json
if __name__ == "__main__":
    main()

To use the Azure SDK library in your project, see this documentation. To provide feedback on this code sample, open a GitHub issue

package armcompute_test

import (
	"context"
	"log"

	"time"

	"github.com/Azure/azure-sdk-for-go/sdk/azcore/to"
	"github.com/Azure/azure-sdk-for-go/sdk/azidentity"
	"github.com/Azure/azure-sdk-for-go/sdk/resourcemanager/compute/armcompute/v7"
)

// Generated from example definition: https://github.com/Azure/azure-rest-api-specs/blob/fb90eb1bec64c6e8ad3e288a64c84cc18742a394/specification/compute/resource-manager/Microsoft.Compute/ComputeRP/stable/2025-04-01/examples/virtualMachineExamples/VirtualMachine_InstallPatches.json
func ExampleVirtualMachinesClient_BeginInstallPatches() {
	cred, err := azidentity.NewDefaultAzureCredential(nil)
	if err != nil {
		log.Fatalf("failed to obtain a credential: %v", err)
	}
	ctx := context.Background()
	clientFactory, err := armcompute.NewClientFactory("<subscription-id>", cred, nil)
	if err != nil {
		log.Fatalf("failed to create client: %v", err)
	}
	poller, err := clientFactory.NewVirtualMachinesClient().BeginInstallPatches(ctx, "myResourceGroupName", "myVMName", armcompute.VirtualMachineInstallPatchesParameters{
		MaximumDuration: to.Ptr("PT4H"),
		RebootSetting:   to.Ptr(armcompute.VMGuestPatchRebootSettingIfRequired),
		WindowsParameters: &armcompute.WindowsParameters{
			ClassificationsToInclude: []*armcompute.VMGuestPatchClassificationWindows{
				to.Ptr(armcompute.VMGuestPatchClassificationWindowsCritical),
				to.Ptr(armcompute.VMGuestPatchClassificationWindowsSecurity)},
			MaxPatchPublishDate: to.Ptr(func() time.Time { t, _ := time.Parse(time.RFC3339Nano, "2020-11-19T02:36:43.053Z"); return t }()),
			PatchNameMasksToExclude: []*string{
				to.Ptr("*Windows*")},
			PatchNameMasksToInclude: []*string{
				to.Ptr("*SQL*")},
		},
	}, nil)
	if err != nil {
		log.Fatalf("failed to finish the request: %v", err)
	}
	res, err := poller.PollUntilDone(ctx, nil)
	if err != nil {
		log.Fatalf("failed to pull the result: %v", err)
	}
	// You could use response here. We use blank identifier for just demo purposes.
	_ = res
	// If the HTTP response code is 200 as defined in example definition, your response structure would look as follows. Please pay attention that all the values in the output are fake values for just demo purposes.
	// res.VirtualMachineInstallPatchesResult = armcompute.VirtualMachineInstallPatchesResult{
	// 	ExcludedPatchCount: to.Ptr[int32](0),
	// 	FailedPatchCount: to.Ptr[int32](0),
	// 	InstallationActivityID: to.Ptr("68f8b292-dfc2-4646-9781-33cc88631968"),
	// 	InstalledPatchCount: to.Ptr[int32](3),
	// 	MaintenanceWindowExceeded: to.Ptr(false),
	// 	NotSelectedPatchCount: to.Ptr[int32](0),
	// 	Patches: []*armcompute.PatchInstallationDetail{
	// 		{
	// 			Name: to.Ptr("Definition Update for Windows Defender Antivirus - KB2267602 (Definition 1.279.1373.0)"),
	// 			Classifications: []*string{
	// 				to.Ptr("Definition Updates")},
	// 				InstallationState: to.Ptr(armcompute.PatchInstallationStateInstalled),
	// 				KbID: to.Ptr("2267602"),
	// 				PatchID: to.Ptr("35428702-5784-4ba4-a6e0-5222258b5411"),
	// 				Version: to.Ptr(""),
	// 			},
	// 			{
	// 				Name: to.Ptr("Windows Malicious Software Removal Tool x64 - October 2018 (KB890830)"),
	// 				Classifications: []*string{
	// 					to.Ptr("Update Rollups")},
	// 					InstallationState: to.Ptr(armcompute.PatchInstallationStatePending),
	// 					KbID: to.Ptr("890830"),
	// 					PatchID: to.Ptr("39f9cdd1-795c-4d0e-8c0a-73ab3f31746d"),
	// 					Version: to.Ptr(""),
	// 			}},
	// 			PendingPatchCount: to.Ptr[int32](2),
	// 			RebootStatus: to.Ptr(armcompute.VMGuestPatchRebootStatusCompleted),
	// 			StartDateTime: to.Ptr(func() time.Time { t, _ := time.Parse(time.RFC3339Nano, "2020-04-24T21:02:04.255Z"); return t}()),
	// 			Status: to.Ptr(armcompute.PatchOperationStatusSucceeded),
	// 		}
}

To use the Azure SDK library in your project, see this documentation. To provide feedback on this code sample, open a GitHub issue

const { ComputeManagementClient } = require("@azure/arm-compute");
const { DefaultAzureCredential } = require("@azure/identity");
require("dotenv/config");

/**
 * This sample demonstrates how to Installs patches on the VM.
 *
 * @summary Installs patches on the VM.
 * x-ms-original-file: specification/compute/resource-manager/Microsoft.Compute/ComputeRP/stable/2025-04-01/examples/virtualMachineExamples/VirtualMachine_InstallPatches.json
 */
async function installPatchStateOfAVirtualMachine() {
  const subscriptionId = process.env["COMPUTE_SUBSCRIPTION_ID"] || "{subscription-id}";
  const resourceGroupName = process.env["COMPUTE_RESOURCE_GROUP"] || "myResourceGroupName";
  const vmName = "myVMName";
  const installPatchesInput = {
    maximumDuration: "PT4H",
    rebootSetting: "IfRequired",
    windowsParameters: {
      classificationsToInclude: ["Critical", "Security"],
      maxPatchPublishDate: new Date("2020-11-19T02:36:43.0539904+00:00"),
      patchNameMasksToExclude: ["*Windows*"],
      patchNameMasksToInclude: ["*SQL*"],
    },
  };
  const credential = new DefaultAzureCredential();
  const client = new ComputeManagementClient(credential, subscriptionId);
  const result = await client.virtualMachines.beginInstallPatchesAndWait(
    resourceGroupName,
    vmName,
    installPatchesInput,
  );
  console.log(result);
}

To use the Azure SDK library in your project, see this documentation. To provide feedback on this code sample, open a GitHub issue

using Azure;
using Azure.ResourceManager;
using System;
using System.Threading.Tasks;
using System.Xml;
using Azure.Core;
using Azure.Identity;
using Azure.ResourceManager.Compute.Models;
using Azure.ResourceManager.Compute;

// Generated from example definition: specification/compute/resource-manager/Microsoft.Compute/ComputeRP/stable/2025-04-01/examples/virtualMachineExamples/VirtualMachine_InstallPatches.json
// this example is just showing the usage of "VirtualMachines_InstallPatches" operation, for the dependent resources, they will have to be created separately.

// get your azure access token, for more details of how Azure SDK get your access token, please refer to https://free.blessedness.top/en-us/dotnet/azure/sdk/authentication?tabs=command-line
TokenCredential cred = new DefaultAzureCredential();
// authenticate your client
ArmClient client = new ArmClient(cred);

// this example assumes you already have this VirtualMachineResource created on azure
// for more information of creating VirtualMachineResource, please refer to the document of VirtualMachineResource
string subscriptionId = "{subscription-id}";
string resourceGroupName = "myResourceGroupName";
string vmName = "myVMName";
ResourceIdentifier virtualMachineResourceId = VirtualMachineResource.CreateResourceIdentifier(subscriptionId, resourceGroupName, vmName);
VirtualMachineResource virtualMachine = client.GetVirtualMachineResource(virtualMachineResourceId);

// invoke the operation
VirtualMachineInstallPatchesContent content = new VirtualMachineInstallPatchesContent(VmGuestPatchRebootSetting.IfRequired)
{
    MaximumDuration = XmlConvert.ToTimeSpan("PT4H"),
    WindowsParameters = new WindowsParameters
    {
        ClassificationsToInclude = { VmGuestPatchClassificationForWindows.Critical, VmGuestPatchClassificationForWindows.Security },
        MaxPatchPublishOn = DateTimeOffset.Parse("2020-11-19T02:36:43.0539904+00:00"),
        PatchNameMasksToInclude = { "*SQL*" },
        PatchNameMasksToExclude = { "*Windows*" },
    },
};
ArmOperation<VirtualMachineInstallPatchesResult> lro = await virtualMachine.InstallPatchesAsync(WaitUntil.Completed, content);
VirtualMachineInstallPatchesResult result = lro.Value;

Console.WriteLine($"Succeeded: {result}");

To use the Azure SDK library in your project, see this documentation. To provide feedback on this code sample, open a GitHub issue

Sample response

Status code:: 200

{
  "status": "Succeeded",
  "installationActivityId": "68f8b292-dfc2-4646-9781-33cc88631968",
  "rebootStatus": "Completed",
  "maintenanceWindowExceeded": false,
  "excludedPatchCount": 0,
  "notSelectedPatchCount": 0,
  "pendingPatchCount": 2,
  "installedPatchCount": 3,
  "failedPatchCount": 0,
  "startDateTime": "2020-04-24T21:02:04.2556154Z",
  "patches": [
    {
      "patchId": "35428702-5784-4ba4-a6e0-5222258b5411",
      "name": "Definition Update for Windows Defender Antivirus - KB2267602 (Definition 1.279.1373.0)",
      "version": "",
      "kbId": "2267602",
      "classifications": [
        "Definition Updates"
      ],
      "installationState": "Installed"
    },
    {
      "patchId": "39f9cdd1-795c-4d0e-8c0a-73ab3f31746d",
      "name": "Windows Malicious Software Removal Tool x64 - October 2018 (KB890830)",
      "version": "",
      "kbId": "890830",
      "classifications": [
        "Update Rollups"
      ],
      "installationState": "Pending"
    }
  ],
  "error": null
}

Status code:: 202

Location: https://management.azure.com/subscriptions/{subscriptionId}/providers/Microsoft.Compute/locations/westus/operations/{operationId}&monitor=true&api-version=2025-04-01

Definitions

Name	Description
ApiError	Api error.
ApiErrorBase	Api error base.
CloudError	An error response from the Compute service.
InnerError	Inner error details.
LinuxParameters	Input for InstallPatches on a Linux VM, as directly received by the API
PatchInstallationDetail	Information about a specific patch that was encountered during an installation action.
PatchInstallationState	The state of the patch after the installation operation completed.
PatchOperationStatus	The overall success or failure status of the operation. It remains "InProgress" until the operation completes. At that point it will become "Unknown", "Failed", "Succeeded", or "CompletedWithWarnings."
VirtualMachineInstallPatchesParameters	Input for InstallPatches as directly received by the API
VirtualMachineInstallPatchesResult	The result summary of an installation operation.
VMGuestPatchClassificationLinux
VMGuestPatchClassificationWindows
VMGuestPatchRebootSetting	Defines when it is acceptable to reboot a VM during a software update operation.
VMGuestPatchRebootStatus	The reboot state of the VM following completion of the operation.
WindowsParameters	Input for InstallPatches on a Windows VM, as directly received by the API

ApiError

Object

Api error.

Name	Type	Description
code	string	The error code.
details	ApiErrorBase[]	The Api error details
innererror	InnerError	The Api inner error
message	string	The error message.
target	string	The target of the particular error.

ApiErrorBase

Object

Api error base.

Name	Type	Description
code	string	The error code.
message	string	The error message.
target	string	The target of the particular error.

CloudError

Object

An error response from the Compute service.

Name	Type	Description
error	ApiError	Api error.

InnerError

Object

Inner error details.

Name	Type	Description
errordetail	string	The internal error message or exception dump.
exceptiontype	string	The exception type.

LinuxParameters

Object

Input for InstallPatches on a Linux VM, as directly received by the API

Name	Type	Description
classificationsToInclude	VMGuestPatchClassificationLinux[]	The update classifications to select when installing patches for Linux.
maintenanceRunId	string	This is used as a maintenance run identifier for Auto VM Guest Patching in Linux.
packageNameMasksToExclude	string[]	packages to exclude in the patch operation. Format: packageName_packageVersion
packageNameMasksToInclude	string[]	packages to include in the patch operation. Format: packageName_packageVersion

PatchInstallationDetail

Object

Information about a specific patch that was encountered during an installation action.

Name	Type	Description
classifications	string[]	The classification(s) of the patch as provided by the patch publisher.
installationState	PatchInstallationState	The state of the patch after the installation operation completed.
kbId	string	The KBID of the patch. Only applies to Windows patches.
name	string	The friendly name of the patch.
patchId	string	A unique identifier for the patch.
version	string	The version string of the package. It may conform to Semantic Versioning. Only applies to Linux.

PatchInstallationState

Enumeration

The state of the patch after the installation operation completed.

Value	Description
Unknown
Installed
Failed
Excluded
NotSelected
Pending

PatchOperationStatus

Enumeration

The overall success or failure status of the operation. It remains "InProgress" until the operation completes. At that point it will become "Unknown", "Failed", "Succeeded", or "CompletedWithWarnings."

Value	Description
Unknown
InProgress
Failed
Succeeded
CompletedWithWarnings

VirtualMachineInstallPatchesParameters

Object

Input for InstallPatches as directly received by the API

Name	Type	Description
linuxParameters	LinuxParameters	Input for InstallPatches on a Linux VM, as directly received by the API
maximumDuration	string (duration)	Specifies the maximum amount of time that the operation will run. It must be an ISO 8601-compliant duration string such as PT4H (4 hours)
rebootSetting	VMGuestPatchRebootSetting	Defines when it is acceptable to reboot a VM during a software update operation.
windowsParameters	WindowsParameters	Input for InstallPatches on a Windows VM, as directly received by the API

VirtualMachineInstallPatchesResult

Object

The result summary of an installation operation.

Name	Type	Description
error	ApiError	The errors that were encountered during execution of the operation. The details array contains the list of them.
excludedPatchCount	integer (int32)	The number of patches that were not installed due to the user blocking their installation.
failedPatchCount	integer (int32)	The number of patches that could not be installed due to some issue. See errors for details.
installationActivityId	string	The activity ID of the operation that produced this result. It is used to correlate across CRP and extension logs.
installedPatchCount	integer (int32)	The number of patches successfully installed.
maintenanceWindowExceeded	boolean	Whether the operation ran out of time before it completed all its intended actions.
notSelectedPatchCount	integer (int32)	The number of patches that were detected as available for install, but did not meet the operation's criteria.
patches	PatchInstallationDetail[]	The patches that were installed during the operation.
pendingPatchCount	integer (int32)	The number of patches that were identified as meeting the installation criteria, but were not able to be installed. Typically this happens when maintenanceWindowExceeded == true.
rebootStatus	VMGuestPatchRebootStatus	The reboot state of the VM following completion of the operation.
startDateTime	string (date-time)	The UTC timestamp when the operation began.
status	PatchOperationStatus	The overall success or failure status of the operation. It remains "InProgress" until the operation completes. At that point it will become "Failed", "Succeeded", "Unknown" or "CompletedWithWarnings."

VMGuestPatchClassificationLinux

Enumeration

Value	Description
Critical
Security
Other

VMGuestPatchClassificationWindows

Enumeration

Value	Description
Critical
Security
UpdateRollUp
FeaturePack
ServicePack
Definition
Tools
Updates

VMGuestPatchRebootSetting

Enumeration

Defines when it is acceptable to reboot a VM during a software update operation.

Value	Description
IfRequired
Never
Always

VMGuestPatchRebootStatus

Enumeration

The reboot state of the VM following completion of the operation.

Value	Description
Unknown
NotNeeded
Required
Started
Failed
Completed

WindowsParameters

Object

Input for InstallPatches on a Windows VM, as directly received by the API

Name	Type	Description
classificationsToInclude	VMGuestPatchClassificationWindows[]	The update classifications to select when installing patches for Windows.
excludeKbsRequiringReboot	boolean	Filters out Kbs that don't have an InstallationRebootBehavior of 'NeverReboots' when this is set to true.
kbNumbersToExclude	string[]	Kbs to exclude in the patch operation
kbNumbersToInclude	string[]	Kbs to include in the patch operation
maxPatchPublishDate	string (date-time)	This is used to install patches that were published on or before this given max published date.
patchNameMasksToExclude	string[]	This is used to exclude patches that match the given patch name masks. Alphanumeric strings and wildcard expressions consisting of * and ? are only supported as input values in the list. Null, empty and only whitespaces strings as inputs values are not supported.
patchNameMasksToInclude	string[]	This is used to include patches that match the given patch name masks. Alphanumeric strings and wildcard expressions consisting of * and ? are only supported as input values in the list. Null, empty and only whitespaces strings as inputs values are not supported.