SharePoint Online: PowerShell to Upload Master Page

Requirement: Upload master page to SharePoint Online.

How to add a master page to SharePoint Online?

To add a master page to SharePoint Online, do the following:

  1. Login to your SharePoint Online site >> Click on Settings >> Site Settings
  2. On the Site Settings page, click on “Master Pages” under Web Designer Galleries. This library is similar to any other document library. 
    sharepoint online upload master page
  3. Click on “Upload Document” link, browse and locate your custom master page and complete uploading. 
    upload master page to sharepoint online
  4. Once uploaded, you can change the master page from SharePoint web UI or PowerShell.

PowerShell to Upload Master page to SharePoint Online

This PowerShell script gets the Master page from the location specified and uploads it to SharePoint Online.  

#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 Upload-CustomMasterPage()
        [Parameter(Mandatory=$true)] [string] $SiteURL,
        [Parameter(Mandatory=$true)] [string] $MasterPageLocation

    Try {
        #Setup the context
        $Ctx = New-Object Microsoft.SharePoint.Client.ClientContext($SiteURL)
        $Ctx.Credentials = $Credentials
        #Get the Web
        $Web = $Ctx.web
        #Get the Master Page Gallery
        $MasterPageGallery = $Web.Lists.GetByTitle("Master Page Gallery")

        #Get the Master page from given local location 
        $MasterPageFile = Get-Item $MasterPageLocation
        $MasterPageContent = [System.IO.File]::ReadAllBytes($MasterPageFile.FullName)

        #Prepare the File to upload Master page Gallary
        $FileCreationInfo = New-Object Microsoft.SharePoint.Client.FileCreationInformation
        $FileCreationInfo.Overwrite = $True
        $FileCreationInfo.Content = $MasterPageContent
        $FileCreationInfo.URL = $
        Write-host "Uploading Master Page to Site:"$SiteURL
        #Upload the File to Master page Gallary
        $MasterPage = $MasterPageGallery.RootFolder.Files.Add($FileCreationInfo)  

        #Check-Out and Check-In to create major version
        $CheckIn = $MasterPage.CheckIn("Master Page Uploaded",[Microsoft.SharePoint.Client.CheckinType]::MajorCheckIn)
        Write-Host "Master Page '$MasterPageFile' Uploaded to site '$SiteURL'" -f Green

        <#Process subsites - Call the function recursively
        If($Web.Webs.Count -gt 0)
            Foreach ($web in $Web.Webs)
                Upload-CustomMasterPage -SiteURL $web.Url  -MasterPageLocation $MasterPageLocation
    Catch {
        write-host -f Red "Error Uploading Custom Master Page!" $_.Exception.Message

#Set parameter values

#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
Upload-CustomMasterPage -SiteURL $SiteURL -MasterPageLocation $MasterPageLocation

Please note, this script uploads the master page only to the given site URL. If you want to upload the master page to all subsites underneath, uncomment the lines. Once the Master page is uploaded, you can use this another article to apply the master page in SharePoint Online: How to Set Custom Master Page in SharePoint Online using PowerShell?

SharePoint Online: Deploy Custom Master page using PnP PowerShell

Here is the PnP PowerShell to upload the master page in SharePoint Online:

#Config Variables
$SiteURL = ""
$MasterPagePath = "C:\Users\salaudeen\Downloads\CrescentV2.master"

#Connect to PnP Online
Connect-PnPOnline -Url $SiteURL -Interactive
#Upload Master page to SharePoint Online site
Add-PnPMasterPage -SourceFilePath $MasterPagePath -Title "CrescentV2" -Description "Crescent V2 Master Page" -DestinationFolderHierarchy "CrescentV2"

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 *