SharePoint Online: Change Master Page using PowerShell

Requirement: Change the Master Page in SharePoint Online.

How to Set Master Page in SharePoint Online?

If you want to change the master page in SharePoint Online, follow these steps:

  1. Login to your SharePoint Online site >> Click on Settings Gear Icon >> Site Settings
  2. From the Site Settings page >> Click On the “Master page” link under the Look and Feel group. This page lists all master pages available on your SharePoint Online site. (URL shortcut: /_Layouts/ChangeSiteMasterPage.aspx) 
  3. Pick the master page to be used on all site pages. Optionally, you can specify if you want to “Reset all subsites to inherit this site master page setting” and hit OK.
    sharepoint online change master page powershell
  4. This sets the master page for your SharePoint Online site. From this page, you can set a theme and alternate CSS for your site to add even more branding to your SharePoint Online site.
Note: If the Master Page link is not available in site settings, you need to activate SharePoint Publishing feature with these steps: How to Enable Publishing Feature in SharePoint Online?

Now, To automate the process of changing a custom Master Page, let’s use PowerShell!

SharePoint Online: Change Master Page using PowerShell

Here is the SharePoint Online PowerShell to set the master page, assuming the custom master page “Crescent.master” is already deployed to the site.

#Load SharePoint CSOM Assemblies
Add-Type -Path "C:\Program Files\Common Files\Microsoft Shared\Web Server Extensions\16\ISAPI\Microsoft.SharePoint.Client.dll"
Add-Type -Path "C:\Program Files\Common Files\Microsoft Shared\Web Server Extensions\16\ISAPI\Microsoft.SharePoint.Client.Runtime.dll"

Function Set-CustomMasterPage()
{
    param
    (
        [Parameter(Mandatory=$true)] [string] $SiteURL,
        [Parameter(Mandatory=$true)] [string] $MasterPage    
    )

    Try {
        #Setup the context
        $Ctx = New-Object Microsoft.SharePoint.Client.ClientContext($SiteURL)
        $Ctx.Credentials = $Credentials

        #Get the Web
        $Web = $Ctx.web
        $Ctx.Load($Web)
        $Ctx.ExecuteQuery()
    
        #Frame Master page URL
        $MasterPageURL = "$($web.ServerRelativeUrl)/_catalogs/masterpage/$($MasterPage)"

        #Set Default Master page & Custom Master page
        $web.CustomMasterUrl = $MasterPageURL
        $Web.MasterUrl = $MasterPageURL
        $web.Update()
        $Ctx.ExecuteQuery()

        Write-Host "Master Page '$MasterPage' Applied on site '$SiteURL'" -f Green
    }
    Catch {
        write-host -f Red "Error Changing Master Page!" $_.Exception.Message
    }
}

#Set parameter values
$SiteURL="https://crescent.sharepoint.com/sites/sales/us"
$MasterPage="Crescent.master"

#Setup Credentials to connect
$Cred= Get-Credential
$Credentials = New-Object Microsoft.SharePoint.Client.SharePointOnlineCredentials($Cred.Username, $Cred.Password)

#Call the function to change master page
Set-CustomMasterPage -SiteURL $SiteURL -MasterPage $MasterPage

This script sets the master page for a given site (web). Let’s alter the script slightly to change the master page for all subsites in a site collection.

SharePoint Online PowerShell to Set Master Page

To change the master page in a SharePoint Online site collection, including each subsite, use this script:

#Load SharePoint CSOM Assemblies
Add-Type -Path "C:\Program Files\Common Files\Microsoft Shared\Web Server Extensions\16\ISAPI\Microsoft.SharePoint.Client.dll"
Add-Type -Path "C:\Program Files\Common Files\Microsoft Shared\Web Server Extensions\16\ISAPI\Microsoft.SharePoint.Client.Runtime.dll"

