Edit

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.