Change your SharePoint domain name

When you first signed up for Microsoft 365, you created an onmicrosoft.com domain. Even if you later added a custom domain, the original onmicrosoft.com domain is used for all your SharePoint and OneDrive URLs.

If your organization is going through a rebranding, merger, or acquisition and needs to change the domain in your SharePoint and OneDrive URLs, you can do this using PowerShell. For example, if your organization name changed from Contoso to Fabrikam, you can change your SharePoint URLs from contoso.sharepoint.com to fabrikam.sharepoint.com.

Limitations

Low impact

Medium impact

High impact

Advanced Tenant Rename

If you want to rename an organization with over 10,000 total sites or want to have greater control over the rename operation, you must use Advanced Tenant Rename. It supports changing the SharePoint domain on tenants with up to 100,000 total sites currently and has the ability for admins to prioritize up to 4,000 sites in their organization for early execution within the overall rename. This allows for select business-critical or high-visibility sites to complete first and reduce any risk or concerns with its impact on daily operations.

Advanced Tenant Rename is a part of SharePoint Advanced Management.

Prerequisites

Advanced Tenant Rename can currently only support tenants meeting the following conditions:

• You must have SharePoint Advanced Management licenses purchased for all users in your organization.
• Your organization has <100,000 total sites.
• Your organization doesn’t have Microsoft365 Multi Geo enabled.
• Your organization doesn’t use government clouds, including GCC, GCC High and DoD.
• Your organization doesn’t use vanity domains (from the earlier MTE offering).

Prioritizing sites

With Advanced Tenant Rename, you can prioritize up to 4,000 sites for early execution. This can include both OneDrive and SharePoint sites, excluding root sites (e.g., contoso.sharepoint.com, contoso-admin.sharepoint.com, contoso-my.sharepoint.com).

Prioritized sites would be picked up for processing first, among all the sites in your organization. This allows them the opportunity to complete their renames sooner. You can make the most of this by planning your tenant rename to start at the beginning of a low impact period (weekends, holidays, etc.) and prioritize those sites that you believe are going to be important to have accessible at the start of the next business day.

To manage prioritization, you can make use of the following PowerShell cmdlets.

• Set-SPOTenantRenameSitePrioritization – This allows you to prioritize the specified site for early execution.
• Remove-SPOTenantRenameSitePrioritization – This allows you to remove prioritization for the specified site.
• Get-SPOTenantRenameSitePrioritization – This allows you to view the current list of prioritized sites.

The PowerShell cmdlets for prioritization should be used once the tenant rename is scheduled. Changes to the list of prioritized sites will be supported up to 2 hours before the scheduled start time of the rename. Once the rename starts, further changes will not be accepted.

Step 1: Add the new domain name

1. Check the availability of the new domain you want. For example, if you want your SharePoint and OneDrive URLs to begin with fabrikam.sharepoint.com, enter https://fabrikam.sharepoint.com in a browser. If you get a message that the address couldn’t be found (404), it’s probably available. If you get a sign-in screen or a message that your username couldn’t be found in the fabrikam.sharepoint.com directory, then the domain is taken and you need to try a different one. If the domain is already registered by another customer, we can't provide any information or contact the customer.

   -or-

   If you own the domain for another subscription, you need to delete that tenant in Microsoft Entra ID. Deleting a tenant typically takes three days to complete and to make the domain available.

   Warning

   Do NOT use the domain to test this procedure in a test environment first. If you do, you won't be able to use the domain for your production environment.

2. Add your new .onmicrosoft.com domain using the Domains page in the M365 Admin Center.

   • Do not use the "Add domain" option directly present in the Domains page, since that does not create a .onmicrosoft.com domain. Use the steps in the link above to correctly create one.
   • Do not make this domain your fallback domain.

3. Go back to the Domains page and check that the newly added .onmicrosoft.com domain appears in a 'Healthy' state.

Step 2: Use Microsoft PowerShell to rename your domain

1. REQUIRED - Download the latest SharePoint Online Management Shell. If you installed a previous version of the SharePoint Online Management Shell, go to Add or remove programs and uninstall "SharePoint Online Management Shell". Make sure you review the System Requirements and Install Instructions. The app isn't supported on Mac.

2. Connect to SharePoint as at least a SharePoint Administrator in Microsoft 365. To learn how, see Getting started with SharePoint Online Management Shell.

   Example:

   Connect-SPOService -Url "https://contoso-admin.sharepoint.com"

