Edit

Remove-AzSubDeployment

Delete a subscription-scope deployment from the deployment history.

Syntax

RemoveByDeploymentName (Default)

Remove-AzSubDeployment
    [-Name] <string>
    [-SubscriptionId <string>]
    [-PassThru]
    [-Profile <string>]
    [-WhatIf]
    [-Confirm]
    [<CommonParameters>]

RemoveByInputObject

Remove-AzSubDeployment
    -InputObject <DeploymentExtended>
    [-PassThru]
    [-Profile <string>]
    [-WhatIf]
    [-Confirm]
    [<CommonParameters>]

Aliases

This cmdlet has the following aliases, Remove-AzSubscriptionDeployment

Description

Deletes an Azure Resource Manager deployment scoped to a subscription. This removes the deployment record and its operations from the deployment history; it does not delete the resources the deployment created.

A deployment that is currently running cannot be deleted -- cancel it with Stop-AzSubDeployment first. The delete is a long-running operation and the cmdlet waits for it to finish. Identify the deployment by -Name, or by piping a deployment object from Get-AzSubDeployment. The cmdlet emits nothing on success unless -PassThru is specified.

Examples

Delete a deployment from the history

Remove the record of the deployment named sub-infra-2026-06-18.

Remove-AzSubDeployment -Name sub-infra-2026-06-18

Delete a deployment in a specific subscription without being prompted

Remove-AzSubDeployment -Name sub-infra-2026-06-18 -SubscriptionId 00000000-0000-0000-0000-000000000000 -Confirm:$false

Delete deployments from the pipeline

Get-AzSubDeployment -Name sub-infra-2026-06-18 | Remove-AzSubDeployment -PassThru

-PassThru writes True once the delete completes.

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

-InputObject

A deployment object returned by Get-AzSubDeployment. Its Id identifies the subscription and deployment to delete. Accepts pipeline input.

Parameter properties

Type:Microsoft.Azure.Azclips.Extensions.Resources.Models.DeploymentExtended
Supports wildcards:False
DontShow:False

Parameter sets

RemoveByInputObject
Position:Named
Mandatory:True
Value from pipeline:True
Value from pipeline by property name:False
Value from remaining arguments:False

-Name

The name of the deployment to delete from the subscription's deployment history.

Parameter properties

Type:String
Supports wildcards:False
DontShow:False
Aliases:DeploymentName

Parameter sets

RemoveByDeploymentName
Position:0
Mandatory:True
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False

-PassThru

Writes true after the delete completes without a terminating error. No value is written when -WhatIf or a declined confirmation skips the delete.

Parameter properties

Type:SwitchParameter
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

-Profile

Name of a saved profile to use for this call instead of the currently-active one. Manage profiles with Set-AzProfile / Get-AzProfile.

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

-SubscriptionId

The Azure subscription that owns the deployment. Defaults to the active profile's subscription when omitted.

Parameter properties

Type:String
Supports wildcards:False
DontShow:False

Parameter sets

RemoveByDeploymentName
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

Microsoft.Azure.Azclips.Extensions.Resources.Models.DeploymentExtended

Accepts a subscription deployment object from the pipeline, for example the output of Get-AzSubDeployment.

Outputs

Boolean

No output by default. With -PassThru, writes true after the delete completes. Failures surface as terminating errors.

Notes

Deleting a deployment removes only the deployment record. Resources created by that deployment are left untouched. The legacy Az.Resources name Remove-AzSubscriptionDeployment is accepted as an alias.