How to Safely Rename a SharePoint Hub Site URL with PnP PowerShell

📝 Introduction

Renaming a SharePoint Hub Site URL or title is not a straightforward process. A hub site can not be renamed directly. Instead, the hub site needs to be unregistered before performing the rename, and then re-register it as a hub. This ensures the integrity of the hub structure and keeps associated sites intact.

This post provides a step-by-step PowerShell script using PnP PowerShell to automate the process, including cleanup of redirect sites and validation of associated sites.

🛠️ What This Script Does This PowerShell script walks through:

✅ Unregistering the hub site

✏️ Renaming the site URL and title

🗑️ Deleting the redirect site automatically created after renaming

🔁 Re-registering the site as a hub

🔍 Verifying that child sites remain associated

📋 Prerequisites

  • Ensure the script is run by a user with the appropriate SharePoint Online Administation
  • PnP PowerShell Module installed and configured.

PowerShell Script: Rename a Hub Site

Below is a sample script to automate the hub site rename process:

param (
    [Parameter(Mandatory = $true)]
    [string]$domain = "contoso",

    [Parameter(Mandatory = $true)]
    [string]$currentSiteUrl = "https://contoso.sharepoint.com/sites/TestHR_Hub",

    [Parameter(Mandatory = $true)]
    [string]$updatedSiteUrl = "https://contoso.sharepoint.com/sites/TestHR_Hub_Updated"
)

$adminSiteURL = "https://$domain-Admin.SharePoint.com"
Connect-PnPOnline -Url $adminSiteURL

try {
    $siteId = (Get-PnPTenantSite -Identity $currentSiteUrl).SiteId
    $hubSite = Get-PnPHubSite -Identity $siteId.Guid -ErrorAction SilentlyContinue

    if (-not $hubSite) {
        Write-Host "The site is not a hub site or does not exist."
    }
    else {
        $childSites = Get-PnPHubSiteChild -Identity $siteId.Guid -ErrorAction SilentlyContinue
        Unregister-PnPHubSite -Site $siteId.Guid
    }

    Rename-PnPTenantSite -Identity $currentSiteUrl -NewSiteUrl $updatedSiteUrl -NewSiteTitle 'Test HR Hub' | Out-Null

    # Wait for the rename to complete
    $updatehubSite = Get-PnPTenantSite -Identity $updatedSiteUrl -ErrorAction SilentlyContinue
    while(-not $updatehubSite) {
        Start-Sleep -Seconds 30
        $updatehubSite = Get-PnPTenantSite -Identity $updatedSiteUrl -ErrorAction SilentlyContinue
    }

    # Remove the redirect site created by the rename
    Remove-PnPTenantSite -Url $currentSiteUrl -Force

    # Register the site as a hub site again
    Register-PnPHubSite -Site $updatedSiteUrl | Out-Null

    # Check if child sites are still associated
    $childSites1 = Get-PnPHubSiteChild -Identity $siteId.Guid -ErrorAction SilentlyContinue
    $result = Compare-Object -ReferenceObject $childSites1 -DifferenceObject $childSites
    if ($result) {
        Write-Host "Child sites have been updated after renaming the hub site."
    } else {
        Write-Host "No changes in child sites after renaming the hub site."
    }
}
catch {
    Write-Host "An error occurred while renaming the hub site: $_"
}

Output script

Output script

Outcome

The associated sites are maintained after rename.

Associated Sites

Conclusion

Renaming a SharePoint Hub Site URL requires careful handling to avoid breaking hub associations. By following this automated approach with PnP PowerShell, you can safely rename your hub site, clean up redirect sites, and ensure all associated sites remain connected.