3. Run the following command to specify the new domain name:

   Start-SPOTenantRename -DomainName <DomainName> -ScheduledDateTime <YYYY-MM-DDTHH:MM:SS> [-WhatIf] [-Confirm] 
   

   Where "DomainName" is the part before "sharepoint.com" or "onmicrosoft.com" and "ScheduledDateTime" is at least 24 hours in the future, but not more than 30 days. The time you enter is based on the current date and time of the computer you're using.

   Example:

   Start-SPOTenantRename -DomainName "fabrikam" -ScheduledDateTime "2021-12-31T10:25:00"

   If the PowerShell command Start-SPOTenantRename is not found or nothing is returned, make sure you installed the latest SharePoint Online Management Shell. Before installing the latest version, you might need to uninstall all previous versions by running Uninstall-Module Microsoft.Online.SharePoint.PowerShell -Force -AllVersions. For more info about the Start-SPOTenantRename cmdlet, see Start-SPOTenantRename

To cancel a rename before it starts, you can run Stop-SPOTenantRename. More info about this cmdlet

Step 3: Prioritize sites (premium)

If you had purchased SharePoint Advanced Management licenses for all users at the time of scheduling your rename, it would be automatically considered an Advanced Tenant Rename, with the ability to prioritize sites.

You can prioritize individual sites using the Set-SPOTenantRenameSitePrioritization cmdlet. For example, to prioritize a site ‘projectx’, you should run the following command:

Set-SPOTenantRenameSitePrioritization -SiteUrl https://contoso.sharepoint.com/sites/projectx

If you have already identified the list of sites you’d want prioritized and want to perform the Set operation in bulk, you can populate them in a CSV file and then use PowerShell to import it and iteratively execute the cmdlets. The file should just have a single column with title as ‘SiteUrl’, and every subsequent row should be the full URL of the desired site.

Example:

Import-Csv <Path> | ForEach-Object {Set-SPOTenantRenameSitePrioritization -SiteUrl $_.SiteUrl}

If you attempt this with a file that has the entire 4,000 sites in it, the complete execution of this cmdlet can take approximately 4-6 hours. If you want shorter waiting times, we recommend splitting your list of sites up and performing this in batches.

To view the list of sites prioritized currently, run the following command:

Get-SPOTenantRenameSitePrioritization

And if you want to remove prioritization for a site, you can run the Remove-SPOTenantRenameSitePrioritization cmdlet. For example, to remove prioritization for the ‘projectx’ site, you should run the following command:

Remove-SPOTenantRenameSitePrioritization -SiteUrl https://contoso.sharepoint.com/sites/projectx

Prioritizing a site isn't a guarantee that it will be completed first. There are several factors that can affect processing times, and multiple site renames are processed in parallel. Prioritized sites have a higher chance of completing first.

Step 4: Monitor the status of the rename

You can get the status of the rename by running Get-SPOTenantRenameStatus. Make sure you open a new PowerShell window to sign in again. The date and time shown with this command is in UTC time (but will follow the local format of the system where the cmdlet is run). More info about Get-SPOTenantRenameStatus During and after the rename, you can get the state of a site by running Get-SPOSiteRenameState. For more info about this cmdlet, see Get-SPOSiteRenameState.

To verify success of the rename operation, review the status of the rename operation, and the count of renamed sites in comparison to total sites. The count of sites that can't be renamed to the new domain will be shown in the Attention Required field. To get more information on these sites, run Get-SPOSiteRenameState and pass the RenameJobID listed in the tenant rename status as the ParentOperationID, and the desired status (Success/Failed/Suspended). If you want to export these results to a CSV file, you can use the Export-Csv cmdlet.

Get-SPOSiteRenameState -ParentOperationID <RenameJobID> -State Failed | Export-Csv -Path <Path>

Step 5: Review features and settings after the rename

1. Review any firewall rules that might block access to the new domain.

2. Review organization browser settings to make sure the new domain is a trusted location. This includes reviewing any Group Policy settings that might control browser settings.

3. Review any third-party apps, custom apps, and scripts that access SharePoint. They might need to be modified to use the new domain.

4. If you have custom SharePoint Framework solutions that require access to an API, check the API access page in the SharePoint admin center to ensure that the new domain name can be used by SharePoint Framework components.

Troubleshooting

• Frequently asked questions
• Errors and how to fix them