Function Set-CustomMasterPage()
{
    param
    (
        [Parameter(Mandatory=$true)] [string] $SiteURL,
        [Parameter(Mandatory=$true)] [string] $MasterPage    
    )

    Try {
        #Setup the context
        $Ctx = New-Object Microsoft.SharePoint.Client.ClientContext($SiteURL)
        $Ctx.Credentials = $Credentials

        #Get the Web
        $Web = $Ctx.web
        $Ctx.Load($Web)
        $Ctx.Load($Web.Webs)
        $Ctx.ExecuteQuery()
    
        #Frame Master page URL
        $MasterPageURL = "$($web.ServerRelativeUrl)/_catalogs/masterpage/$($MasterPage)"

        #Set Default Master page & Custom Master page
        $web.CustomMasterUrl = $MasterPageURL
        $Web.MasterUrl = $MasterPageURL
        $web.Update()
        $Ctx.ExecuteQuery()

        Write-Host "Master Page '$MasterPage' Applied on site '$SiteURL'" -f Green

        #Call the function recursively for all subsites
        Foreach ($Subsite in $Web.Webs)
        {
            #Call the function to apply master page in sharepoint online
            Set-CustomMasterPage -SiteURL $Subsite.URL -MasterPage $MasterPage
        }
    }
    Catch {
        write-host -f Red "Error Changing Master Page!" $_.Exception.Message
    }
}

#Set parameter values
$SiteURL="https://crescent.sharepoint.com/sites/sales/"
$MasterPage="seattle.master"

#Setup Credentials to connect
$Cred= Get-Credential
$Credentials = New-Object Microsoft.SharePoint.Client.SharePointOnlineCredentials($Cred.Username, $Cred.Password)

#Call the function to change master page
Set-CustomMasterPage -SiteURL $SiteURL -MasterPage $MasterPage

Please note, your custom master page must be uploaded before changing the master page (which is obvious!). To upload the custom master page to SharePoint Online, use: How to upload Master page to SharePoint Online using PowerShell?

PnP PowerShell to Change Master page in SharePoint Online

Here is how to change the master page of a SharePoint Online site using the PnP PowerShell cmdlet Set-PnPMasterPage.

#Config Variables
$SiteURL = "https://Crescent.sharepoint.com/sites/marketing"
$MasterPageServerRelativeUrl = "/sites/Marketing/_catalogs/masterpage/CrescentV2/CrescentV2.master"

#Connect to PnP Online
Connect-PnPOnline -Url $SiteURL -Interactive

#Set Master page
Set-PnPMasterPage -MasterPageServerRelativeUrl $MasterPageServerRelativeUrl -CustomMasterPageServerRelativeUrl $MasterPageServerRelativeUrl
sharepoint online change master page powershell

Similarly, to change the master page of all sites in a site collection, use the following:

#Config Variables
$SiteURL = "https://Crescent.sharepoint.com/sites/marketing"
$MasterPageServerRelativeUrl = "/sites/Marketing/_catalogs/masterpage/CrescentV2/CrescentV2.master"

#Connect to PnP Online
Connect-PnPOnline -Url $SiteURL -Credentials (Get-Credential)

#Get All Subsites from given site collection
$SubWebs = Get-PnPSubWeb

ForEach ($web in $SubWebs)
{
    #Set Master page for the web
    Set-PnPMasterPage -MasterPageServerRelativeUrl $MasterPageServerRelativeUrl `
          -CustomMasterPageServerRelativeUrl $MasterPageServerRelativeUrl -Web $web.ServerRelativeUrl
}

Salaudeen Rajack

Salaudeen Rajack - Information Technology Expert with Two-decades of hands-on experience, specializing in SharePoint, PowerShell, Microsoft 365, and related products. He has held various positions including SharePoint Architect, Administrator, Developer and consultant, has helped many organizations to implement and optimize SharePoint solutions. Known for his deep technical expertise, He's passionate about sharing the knowledge and insights to help others, through the real-world articles!

Leave a Reply

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