Delete Microsoft 365 user accounts with PowerShell
You can use PowerShell for Microsoft 365 to delete and restore user accounts.
Note
Learn how to restore a user account by using the Microsoft 365 admin center.
For a list of additional resources, see Manage users and groups.
Use Microsoft Graph PowerShell to delete a user account
Note
The Azure Active Directory (AzureAD) PowerShell module is being deprecated and replaced by the Microsoft Graph PowerShell SDK. You can use the Microsoft Graph PowerShell SDK to access all Microsoft Graph APIs. For more information, see Get started with the Microsoft Graph PowerShell SDK.
Also see Install the Microsoft Graph PowerShell SDK and Upgrade from Azure AD PowerShell to Microsoft Graph PowerShell for information on how to install and upgrade to Microsoft Graph PowerShell, respectively.
For information about how to use different methods to authenticate Connect-Graph in an unattended script, see the article Authentication module cmdlets in Microsoft Graph PowerShell.
Deleting a user account requires the User.ReadWrite.All permission scope, which is listed in the 'Assign license' Microsoft Graph API reference page.
The User.Read.All permission scope is required to read the user account details in the tenant.
First, connect to your Microsoft 365 tenant.
# Connect to your tenant
Connect-MgGraph -Scopes User.Read.All, User.ReadWrite.All
After you connect, use the following syntax to remove an individual user account:
$userName="<display name>"
# Get the user
$userId = (Get-MgUser -Filter "displayName eq '$userName'").Id
# Remove the user
Remove-MgUser -UserId $userId -Confirm:$false
This example removes the user account Caleb Sills.
$userName="Caleb Sills"
$userId = (Get-MgUser -Filter "displayName eq '$userName'").Id
Remove-MgUser -UserId $userId -Confirm:$false
Restore a user account
To a restore a user account using Microsoft Graph PowerShell, first connect to your Microsoft 365 tenant.
To restore a deleted user account, the permission scope Directory.ReadWrite.All is required. Connect to the tenant with this permision scope:
# Connect to your tenant
Connect-MgGraph -Scopes Directory.ReadWrite.All
Deleted user accounts no longer exist except as objects in the directory, so you can't search for the user account to restore. Instead, use the following PowerShell script to search the directory for deleted objects of the type microsoft.graph.user:
$DeletedUsers = Get-MgDirectoryDeletedItem -DirectoryObjectId microsoft.graph.user -Property '*'
$DeletedUsers = $DeletedUsers.AdditionalProperties['value']
foreach ($deletedUser in $DeletedUsers)
{
$deletedUser | Format-Table
}
The output of this script, assuming any deleted user objects exist in the directory, will look like this:
Key Value
--- -----
businessPhones {}
displayName Caleb Sills
givenName Caleb
mail [email protected]
surname Sills
userPrincipalName [email protected]
id cdea706c-3fdc-4bbd-9592-5d92d9f71eb8
Use the following syntax to restore an individual user account:
# Input user account ID
$userId = "<id>"
# Restore the user
Restore-MgDirectoryDeletedItem -DirectoryObjectId $userId
This example restores the user account [email protected] using the value for $userID from the output of the above script.
$userId = "cdea706c-3fdc-4bbd-9592-5d92d9f71eb8"
Restore-MgDirectoryDeletedItem -DirectoryObjectId $userId
The output of this command looks like this:
Id DeletedDateTime
-- ---------------
cdea706c-3fdc-4bbd-9592-5d92d9f71eb8
See also
Manage Microsoft 365 user accounts, licenses, and groups with PowerShell