The Remove-MsolUser cmdlet is a powerful command used in the MSOnline PowerShell module to manage user deletion in Microsoft 365 (formerly Office 365). It allows administrators to perform two key actions: moving a user to the Recycle Bin (a “soft delete”) and permanently purging a user from the directory (a “hard delete”). Understanding this two-stage process is crucial for effective user management.
This guide will walk you through the steps to use Remove-MsolUser to both soft-delete and permanently delete users.
Prerequisites: Connect to PowerShell
Before you can use the Remove-MsolUser cmdlet, you need to connect to your Microsoft 365 tenant using PowerShell.
- Install the Module: If you haven’t already, install the MSOnline module. Open PowerShell as an administrator and run:
PowerShell
Install-Module -Name MSOnline
- Connect to Your Tenant: Use the following command to connect. A sign-in window will appear for you to enter your global administrator credentials.
PowerShell
Connect-MsolService
Step 1: Soft-Deleting a User (Moving to Recycle Bin)
A soft delete removes the user from the list of active users and places them in the “Deleted users” container, also known as the Recycle Bin. The user can be restored from here within 30 days. After 30 days, Microsoft automatically deletes them permanently.
To soft-delete a user, you use the Remove-MsolUser cmdlet with the user’s User Principal Name (UPN).
Syntax
PowerShell
Remove-MsolUser -UserPrincipalName “[email protected]”
Example
Let’s delete a user named [email protected].
PowerShell
Remove-MsolUser -UserPrincipalName “[email protected]”
PowerShell will ask for confirmation. Type ‘Y’ and press Enter to proceed. To bypass this confirmation prompt, you can add the -Force parameter.
PowerShell
Remove-MsolUser -UserPrincipalName “[email protected]” -Force
At this point, the user account is in the Recycle Bin. You can view all users in the Recycle Bin with this command:
PowerShell
Get-MsolUser -ReturnDeletedUsers
Step 2: Permanently Deleting a User (Purging from Recycle Bin)
If you need to delete a user immediately and permanently, bypassing the 30-day grace period, you must perform a hard delete. This action is irreversible. ⚠️ Once a user is purged, their data cannot be recovered.
This is often used to free up a UPN or proxy address immediately for a new user.
To permanently purge a user, you use the Remove-MsolUser cmdlet again, but this time you add the -RemoveFromRecycleBin switch.
Syntax
PowerShell
Remove-MsolUser -UserPrincipalName “[email protected]” -RemoveFromRecycleBin
Example
To permanently purge the user [email protected] that we previously soft-deleted:
PowerShell
Remove-MsolUser -UserPrincipalName “[email protected]” -RemoveFromRecycleBin -Force
Adding -Force will again skip the confirmation prompt. The user is now permanently deleted from your Azure Active Directory tenant.
Bulk Deletion Scenarios
The Remove-MsolUser cmdlet is also useful for bulk operations.
Purge All Users from the Recycle Bin
To permanently delete every user currently in the Recycle Bin, you can pipe the output of Get-MsolUser -ReturnDeletedUsers directly into the Remove-MsolUser command.
PowerShell
Get-MsolUser -ReturnDeletedUsers | Remove-MsolUser -RemoveFromRecycleBin -Force
This command first gets a list of all deleted users and then, for each user in that list, runs the permanent removal command.
Delete Multiple Users from a CSV File
If you have a list of users to delete in a CSV file, you can automate the process. Assume you have a file named users-to-delete.csv with a header called UPN.
CSV File Content (users-to-delete.csv):
Code snippet
UPN
PowerShell Script:
PowerShell
# Import the list of users from the CSV
$users = Import-Csv -Path "C:\path\to\users-to-delete.csv"
# Loop through each user in the list and perform a soft delete
foreach ($user in $users) {
Write-Host "Deleting $($user.UPN)..."
Remove-MsolUser -UserPrincipalName $user.UPN -Force
}
Write-Host "Deletion script finished."This script will soft-delete each user listed in the CSV file. You could easily modify it to perform a hard delete by adding the -RemoveFromRecycleBin switch.
Of course. Here is a conclusion for the article.
Reference:
- https://learn.microsoft.com/en-us/microsoft-365/enterprise/delete-and-restore-user-accounts-with-microsoft-365-powershell?view=o365-worldwide
- How to Give Mailbox Permissions to Another Office 365 User?
Conclusion
Mastering the Remove-MsolUser cmdlet is an essential skill for any Microsoft 365 administrator. It provides direct, command-line control over the user lifecycle, from a standard soft delete (moving a user to the Recycle Bin) to an immediate, permanent purge using the -RemoveFromRecycleBin parameter.
Always exercise caution, especially when permanently deleting users. This action is irreversible and should only be performed after verifying the user’s identity and ensuring any necessary data has been backed up or transferred. For bulk operations, double-check your source files to prevent accidental deletion of the wrong accounts.
While the MSOnline module remains functional, it is important to note that Microsoft is transitioning towards the newer Microsoft Graph PowerShell SDK for all Azure AD and Microsoft 365 management tasks. As you become comfortable with these commands, it is highly recommended to begin exploring the equivalent cmdlets in Microsoft Graph to future-proof your administrative scripts and skills.
