Live training: next batches coming soon. Join the waitlist:Waitlists open:Developer Training →Developer →Copilot Studio Training →Copilot Studio →

How to Delete a Microsoft Team with PowerShell (and Permanently Delete Channels)

A project wrapped up in September, and its owner wants the SPGDemo Retired Team gone: one stale channel first, then the whole team. Clicking Delete in Teams doesn’t scale, and it leaves the group in a 30-day soft-delete bin.

In this tutorial, we’ll build each delete team powershell step with PnP PowerShell on a real demo team: create it, add two channels, delete a channel, delete the team, restore it, and purge it so nothing is left behind.

Here’s what we’re building: one script that deletes a channel, deletes the team with its Microsoft 365 group, then purges the group. This is its real output from my tenant:

PowerShell script deleting a Teams channel, the team and purging its Microsoft 365 group with Left behind 0

Before You Start

You need PowerShell 7.4 or later, PnP.PowerShell 3.x, and your own Entra ID app registration with the Microsoft Graph Group.ReadWrite.All permission. New to the module? Install PnP PowerShell for SharePoint Online first, then connect:

Install-Module PnP.PowerShell -Scope CurrentUser

Connect-PnPOnline -Url "https://spguides.sharepoint.com/sites/SPGuides" -ClientId "<your-app-client-id>" -DeviceLogin -PersistLogin

Sign in as a team owner or a Teams administrator. For Microsoft’s own module, see connecting to Microsoft Teams with PowerShell. The demo objects (all mine):

ObjectNameNotes
Team + Microsoft 365 groupSPGDemo Retired TeammailNickname SPGDemoRetiredTeam, private
ChannelGeneralCreated automatically with every team
ChannelSPGDemo Old ChannelStandard; we delete it in Step 3
ChannelSPGDemo Q3 PlanningStandard; goes away with the team

Every team sits on a Microsoft 365 group, which is why the delete cmdlets talk about groups (Microsoft Teams vs Microsoft 365 groups explains the link).

Step 1: Create the Demo Team

New-PnPTeamsTeam creates the group and the team in one call, and the signed-in user becomes the owner:

