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.