Change your SharePoint domain name

When you first sign up for Microsoft 365, you create an onmicrosoft.com domain. Even if you later add a custom domain, all your SharePoint and OneDrive URLs use the original onmicrosoft.com domain.

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 change the domain name by using PowerShell. For example, if your organization name changes from Contoso to Fabrikam, you can change your SharePoint URLs from contoso.sharepoint.com to fabrikam.sharepoint.com.

Limitations of changing a SharePoint domain name

Low impact

Medium impact

High impact

What is Advanced Tenant Rename?

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

Advanced Tenant Rename is a part of SharePoint Advanced Management.

What are the prerequisites?

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

• Meet Prerequisites for SharePoint Advanced Management.
• Your organization doesn't have Microsoft 365 Multi Geo enabled.
• Your organization doesn't use government clouds, including GCC, GCC High, and DoD.
• Your organization doesn't use vanity domains (from an earlier MTE offering).

How do I prioritize sites when renaming domain?

By using Advanced Tenant Rename, you can prioritize up to 4,000 sites for early execution. This list can include both OneDrive and SharePoint sites, but it excludes root sites (for example, contoso.sharepoint.com, contoso-admin.sharepoint.com, contoso-my.sharepoint.com).

The prioritized sites are processed first among all the sites in your organization. This priority gives them the opportunity to complete their renames sooner. Plan your tenant rename to start at the beginning of a low-impact period (such as weekends or holidays) and prioritize those sites that you believe are important to have accessible at the start of the next business day.

To manage prioritization, use the following PowerShell cmdlets.

• Set-SPOTenantRenameSitePrioritization – Prioritize the specified site for early execution.
• Remove-SPOTenantRenameSitePrioritization – Remove prioritization for the specified site.
• Get-SPOTenantRenameSitePrioritization – View the current list of prioritized sites.

Use the PowerShell cmdlets for prioritization after you schedule the tenant rename. You can make changes to the list of prioritized sites up to two hours before the scheduled start time of the rename. Once the rename starts, the system doesn't accept further changes.

Step 1: How do I 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, the domain is taken and you need to try a different one. If another customer already registered the domain, Microsoft 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

   Don't 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 Microsoft 365 admin center.

   • Don't use the Add domain option directly present in the Domains page, since that option doesn't create a .onmicrosoft.com domain. Use the steps in the specified link to correctly create one.
   • Don't 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. 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.

   Run this command:

   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.

   Here's an example:

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

   If that PowerShell command isn't found or returns nothing, 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 the following command:

   Uninstall-Module Microsoft.Online.SharePoint.PowerShell -Force -AllVersions
   

   For more information, see Start-SPOTenantRename.

   To cancel a rename before it starts, you can run the following command:

   Stop-SPOTenantRename
   

   For more information, see Stop-SPOTenantRename.

Step 3: Prioritize sites (premium)

If you purchase SharePoint Advanced Management licenses for all users when you schedule your rename, the process automatically considers Advanced Tenant Rename and gives you the ability to prioritize sites.

Use the Set-SPOTenantRenameSitePrioritization cmdlet to prioritize individual sites. For example, to prioritize a site named projectx, run the following command:

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

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

Here's an example:

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

If you attempt this operation with a file that has all 4,000 sites in it, the complete execution of this cmdlet can take approximately 4-6 hours. If you want shorter waiting times, split your list of sites and run the command in batches.

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

Get-SPOTenantRenameSitePrioritization

To remove prioritization for a site, run the following command:

Remove-SPOTenantRenameSitePrioritization

For example, to remove prioritization for the projectx site, run the following command:

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

Prioritizing a site isn't a guarantee that the site rename finishes first. Several factors can affect processing times, and the system processes multiple site renames in parallel. Prioritized sites have a higher chance of completing first.

Step 4: Monitor the status of the rename

To check the status of the rename operation, run the following command:

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 follows the local format of the system where the cmdlet is run.

For more information, see Get-SPOTenantRenameStatus.

During and after the rename, you can get the state of a site by running the following command:

Get-SPOSiteRenameState

For more information 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 is shown in the Attention Required field.

To get more information on these sites, run the following command:

Get-SPOSiteRenameState
``

Pass the `RenameJobID` listed in the tenant rename status as the `ParentOperationID`, and the status (such as Success, Failed, or Suspended). If you want to export these results to a CSV file, you can use the follownig cmdlet:

```powershell
Export-Csv

Here's an example:

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 action includes reviewing any Group Policy settings that might control browser settings.

3. Review any non-Microsoft 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 SharePoint Framework components can use the new domain name.

Troubleshooting

• Frequently asked questions

• Errors and how to fix them