In the latter part of 2019, Microsoft announced it was releasing a badly-needed PowerShell cmdlet called Invoke-SPOSiteSwap. This cool little cmdlet can be used to move your jazzy site you’ve been working on behind the scenes to the root level site of your tenant. But please don’t forget to inform your users, your making the move so they aren’t shocked when they see the new root site. 😊

The release of the Invoke-SPOSiteSwap began in August of 2019, but was being rolled out to tenants in phases based on the number of licenses, but as of February 2020, it is now available in all tenants regardless of size.

Simply said, the cmdlet swaps the location of the source site with a target site and archives the original target site. In more general terms, when the swap is initiated three actions take place;

    1. The current target site is moved to the archive location
    2. The current source site is move to the target location
    3. By default, a site redirect is created at the source location to redirect traffic to new target site

There are a few requirements and restrictions you need to be aware of when considering using this cmdlet that include;

SharePoint Admin PowerShell version 16.0.19418.0 or later must be used to run cmdlet

The target site can only be the root site or the Search Center using site templates:

Team Site (STS#0)

Modern Team Site (STS#3)

Communication Site (SITEPAGEPUBLISHING#0)

Search Center Site (SRCHCEN#0)

Basic Search Center Site (SRCHCENTERLITE#0)

If target site is a root site, you must also take the following steps;

Featured links will be removed, so document them, and recreate after swap

Review and document external sharing settings and application interfaces prior to swap, and review new root site to be sure they are the same as the original root site

Neither the source or target site can be associated with an Office 365 Group

Neither source or target site can be a hub site, or even associated with a hub site. However;

You can unregister the hub site, run cmdlet, then re-register site as hub site

If site is associated with hub, disassociate it, run cmdlet, re-associate site to hub


Let’s take a look at the Invoke-SPOSiteSwap cmdlet parameters;


-SourceUrl <string> (URL of source site, must exist before swap)

-TargetUrl <string> (URL of target site, must exist before swap)

-ArchiveUrl <string> (URL target site archived to, should be empty)

[-DisableRedirection] (disables site redirect from being created)

Let's see the cmdlet in action;





The previous command will:

Archive the existing to

Moves to

By default it will also automatically create a site redirect of to

As you can see the Invoke-SPOSiteSwap cmdlet is very powerful as it provides you the option to create, customize, and tweak a hidden site, and then move it into production with little effort. I hope you find this cmdlet as helpful as I have while working with SharePoint Online.

Leave a Reply

Your email address will not be published. Required fields are marked *