Remove-AzResourceGroupDeployment
Delete a resource group deployment from the deployment history.
Syntax
RemoveByResourceGroupName (Default)
Remove-AzResourceGroupDeployment
[-ResourceGroupName] <string>
[-Name] <string>
[-SubscriptionId <string>]
[-Profile <string>]
[-WhatIf]
[-Confirm]
[<CommonParameters>]
RemoveByResourceGroupDeploymentId
Remove-AzResourceGroupDeployment
-Id <string>
[-SubscriptionId <string>]
[-Profile <string>]
[-WhatIf]
[-Confirm]
[<CommonParameters>]
Description
Deletes an Azure Resource Manager deployment scoped to a resource group. This removes the deployment record and its associated deployment operations from the deployment history; it does not delete the resources the deployment created, and it leaves the resource group itself untouched.
A deployment that is currently running cannot be deleted -- cancel it with Stop-AzResourceGroupDeployment first, or wait for it to reach a terminal state. The delete is a long-running operation and the cmdlet waits for it to finish.
Deleting a deployment name that does not exist succeeds silently, because ARM answers the same 204 No Content whether or not the deployment was there. The cmdlet emits nothing on success.
The deployment can be identified either by -ResourceGroupName and -Name or by its fully qualified -Id. When -Id is used, the subscription is always taken from the id and -SubscriptionId is ignored; otherwise the subscription defaults to the active profile's.
Examples
Delete a deployment from the history
Remove the record of the deployment named infra-prod-2026-06-18 in resource group myrg.
Remove-AzResourceGroupDeployment -ResourceGroupName myrg -Name infra-prod-2026-06-18
Delete a deployment using positional arguments
-ResourceGroupName and -Name are positional, so the parameter names can be omitted.
Remove-AzResourceGroupDeployment myrg infra-prod-2026-06-18
Delete a deployment by resource id
Target the deployment by its fully qualified resource id. The subscription is read from the id.
Remove-AzResourceGroupDeployment -Id /subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/myrg/providers/Microsoft.Resources/deployments/infra-prod-2026-06-18
Delete a deployment in a specific subscription without being prompted
Remove-AzResourceGroupDeployment supports ShouldProcess with a Medium confirm impact, so it does not prompt under the default $ConfirmPreference of High. Pass -Confirm to request a prompt, or -Confirm:$false to stay unattended even where $ConfirmPreference has been lowered.
Remove-AzResourceGroupDeployment -ResourceGroupName myrg -Name infra-prod-2026-06-18 -SubscriptionId 00000000-0000-0000-0000-000000000000 -Confirm:$false
Parameters
-Confirm
Prompts you for confirmation before running the cmdlet.
Parameter properties
| Type: | SwitchParameter |
| Supports wildcards: | False |
| DontShow: | False |
| Aliases: | cf |
Parameter sets
(All)
| Position: | Named |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
-Id
The fully qualified resource id of the deployment, in the form /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Resources/deployments/{deploymentName}. The subscription, resource group and deployment name are all read from the id; -SubscriptionId is ignored when -Id is used. A malformed id fails before any request is sent.
Parameter properties
| Type: | String |
| Supports wildcards: | False |
| DontShow: | False |
| Aliases: | DeploymentId, ResourceId |
Parameter sets
RemoveByResourceGroupDeploymentId
| Position: | Named |
| Mandatory: | True |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
-Name
The name of the deployment to delete. Accepts the legacy alias -DeploymentName, and can be supplied positionally as the second argument.
Parameter properties
| Type: | String |
| Supports wildcards: | False |
| DontShow: | False |
| Aliases: | DeploymentName |
Parameter sets
RemoveByResourceGroupName
| Position: | 1 |
| Mandatory: | True |
| Value from pipeline: | False |
| Value from pipeline by property name: | True |
| Value from remaining arguments: | False |
-Profile
Use the named profile for this command, overriding the active profile.
Parameter properties
| Type: | String |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
(All)
| Position: | Named |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
-ResourceGroupName
The name of the resource group that contains the deployment. Can be supplied positionally as the first argument.
Parameter properties
| Type: | String |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
RemoveByResourceGroupName
| Position: | 0 |
| Mandatory: | True |
| Value from pipeline: | False |
| Value from pipeline by property name: | True |
| Value from remaining arguments: | False |
-SubscriptionId
Azure subscription id. Defaults to the active profile's subscription. Ignored when -Id is used; the subscription embedded in the id always wins.
Parameter properties
| Type: | String |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
RemoveByResourceGroupName
| Position: | Named |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
RemoveByResourceGroupDeploymentId
| Position: | Named |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
-WhatIf
Runs the command in a mode that only reports what would happen without performing the actions.
Parameter properties
| Type: | SwitchParameter |
| Supports wildcards: | False |
| DontShow: | False |
| Aliases: | wi |
Parameter sets
(All)
| Position: | Named |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
CommonParameters
This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, -ProgressAction, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters.
Inputs
String
You can pipe the ResourceGroupName and Name values to this cmdlet by property name, for example the output of Get-AzResourceGroupDeployment.
Outputs
Void
Nothing is emitted on success. Azure Resource Manager answers the delete request with HTTP 204 No Content, so a silent return and a zero exit status mean the deployment record was deleted. Failures surface as terminating errors.
Notes
Deleting a deployment removes only the deployment record from the history of the resource group. Resources created by that deployment are left untouched.
A deployment that is still running cannot be deleted; Azure Resource Manager rejects the request. Cancel it first with Stop-AzResourceGroupDeployment, then delete it.
Deleting a name that does not exist is not an error. Azure Resource Manager answers 204 No Content for an absent deployment, so the cmdlet returns silently. This differs from Remove-AzResourceGroupDeployment in Az.Resources, which performs an existence check first and throws.
The delete is a long-running operation. The cmdlet polls until Azure Resource Manager reports the operation complete before returning.