$team = New-PnPTeamsTeam -DisplayName "SPGDemo Retired Team" -MailNickName "SPGDemoRetiredTeam" `
    -Description "Q3 2026 project team - retiring" -Visibility Private

$team | Select-Object DisplayName, GroupId, Visibility, MailNickName | Format-List
New-PnPTeamsTeam creating the private SPGDemo Retired Team and returning its GroupId

Checkpoint: You see the team’s GroupId and Visibility Private.

Target teams by that GroupId or the mailNickname. If two teams share a display name, Remove-PnPTeamsTeam deletes nothing.

Step 2: Add Two Channels

The first line looks the group up by mailNickname, a pattern every later step reuses:

$groupId = (Get-PnPMicrosoft365Group -Filter "mailNickname eq 'SPGDemoRetiredTeam'").Id

Add-PnPTeamsChannel -Team $groupId -DisplayName "SPGDemo Old Channel" -Description "Old project chatter" | Out-Null
Add-PnPTeamsChannel -Team $groupId -DisplayName "SPGDemo Q3 Planning" | Out-Null

Get-PnPTeamsChannel -Team $groupId | Select-Object DisplayName, MembershipType
Add-PnPTeamsChannel adding SPGDemo Old Channel and SPGDemo Q3 Planning to the demo team

Checkpoint: Three standard channels: General, SPGDemo Old Channel and SPGDemo Q3 Planning.

Private and shared channels also need -ChannelType and -OwnerUPN (see create a private channel in Microsoft Teams).

Step 3: Delete One Channel with Remove-PnPTeamsChannel

-Team takes the group ID, -Identity the channel name or ID, and -Force skips the prompt:

$groupId = (Get-PnPMicrosoft365Group -Filter "mailNickname eq 'SPGDemoRetiredTeam'").Id

# Deletes the channel (soft delete: owners can restore it in Teams for 21 days)
Remove-PnPTeamsChannel -Team $groupId -Identity "SPGDemo Old Channel" -Force

Start-Sleep -Seconds 15   # the channel list lags a few seconds behind the delete
Get-PnPTeamsChannel -Team $groupId | Select-Object DisplayName, MembershipType
Remove-PnPTeamsChannel deleting SPGDemo Old Channel, leaving SPGDemo Q3 Planning and General

On my first run, listing right after the delete still showed the old channel, hence the Start-Sleep. More on team vs channel in Microsoft Teams.

How to Permanently Delete a Teams Channel with PowerShell

No PowerShell command purges a channel right away. Remove-PnPTeamsChannel, Remove-TeamChannel and the Graph API all soft delete it: owners can restore it for 21 days, and the name stays reserved in that team:

$groupId = (Get-PnPMicrosoft365Group -Filter "mailNickname eq 'SPGDemoRetiredTeam'").Id

try {
    Add-PnPTeamsChannel -Team $groupId -DisplayName "SPGDemo Old Channel" -ErrorAction Stop
} catch {
    "Add failed: $($_.Exception.Message)"
}
Add-PnPTeamsChannel failing with Channel name already existed for the soft-deleted channel name

The same name on a brand-new team worked fine, so the block is per team. A channel becomes permanent after 21 days, or at once when you delete the team and purge its group (Steps 4-7).

To undo a channel delete, open the team in Teams: More team options > Manage team > Channels > Deleted > Restore.

Step 4: Delete the Team with Remove-PnPTeamsTeam

Remove-PnPTeamsTeam deletes the team and its Microsoft 365 group, so the SharePoint site, mailbox and Planner plans go too:

$groupId = (Get-PnPMicrosoft365Group -Filter "mailNickname eq 'SPGDemoRetiredTeam'").Id
"Deleting team $groupId"

# Deletes the team AND its Microsoft 365 group (SharePoint site, mailbox, Planner go with it)
Remove-PnPTeamsTeam -Identity $groupId -Force

$active = Get-PnPMicrosoft365Group -Identity $groupId -ErrorAction SilentlyContinue
"Group still active: $([bool]$active)"
Remove-PnPTeamsTeam deleting the SPGDemo Retired Team and Group still active False

Checkpoint: Group still active: False.

Conversations, files and chats go with the team, so back up Microsoft Teams files or export Teams chat history with PowerShell first.

Step 5: Find the Team in Deleted Groups

The group now waits in deleted groups for 30 days:

Get-PnPDeletedMicrosoft365Group |
    Where-Object DisplayName -eq "SPGDemo Retired Team" |
    Select-Object DisplayName, Id, DeletedDateTime | Format-List
Get-PnPDeletedMicrosoft365Group listing the soft-deleted SPGDemo Retired Team with its DeletedDateTime

Step 6: Restore the Team If You Change Your Mind

You can’t restore a deleted team directly; you restore its group, and the team comes back with it:

$deleted = Get-PnPDeletedMicrosoft365Group | Where-Object DisplayName -eq "SPGDemo Retired Team"

Restore-PnPDeletedMicrosoft365Group -Identity $deleted.Id | Out-Null

Get-PnPMicrosoft365Group -Identity $deleted.Id -Detailed |
    Select-Object DisplayName, MailNickname, HasTeam | Format-List
Get-PnPMicrosoft365Group returning Gone 410 right after Restore-PnPDeletedMicrosoft365Group

The Gone (410) error just meant the restore was still replicating. A few minutes later, the same check came back clean:

Restored SPGDemo Retired Team with HasTeam True and the SPGDemo Q3 Planning channel back

Checkpoint: HasTeam is True and SPGDemo Q3 Planning is back. The channel deleted before the team stayed deleted. Microsoft says a restore can take up to 24 hours.

Step 7: Purge the Group So It’s Gone for Good

Delete the group again and purge it. The loop waits until the group shows up in deleted groups, because purging too early finds nothing:

$groupId = (Get-PnPMicrosoft365Group -Filter "mailNickname eq 'SPGDemoRetiredTeam'").Id

Remove-PnPMicrosoft365Group -Identity $groupId

# wait until the group shows up in deleted groups, then purge it for good
do { Start-Sleep -Seconds 5
     $deleted = Get-PnPDeletedMicrosoft365Group -Identity $groupId -ErrorAction SilentlyContinue } until ($deleted)
Remove-PnPDeletedMicrosoft365Group -Identity $groupId

$left = Get-PnPDeletedMicrosoft365Group | Where-Object Id -eq $groupId
"Still in deleted groups: $(($left | Measure-Object).Count)"
Remove-PnPDeletedMicrosoft365Group purging the deleted team group with Still in deleted groups 0

Checkpoint: Still in deleted groups: 0. No restore after this.

Test the Script on a Fresh Team

I recreated the team with both channels and ran the all-in-one script from the top of this post (pass -MailNickname for another team):

param([string]$MailNickname = "SPGDemoRetiredTeam")

$group = Get-PnPMicrosoft365Group -Filter "mailNickname eq '$MailNickname'"
"1. Found team: $($group.DisplayName)"

Remove-PnPTeamsChannel -Team $group.Id -Identity "SPGDemo Q3 Planning" -Force
"2. Deleted channel: SPGDemo Q3 Planning"

Remove-PnPTeamsTeam -Identity $group.Id -Force
"3. Deleted team and Microsoft 365 group"

do {
    Start-Sleep -Seconds 5
    $gone = Get-PnPDeletedMicrosoft365Group -Identity $group.Id -ErrorAction SilentlyContinue
} until ($gone)
Remove-PnPDeletedMicrosoft365Group -Identity $group.Id
"4. Purged from deleted groups (no 30-day restore)"

$left = Get-PnPDeletedMicrosoft365Group | Where-Object Id -eq $group.Id
"Left behind: $(($left | Measure-Object).Count)"

Then I checked both lists for the team’s name:

$active  = Get-PnPMicrosoft365Group -Filter "mailNickname eq 'SPGDemoRetiredTeam'"
$deleted = Get-PnPDeletedMicrosoft365Group | Where-Object DisplayName -eq "SPGDemo Retired Team"

"Active groups named SPGDemo Retired Team:  $(($active | Measure-Object).Count)"
"Deleted groups named SPGDemo Retired Team: $(($deleted | Measure-Object).Count)"
Verification script showing 0 active and 0 deleted groups named SPGDemo Retired Team

Both are 0, and the team’s site wasn’t in the deleted sites list either. To remove a group-connected site on its own, see deleting a SharePoint Online site with PowerShell.

Same Thing with the MicrosoftTeams or Graph Module

These equivalents need an interactive sign-in, so they’re shown as code, not run here:

# MicrosoftTeams module
Install-Module MicrosoftTeams -Scope CurrentUser
Connect-MicrosoftTeams
$team = Get-Team -DisplayName "SPGDemo Retired Team"
Remove-TeamChannel -GroupId $team.GroupId -DisplayName "SPGDemo Old Channel"   # soft delete
Remove-Team -GroupId $team.GroupId                                            # team + group

# Microsoft Graph PowerShell
Connect-MgGraph -Scopes "Group.ReadWrite.All"
Remove-MgTeamChannel -TeamId $team.GroupId -ChannelId $channelId
Remove-MgGroup -GroupId $team.GroupId
Remove-MgDirectoryDeletedItem -DirectoryObjectId $team.GroupId                 # purge

No PowerShell? In the Teams admin center, select Teams, pick the team, select Delete, and confirm.

Troubleshooting

  • “Channel name already existed”: the old channel is soft-deleted. Restore it, rename, or wait 21 days.
  • Get-PnPTeamsTeam returns nothing: my app has no Teams read permission, so I used Get-PnPMicrosoft365Group.
  • The site doesn’t go away: a site under a retention policy stays until the retention period ends.

Important: a purge can’t be undone. When you aren’t sure, archive the team instead; it can be made active again.

Where to Take It Next

  • Read mailNicknames from a CSV and run the script per row, with a prompt before the purge.
  • Clean up conversations but keep the team: delete chats in Microsoft Teams.

Cleaning up more than one team? These tutorials help with the rest of the job:

Frequently Asked Questions

Does deleting a team with PowerShell delete the Microsoft 365 group?

Yes. Remove-PnPTeamsTeam and Remove-Team both delete the group with the team. The Remove-PnPTeamsTeam reference says it works the same as Remove-PnPMicrosoft365Group.

Can I restore a team after deleting it with PowerShell?

Yes, for 30 days. Restore its group with Restore-PnPDeletedMicrosoft365Group and the team comes back. Microsoft’s guide to archive or delete a team says the restore can take up to 24 hours.

How do I permanently delete a Teams channel with PowerShell?

You can’t purge a single channel right away. Remove-PnPTeamsChannel soft deletes it for 21 days, then it’s permanent. Deleting and purging the whole team removes its channels at once.

Can I delete the General channel?

No. Every team keeps its first channel, General by default (owners can now rename it), for as long as the team exists. To get rid of it, delete the team.