A script is faster and repeatable, but deleting folders blindly is risky too. A folder takes every file and subfolder inside it, so I want each delete to land in the recycle bin where I can undo it.

In this tutorial, I’ll show you how I handle delete folder sharepoint powershell jobs with PnP PowerShell: delete one folder, delete a subfolder, clear out only empty folders, handle a missing folder, restore a folder from the recycle bin, and run it in Windows PowerShell 5.1.

Quick answer: Connect with Connect-PnPOnline, then run Remove-PnPFolder -Name "Archive 2025" -Folder "SPGuidesProjects" -Recycle -Force. -Name is the folder to delete, -Folder is its parent’s site-relative URL, -Recycle sends it to the site recycle bin instead of deleting it outright, and -Force skips the confirmation prompt.

What you need before you start

You need the PnP.PowerShell module, your own Entra ID app registration for sign-in, and at least Edit permission on the library. I covered the install and the app registration step by step in my post on creating a folder in SharePoint with PowerShell, so here’s only the short version:

Install-Module PnP.PowerShell -Scope CurrentUser

Connect-PnPOnline -Url "https://spguides.sharepoint.com/sites/SPGuides" -ClientId "<your-app-client-id>" -DeviceLogin -PersistLogin

Replace the client ID with your app’s Application (client) ID. If the install itself gives you trouble, this guide to installing PnP PowerShell for SharePoint Online walks through the usual fixes.

I ran every script below on 10/25/2026 against my /sites/SPGuides site, in PowerShell 7.6.7 with PnP.PowerShell 3.3.0. The library shows as SPGuides Projects, but its URL name is SPGuidesProjects.

How do I delete a folder with Remove-PnPFolder?

Remove-PnPFolder takes the folder name and its parent path as two separate values. That trips people up, because you don’t pass the full path of the folder you’re deleting:

Here’s the script I ran on the Archive 2025 folder. It counts the files first, deletes the folder to the recycle bin, then checks whether it’s still there:

$folder = Get-PnPFolder -Url "SPGuidesProjects/Archive 2025" -Includes ItemCount
"Deleting $($folder.ServerRelativeUrl) ($($folder.ItemCount) files inside)"

# -Recycle sends the folder and everything in it to the site recycle bin; -Force skips the prompt
Remove-PnPFolder -Name "Archive 2025" -Folder "SPGuidesProjects" -Recycle -Force

$stillThere = Get-PnPFolder -Url "SPGuidesProjects/Archive 2025" -ErrorAction SilentlyContinue
"Archive 2025 still exists: $([bool]$stillThere)"

With -Recycle, the cmdlet returns a RecycleBinItemId, the ID of the new recycle bin entry. The final check confirms the folder is gone:

Deleting /sites/SPGuides/SPGuidesProjects/Archive 2025 (3 files inside)

RecycleBinItemId
----------------
c928b896-ec82-4f73-a7d3-4f0cf5a272bf
Archive 2025 still exists: False

The -Folder value is the library’s URL name, not its display name. The default Documents library is Shared Documents, for example. To look up URL names, list all lists and libraries with PnP PowerShell.

What happens without -Recycle?

According to the PnP documentation, leaving out -Recycle deletes the folder directly instead of moving it to the recycle bin, so you can’t restore it from there. I never run it that way on client sites, and I didn’t run it for this post either.

Leaving out -Force is harmless: PowerShell just asks you to confirm each delete. I keep the prompt while I test a script and add -Force once the paths are right.

Where does the deleted folder go?

With -Recycle, the folder and everything in it land in the site recycle bin, exactly as if you’d deleted it in the browser. Open the site, go to Site contents, and select Recycle bin.

Here’s my site recycle bin after the test runs. Each entry shows the original location and who deleted it, and Q1 2027 Planning appears twice because I deleted it in two separate runs:

Microsoft keeps deleted items for 93 days from the original delete. That window covers both the site recycle bin and the second-stage site collection recycle bin. My SharePoint recycle bin tutorial explains both stages.

Delete a subfolder and everything inside it

To delete a folder deeper in the tree, put the full parent path in -Folder. My Old Projects folder had a 2024 subfolder with Kickoff and Status Reports inside it. Get-PnPFolderItem lists what’s about to go before the delete runs:

# -Folder is the parent path; -Name is the folder to delete (its subfolders go with it)
Get-PnPFolderItem -FolderSiteRelativeUrl "SPGuidesProjects/Old Projects/2024" -ItemType Folder |
    Select-Object Name

Remove-PnPFolder -Name "2024" -Folder "SPGuidesProjects/Old Projects" -Recycle -Force | Out-Null
"Deleted: SPGuidesProjects/Old Projects/2024 and its subfolders"

Both subfolders went with 2024; there’s no separate recursive switch. If you only want to relocate a branch, not delete it, move the folder in SharePoint Online instead.

Delete only empty folders

Upload jobs and migrations leave behind empty folders. This loop checks each subfolder’s ItemCount and deletes only the ones with nothing in them:

$parent = "SPGuidesProjects/Temp Uploads"

$folders = Get-PnPFolderItem -FolderSiteRelativeUrl $parent -ItemType Folder
foreach ($f in $folders) {
    if ($f.ItemCount -eq 0) {
        Remove-PnPFolder -Name $f.Name -Folder $parent -Recycle -Force | Out-Null
        "Deleted empty folder: $($f.Name)"
    } else {
        "Kept: $($f.Name) ($($f.ItemCount) item)"
    }
}

My Temp Uploads folder had Batch 01 through Batch 05, and only Batch 05 held a file (an upload log). The script deleted the four empty ones and kept the fifth:

Deleted empty folder: Batch 01
Deleted empty folder: Batch 02
Deleted empty folder: Batch 03
Deleted empty folder: Batch 04
Kept: Batch 05 (1 item)

ItemCount counts subfolders too, so a folder that holds only an empty subfolder is kept. Run the loop again to catch the next level. If empty folders keep coming back, revisit your SharePoint folder structure.

Restore a deleted folder with PnP PowerShell

When someone deletes the wrong folder, you can bring it back without opening the browser. Get-PnPRecycleBinItem reads the recycle bin, and Restore-PnPRecycleBinItem puts the item back in its original location:

$item = Get-PnPRecycleBinItem -FirstStage |
    Where-Object { $_.LeafName -eq "Archive 2025" -and $_.ItemType -eq "Folder" }
$item | Select-Object LeafName, DirName, ItemType, DeletedByName

$item | Restore-PnPRecycleBinItem -Force
$restored = Get-PnPFolder -Url "SPGuidesProjects/Archive 2025" -ErrorAction SilentlyContinue
"Archive 2025 restored: $([bool]$restored)"

The output showed Archive 2025 from sites/SPGuides/SPGuidesProjects with ItemType Folder, then Archive 2025 restored: True. Filter on ItemType, because a file and a folder can share a name.

Two catches. Get-PnPRecycleBinItem needs Site Collection Administrator rights, so a site member gets nothing back. And restore the folder entry itself: restoring a single file from a deleted folder recreates the folder with only that file in it.

Delete a folder in Windows PowerShell 5.1

PnP.PowerShell 3.x needs PowerShell 7.4 or later. On a server that only has Windows PowerShell 5.1, the last version that loads is PnP.PowerShell 1.12.0, and its -DeviceLogin also needs -Tenant:

Install-Module PnP.PowerShell -RequiredVersion 1.12.0 -Scope CurrentUser
Connect-PnPOnline -Url "https://spguides.sharepoint.com/sites/SPGuides" -ClientId "<your-app-client-id>" -Tenant "spguides.onmicrosoft.com" -DeviceLogin

Remove-PnPFolder takes the same parameters in 1.12.0. This is the script I ran there:

"PowerShell $($PSVersionTable.PSVersion) / PnP.PowerShell $((Get-Module PnP.PowerShell).Version)"

Remove-PnPFolder -Name "Q1 2027 Planning" -Folder "SPGuidesProjects" -Recycle -Force

$check = Get-PnPFolder -Url "SPGuidesProjects/Q1 2027 Planning" -ErrorAction SilentlyContinue
"Q1 2027 Planning still exists: $([bool]$check)"

It printed PowerShell 5.1.26100.9444 with PnP.PowerShell 1.12.0, a RecycleBinItemId, and still exists: False. If 5.1 says the cmdlet isn’t recognized, see this fix for Connect-PnPOnline is not recognized.

What to check before you delete a folder

• What’s inside: run Get-PnPFolderItem with -Recursive first. A folder delete takes every file and subfolder with it.
• Retention labels and policies: retention settings don’t apply to folders themselves, but they do apply to the files inside. A file under a retention policy can be deleted, and SharePoint keeps a copy in the hidden Preservation Hold library.
• Records: a file with a locked record label or a regulatory record label can’t be deleted, so the folder delete fails with an error.
• Flows and links: anything that writes to the folder path, such as a Power Automate flow, breaks once the folder is gone.

If you only want the files gone and the folder kept, delete the files instead. This flow shows how to delete all files in a SharePoint folder with Power Automate.

Common errors and how to fix them

The one I see most is File Not Found. It means the folder name or the parent path is wrong. This test deleted a folder that doesn’t exist, with -ErrorAction Stop so the catch block runs:

try {
    Remove-PnPFolder -Name "Archive 2026" -Folder "SPGuidesProjects" -Recycle -Force -ErrorAction Stop
} catch {
    "Remove failed: $($_.Exception.Message)"
}

• “File Not Found.”: check the folder’s spelling and that -Folder is the parent path with the library’s URL name, not its display name.
• Access denied: your account needs at least Edit permission on the library to delete folders.
• Get-PnPRecycleBinItem returns nothing: you need to be a Site Collection Administrator, or the item already moved to the second stage (use -SecondStage).
• Delete blocked by a label: a file inside has a record label. Ask your compliance admin before you touch it.

For more ready-made admin scripts, browse my PnP PowerShell scripts for SharePoint developers or the SharePoint tutorials hub.

If you’re cleaning up more than folders, these PnP PowerShell tutorials cover the next jobs:

• Download All Files from a SharePoint Document Library Using PnP PowerShell
• How to Upload Files to a SharePoint Document Library Using PnP PowerShell
• Get SharePoint Folder Permissions Using PnP PowerShell
• How to Delete a SharePoint Online Site Using PowerShell (PnP and SPO)

Frequently Asked Questions

Bijay Kumar

Hey! I’m Bijay Kumar, founder of SPGuides.com and a Microsoft Business Applications MVP (Power Automate, Power Apps). I launched this site in 2020 because I truly enjoy working with SharePoint, Power Platform, and SharePoint Framework (SPFx), and wanted to share that passion through step-by-step tutorials, guides, and training videos. My mission is to help you learn these technologies so you can utilize SharePoint, enhance productivity, and potentially build business solutions along the way.

www.enjoysharepoint.com

In this tutorial, I’ll walk you through the create folder sharepoint powershell steps I use: install PnP PowerShell, register an Entra app, connect, add a folder, skip existing ones, build nested folders, load a CSV, and handle Windows PowerShell 5.1.

Here’s the shortest version that works once the module is installed:

Connect-PnPOnline -Url "https://spguides.sharepoint.com/sites/SPGuides" -ClientId "<your-app-client-id>" -DeviceLogin -PersistLogin

Add-PnPFolder -Name "Q4 2026 Reports" -Folder "SPGuidesProjects"

It creates a Q4 2026 Reports folder in the root of the SPGuides Projects library and returns the new folder object.

What you need before you start

You need the PnP.PowerShell module, an Entra ID app registration for sign-in, and at least Edit (Contribute) rights on the library. If folders are new to you, my guide on creating a folder in SharePoint from the browser shows the same result by hand.

I ran every script in this post on 10/25/2026 with PowerShell 7.6.7 and PnP.PowerShell 3.3.0, and again in Windows PowerShell 5.1 with PnP.PowerShell 1.12.0.

Step 1: Install PnP PowerShell

Current PnP PowerShell needs PowerShell 7.4.0 or later. Open PowerShell 7 (pwsh, not the blue Windows PowerShell window) and install the module for your account:

Install-Module PnP.PowerShell -Scope CurrentUser

No admin rights are needed with -Scope CurrentUser. If anything goes wrong, follow this walkthrough to install PnP PowerShell for SharePoint Online.

Step 2: Register your own Entra ID app

Since September 9, 2024, PnP PowerShell no longer ships a shared sign-in app, so every tenant needs its own app registration. The module can create one for you:

Register-PnPEntraIDAppForInteractiveLogin -ApplicationName "PnP.PowerShell" -Tenant spguides.onmicrosoft.com

Replace the tenant with yours. Creating the app needs the Application Developer role, and a Global Administrator may have to grant admin consent. Copy the Application (client) ID it prints; that’s your -ClientId.

Step 3: Connect to the site

Connect to the site that holds the library. I use -DeviceLogin, which shows a code to enter at the Microsoft device login page, and -PersistLogin so the next session reuses the token. More sign-in options are in connecting to SharePoint Online with PowerShell:

$siteUrl  = "https://spguides.sharepoint.com/sites/SPGuides"
$clientId = "<your-app-client-id>"   # your own Entra app's client ID
Connect-PnPOnline -Url $siteUrl -ClientId $clientId -DeviceLogin -PersistLogin

$web = Get-PnPWeb
"Connected to: $($web.Title) ($($web.Url))"
$lib = Get-PnPList -Identity "SPGuides Projects" -Includes RootFolder.Name
"Library display name: $($lib.Title) / URL name: $($lib.RootFolder.Name)

The last two lines confirm the connection: the site title and URL, then the library’s display name (SPGuides Projects) next to its URL name (SPGuidesProjects).

If PowerShell says the cmdlet isn’t recognized, the module didn’t load in that window; this fix for Connect-PnPOnline is not recognized covers the usual causes.

How do I create a folder with Add-PnPFolder?

Add-PnPFolder has only two working parameters, which is why it’s my default for a single folder:

Here’s the script I ran. The pipe to Select-Object just keeps the output short:

# -Folder is the site-relative URL of the parent: the library's URL name, not its display name
Add-PnPFolder -Name "Q4 2026 Reports" -Folder "SPGuidesProjects" |
    Select-Object Name, ServerRelativeUrl, ItemCount

The output shows the folder’s server-relative URL and an ItemCount of 0, so it’s a new, empty folder:

Name            ServerRelativeUrl                                ItemCount
----            -----------------                                ---------
Q4 2026 Reports /sites/SPGuides/SPGuidesProjects/Q4 2026 Reports         0

Refresh the library in the browser and the folder is there. This view also shows the folders the later examples in this post create:

To create a subfolder, point -Folder at the parent folder’s path. This adds Invoices inside Q4 2026 Reports:

Add-PnPFolder -Name "Invoices" -Folder "SPGuidesProjects/Q4 2026 Reports"

The parent must already exist for Add-PnPFolder. For deeper paths, use Resolve-PnPFolder, covered below. If the library itself is missing, first create the document library with PnP PowerShell.

Library display name vs URL name: the gotcha

The -Folder parameter wants a URL path, not the name you see in the left navigation. My library shows as SPGuides Projects, but its URL name is SPGuidesProjects, with no space.

The classic example is the default library. It’s called Documents on screen, but its URL name is Shared Documents, so the parent there is -Folder "Shared Documents".

To find the URL name, run the Get-PnPList line from the connect script, or read it from the library address after the site path. To list every library at once, use this guide to get all lists and libraries with PnP PowerShell.

Create a folder only if it doesn’t already exist

Add-PnPFolder doesn’t skip existing folders. When I ran it a second time, it threw this error:

A file or folder with the name https://spguides.sharepoint.com/sites/SPGuides/SPGuidesProjects/Q4 2026 Reports already exists.

For scripts that run more than once, check with Get-PnPFolder first. This script shows both behaviors, the failed second Add-PnPFolder and the safe check:

$parent = "SPGuidesProjects"
$name   = "Q4 2026 Reports"

# Running Add-PnPFolder twice throws an error, so check first
try {
    Add-PnPFolder -Name $name -Folder $parent -ErrorAction Stop | Out-Null
} catch {
    "Add-PnPFolder failed: $($_.Exception.Message)"
}

$existing = Get-PnPFolder -Url "$parent/$name" -ErrorAction SilentlyContinue
if ($existing) {
    "Skipped: $($existing.ServerRelativeUrl) already exists"
} else {
    Add-PnPFolder -Name $name -Folder $parent | Out-Null
    "Created: $parent/$name"
}

The try block printed the error, and the check printed Skipped: /sites/SPGuides/SPGuidesProjects/Q4 2026 Reports already exists. The same pattern works for files, lists and sites; see checking if a folder, file or list exists in SharePoint.

Create nested folders and subfolders with Resolve-PnPFolder

Resolve-PnPFolder takes a full site-relative path, creates every level that’s missing, and returns the last folder. If the folder already exists, it just returns it, so there’s no error to handle:

# Resolve-PnPFolder creates every missing level and returns the last folder
Resolve-PnPFolder -SiteRelativePath "SPGuidesProjects/Clients/2026/Website Redesign" |
    Select-Object Name, ServerRelativeUrl

# Run it again: nothing is created, the existing folder comes back (no error)
$again = Resolve-PnPFolder -SiteRelativePath "SPGuidesProjects/Clients/2026/Website Redesign"
"Second run returned: $($again.ServerRelativeUrl)"

One call created Clients, 2026 and Website Redesign. The second run returned /sites/SPGuides/SPGuidesProjects/Clients/2026/Website Redesign without creating anything.

That makes Resolve-PnPFolder the better choice for any script you’ll rerun. Before you build deep trees, though, read my SharePoint folder structure best practices; metadata columns often beat a fifth folder level.

Add-PnPFolder or Resolve-PnPFolder: which one to use?

Both cmdlets return the same folder object, so the rest of your script doesn’t care which one made it. The difference is how they treat paths and existing folders:

I use Add-PnPFolder when a duplicate means something went wrong and I want the script to stop. For everything else, especially scheduled scripts, Resolve-PnPFolder saves the extra Get-PnPFolder check.

Create multiple folders from a CSV file

For bulk folders, keep the names in a CSV so a business user can maintain the list. Mine, saved as folders.csv, has a Department and a Year column:

Department,Year
Finance,2026
Human Resources,2026
Marketing,2026
Sales,2026
IT,2026

This loop builds a path per row and lets Resolve-PnPFolder create each one:

$rows = Import-Csv -Path ".\folders.csv"

foreach ($row in $rows) {
    $path   = "SPGuidesProjects/Departments/$($row.Department)/$($row.Year)"
    $folder = Resolve-PnPFolder -SiteRelativePath $path
    "Ready: $($folder.ServerRelativeUrl)"
}

"{0} folder paths processed" -f $rows.Count

It printed five Ready lines, one per department, and 5 folder paths processed. Because Resolve-PnPFolder skips existing folders, you can add rows later and rerun the same script.

In the browser, the Departments folder now holds Finance, Human Resources, IT, Marketing and Sales, each with a 2026 subfolder:

Once the folders exist, you can upload files to the library with PnP PowerShell into each path, or report on folder permissions with PnP PowerShell if departments need different access.

Create a folder in Windows PowerShell 5.1

PnP.PowerShell 3.x doesn’t load in Windows PowerShell 5.1, because it needs PowerShell 7.4 or later. If a server only has 5.1, the last version that runs there is PnP.PowerShell 1.12.0.

Install that version for your account, then connect. With 1.12.0, -DeviceLogin also needs -Tenant:

Install-Module PnP.PowerShell -RequiredVersion 1.12.0 -Scope CurrentUser
Connect-PnPOnline -Url "https://spguides.sharepoint.com/sites/SPGuides" -ClientId "<your-app-client-id>" -Tenant "spguides.onmicrosoft.com" -DeviceLogin

Without -Tenant, my 5.1 test failed with Please specify -Tenant with either the tenant id or hostname. Adding the tenant hostname fixed it on the next try.

After that, both folder cmdlets behave the same as in PowerShell 7:

"PowerShell $($PSVersionTable.PSVersion) / PnP.PowerShell $((Get-Module PnP.PowerShell).Version)"

Add-PnPFolder -Name "Q1 2027 Planning" -Folder "SPGuidesProjects" |
    Select-Object Name, ServerRelativeUrl

Resolve-PnPFolder -SiteRelativePath "SPGuidesProjects/Clients/2027/Intranet Refresh" |
    Select-Object Name, ServerRelativeUrl

The output confirms PowerShell 5.1.26100.9444 with PnP.PowerShell 1.12.0, then the new Q1 2027 Planning folder and the nested Intranet Refresh folder. Version 1.12.0 doesn’t get updates anymore, so move to PowerShell 7 when you can.

Common errors and fixes

• “A file or folder with the name … already exists”: Add-PnPFolder found the folder. Check with Get-PnPFolder first, or use Resolve-PnPFolder.
• The parent path isn’t found: you probably passed the library’s display name. Use its URL name (Shared Documents for Documents, SPGuidesProjects here).
• Invalid folder names: SharePoint rejects ” * : < > ? / \ | and leading or trailing spaces. Resolve-PnPFolder names also can’t end with a period.
• Access denied: your account needs at least Edit (Contribute) permission on the library.
• Connect-PnPOnline asks for a ClientId: register your own Entra app (Step 2) and pass its client ID.

What about the SharePoint Online Management Shell? It has no folder cmdlets at all (I checked version 16.0.27424), so folder work is a PnP PowerShell job.

To clean up a test folder, send it to the recycle bin instead of deleting it permanently:

Remove-PnPFolder -Name "Q4 2026 Reports" -Folder "SPGuidesProjects" -Recycle -Force

That keeps a 93-day safety net in the site recycle bin. For more ready-made scripts, browse my PnP PowerShell scripts for SharePoint developers or the SharePoint tutorials hub.

If you’re automating more document library work, these tutorials pick up where this one ends:

• Download All Files from a SharePoint Document Library Using PnP PowerShell
• How to Move Folders in SharePoint Online?
• 2 Best Ways to Create a Folder in SharePoint From Power Apps
• SharePoint Document Set vs Folder: Which One Should You Use?

Need to clean up test folders afterwards? My companion post shows how to delete a folder in SharePoint Online with PnP PowerShell.

Frequently Asked Questions

Bijay Kumar

Hey! I’m Bijay Kumar, founder of SPGuides.com and a Microsoft Business Applications MVP (Power Automate, Power Apps). I launched this site in 2020 because I truly enjoy working with SharePoint, Power Platform, and SharePoint Framework (SPFx), and wanted to share that passion through step-by-step tutorials, guides, and training videos. My mission is to help you learn these technologies so you can utilize SharePoint, enhance productivity, and potentially build business solutions along the way.

www.enjoysharepoint.com

A PnP site template fixes it. You build the lists once on a model site, export them to a template file with PnP PowerShell, and apply that file to every new site in about a minute, sample tasks included.

In this tutorial, we’ll build a SharePoint site template PnP PowerShell workflow from scratch: install the module, create a source site, add the lists, export them with Get-PnPSiteTemplate, pack in sample rows, and apply everything to a brand-new site with Invoke-PnPSiteTemplate. Every command below ran in my tenant on 10/27/2026.

Here’s what we’re building. This is SPGuides Project Alpha, a site that didn’t exist a minute earlier, with the Project Tasks list, all four custom columns and the four starter tasks copied from the template:

The finished setup has four parts:

• A source site (/sites/SPGuidesProjectTemplate) that holds the model lists.
• A template file (ProjectSiteTemplate.pnp) exported from that site.
• Data rows inside the template, so every new site starts with the same tasks.
• A reusable function that creates a project site and applies the template in one call.

Before You Start

You need PowerShell 7.4 or later and the PnP.PowerShell module (Step 1 checks both). If you’ve never used it, my guide to install PnP PowerShell for SharePoint Online covers the setup in more detail.

• Permissions: creating sites with New-PnPSite needs the SharePoint Administrator or Global Administrator role, or self-service site creation turned on for your tenant.
• Entra ID app: since September 9, 2024, PnP PowerShell requires your own Entra ID app registration. Creating it needs rights to register apps and grant consent (Step 2).
• Tools: any editor works. I used VS Code for the longer scripts and a plain PowerShell 7 window for the short ones.

Here’s the list and library we’ll put in the template. Internal names matter, because the scripts and the data rows refer to them:

And the four starter tasks every new project gets:

How a PnP Site Template Works

A PnP site template is a file that describes a site: lists, columns, content types, views, pages, navigation, theme and more. Get-PnPSiteTemplate reads a live site and writes that file. Invoke-PnPSiteTemplate reads the file and creates whatever is missing on another site. It’s the open-source PnP provisioning engine, so there’s no Microsoft support SLA behind it.

Two rules shape everything that follows. First, a site template doesn’t create the site: the target site must already exist, which is why every apply step starts with New-PnPSite. Second, it copies structure, not content. List items only travel when you add them as data rows, and files in a library don’t travel at all with the export we use.

Note: SharePoint also has “site templates” in the browser (Settings > Apply a site template). Those are site designs built from JSON site scripts, which is a different tool.

If that’s what you want, read how to create a custom site template with site designs. To find which built-in template a site was created from, see how to get the site template ID with PowerShell.

Step 1: Install PnP PowerShell and Check the Version

Goal: make sure the shell and module are new enough before we touch SharePoint.

1. Open PowerShell 7 (pwsh), not Windows PowerShell 5.1.
2. If PnP PowerShell isn’t installed yet, remove the # in front of the Install-Module line and run it once.
3. Run the version checks.

# Run once: installs PnP PowerShell for your account (needs PowerShell 7.4 or later)
# Install-Module PnP.PowerShell -Scope CurrentUser

$PSVersionTable.PSVersion.ToString()
Get-Module PnP.PowerShell -ListAvailable |
    Sort-Object Version -Descending |
    Select-Object -First 1 Name, Version

Already have it? Run Update-Module PnP.PowerShell to get the latest release. If a later command says Connect-PnPOnline isn’t recognized, the module isn’t loaded in this shell; this fix for Connect-PnPOnline is not recognized walks through it.

Checkpoint: The console prints 7.6.7 for PowerShell and PnP.PowerShell 3.3.0 (any PowerShell 7.4+ and a current 3.x module works the same).

Step 2: Register Your Entra ID App and Connect

Goal: get a working sign-in that every later script reuses without asking for the client ID again.

1. Run Register-PnPEntraIDAppForInteractiveLogin once for your tenant and sign in when the browser opens.
2. Accept the consent prompt for the permissions the app asks for.
3. Copy the client ID the command prints. That’s your app’s ID.

# Run once per tenant: creates your own Entra ID app for interactive PnP PowerShell sign-ins
# Replace yourtenant with your tenant name
Register-PnPEntraIDAppForInteractiveLogin -ApplicationName "PnP.PowerShell" -Tenant yourtenant.onmicrosoft.com

Now connect. Putting the client ID in $env:ENTRAID_CLIENT_ID means you can leave -ClientId off every Connect-PnPOnline call. -DeviceLogin shows a code you enter at the Microsoft sign-in page, and -PersistLogin caches the token so you don’t sign in again after a restart. There’s more on the options in my post on how to connect to SharePoint Online using PowerShell.

# Paste the client ID of the app you registered
$env:ENTRAID_CLIENT_ID = "<your app's client id>"

# Replace yourtenant with your tenant name
Connect-PnPOnline -Url "https://yourtenant.sharepoint.com/sites/SPGuides" -DeviceLogin -PersistLogin

# Always confirm which site this window is connected to
(Get-PnPWeb).Url

Prefer a browser pop-up over a device code? Use -Interactive with -ClientId instead. The second line below is the fix I needed once when the device login refused to start:

# Alternative: sign in through a browser window instead of a device code
Connect-PnPOnline -Url "https://yourtenant.sharepoint.com/sites/SPGuides" -Interactive -ClientId "<your app's client id>"

# If -DeviceLogin asks for the tenant, add it
Connect-PnPOnline -Url "https://yourtenant.sharepoint.com/sites/SPGuides" -DeviceLogin -PersistLogin -Tenant yourtenant.onmicrosoft.com

Checkpoint: (Get-PnPWeb).Url returns https://yourtenant.sharepoint.com/sites/SPGuides, the site you just connected to.

Step 3: Create the Source Site

Goal: a clean communication site that will hold the model lists. Keeping the model on its own site means the template never picks up clutter from a real project.

1. Stay connected to any site in the tenant (I used /sites/SPGuides).
2. Run New-PnPSite with -Type CommunicationSite and -SiteDesign Blank.
3. Leave -Wait on so the command returns only when the site is ready.

# Your Entra ID app's client ID is in $env:ENTRAID_CLIENT_ID, so -ClientId can be left out
# Replace yourtenant with your tenant name
Connect-PnPOnline -Url "https://yourtenant.sharepoint.com/sites/SPGuides" -DeviceLogin -PersistLogin

# Create the source (model) site that we'll turn into a template
New-PnPSite -Type CommunicationSite `
    -Title "SPGuides Project Template" `
    -Url "https://yourtenant.sharepoint.com/sites/SPGuidesProjectTemplate" `
    -SiteDesign Blank -Wait

Be patient here. With -Wait, New-PnPSite took more than 90 seconds for this site, and the window just sits there until SharePoint finishes. A team site works too, but -Type TeamSite needs -Alias and creates a Microsoft 365 group. My guide to create a site in SharePoint Online using PnP PowerShell compares both.

Checkpoint: The command returns https://yourtenant.sharepoint.com/sites/SPGuidesProjectTemplate and the empty site opens in the browser.

Step 4: Build the Project Tasks List and Project Documents Library

Goal: create the two lists and their columns on the source site, exactly as the Before You Start table describes.

1. Connect to the new source site.
2. Create Project Tasks with New-PnPList, then add each column with Add-PnPField.
3. Use Set-PnPField to make the dates date-only (DisplayFormat 0) and to give Status a default of Not Started.
4. Create the Project Documents library with the URL ProjectDocuments and add its two columns.
5. List the results to confirm both exist.

# Replace yourtenant with your tenant name
Connect-PnPOnline -Url "https://yourtenant.sharepoint.com/sites/SPGuidesProjectTemplate" -DeviceLogin -PersistLogin

# 1. Custom list: Project Tasks
New-PnPList -Title "Project Tasks" -Template GenericList -OnQuickLaunch | Out-Null
Add-PnPField -List "Project Tasks" -DisplayName "Assigned To" -InternalName "AssignedTo" -Type User -AddToDefaultView | Out-Null
Add-PnPField -List "Project Tasks" -DisplayName "Due Date" -InternalName "DueDate" -Type DateTime -AddToDefaultView | Out-Null
Set-PnPField -List "Project Tasks" -Identity "DueDate" -Values @{DisplayFormat = 0}   # 0 = date only
Add-PnPField -List "Project Tasks" -DisplayName "Status" -InternalName "TaskStatus" -Type Choice `
    -Choices "Not Started", "In Progress", "Completed" -AddToDefaultView | Out-Null
Set-PnPField -List "Project Tasks" -Identity "TaskStatus" -Values @{DefaultValue = "Not Started"}
Add-PnPField -List "Project Tasks" -DisplayName "Priority" -InternalName "Priority" -Type Choice `
    -Choices "High", "Medium", "Low" -AddToDefaultView | Out-Null

# 2. Custom library: Project Documents
New-PnPList -Title "Project Documents" -Url "ProjectDocuments" -Template DocumentLibrary -OnQuickLaunch | Out-Null
Add-PnPField -List "Project Documents" -DisplayName "Document Type" -InternalName "DocumentType" -Type Choice `
    -Choices "Proposal", "Contract", "Report", "Meeting Notes" -AddToDefaultView | Out-Null
Add-PnPField -List "Project Documents" -DisplayName "Review Date" -InternalName "ReviewDate" -Type DateTime -AddToDefaultView | Out-Null
Set-PnPField -List "Project Documents" -Identity "ReviewDate" -Values @{DisplayFormat = 0}

Get-PnPList | Where-Object Title -like "Project*" | Select-Object Title, ItemCount, BaseTemplate

The -InternalName values matter later: data rows and scripts use internal names, not display names. For more column types, see how to create a SharePoint list and add columns using PnP PowerShell, and these tips for customizing SharePoint list fields cover defaults and formats.

Checkpoint: The output table shows Project Documents with BaseTemplate 101 and Project Tasks with BaseTemplate 100, both with ItemCount 0.

Step 5: Add Sample Tasks and a Test Document

Goal: give the source site real data, so we can see exactly what the template carries over.

1. Set $me to a user in your tenant (Assigned To needs a real account).
2. Add the four tasks with Add-PnPListItem, using internal names as the keys.
3. Upload one file, Project-Charter.docx, to Project Documents with Add-PnPFile and set its two columns.
4. Read the tasks back.

# Replace yourtenant with your tenant name
Connect-PnPOnline -Url "https://yourtenant.sharepoint.com/sites/SPGuidesProjectTemplate" -DeviceLogin -PersistLogin
$me = "bijay@yourtenant.onmicrosoft.com"   # any user in your tenant

# Sample tasks every new project should start with (noon UTC keeps the date right in US time zones)
$tasks = @(
    @{Title = "Kickoff meeting with stakeholders"; DueDate = "2026-11-02T12:00:00Z"; TaskStatus = "Completed";   Priority = "High"}
    @{Title = "Gather requirements";               DueDate = "2026-11-09T12:00:00Z"; TaskStatus = "In Progress"; Priority = "High"}
    @{Title = "Set up the project site";           DueDate = "2026-11-16T12:00:00Z"; TaskStatus = "Not Started"; Priority = "Medium"}
    @{Title = "Send the weekly status report";     DueDate = "2026-11-20T12:00:00Z"; TaskStatus = "Not Started"; Priority = "Low"}
)
foreach ($t in $tasks) {
    $t.AssignedTo = $me
    Add-PnPListItem -List "Project Tasks" -Values $t | Out-Null
}

# One document in the library (to test what the template copies)
Add-PnPFile -Path ".\Project-Charter.docx" -Folder "ProjectDocuments" `
    -Values @{DocumentType = "Proposal"; ReviewDate = "2026-11-06T12:00:00Z"} | Out-Null

Get-PnPListItem -List "Project Tasks" -Fields Title, TaskStatus, Priority |
    ForEach-Object { [pscustomobject]@{ Task = $_["Title"]; Status = $_["TaskStatus"]; Priority = $_["Priority"] } }

Notice the dates end in T12:00:00Z. My first run used plain “2026-11-02” strings, and SharePoint showed 11/1/2026: a date-only string is stored as midnight UTC, which is still the previous day in a US time zone. Noon UTC lands on the right day everywhere in the US.

Here’s the list in the browser, with Assigned To, Due Date, Status and Priority filled in. For more ways to add items (CSV, batches, every column type), see how to add SharePoint Online list items using PnP PowerShell.

And the library with Document Type set to Proposal and a Review Date of 11/06/2026:

Checkpoint: Project Tasks has 4 items (Completed, In Progress and two Not Started) and Project Documents has 1 file, Project-Charter.docx.

Step 6: Export the Site Template with Get-PnPSiteTemplate

Goal: save the two lists to a template file, once as readable XML and once as a .pnp package.

1. Create a folder for templates (I used C:\SPGuidesDemo\Templates).
2. Run Get-PnPSiteTemplate with -Handlers Lists and -ListsToExtract naming both lists.
3. Run it a second time with a .pnp file name.
4. Compare the two files.

# Replace yourtenant with your tenant name
Connect-PnPOnline -Url "https://yourtenant.sharepoint.com/sites/SPGuidesProjectTemplate" -DeviceLogin -PersistLogin
$folder = "C:\SPGuidesDemo\Templates"

# Only the two custom lists, with their columns and views
$lists = "Project Tasks", "Project Documents"

# .xml = readable file, .pnp = package (needed for list data rows)
Get-PnPSiteTemplate -Out "$folder\ProjectSiteTemplate.xml" -Handlers Lists -ListsToExtract $lists -Force
Get-PnPSiteTemplate -Out "$folder\ProjectSiteTemplate.pnp" -Handlers Lists -ListsToExtract $lists -Force

Get-ChildItem "$folder\ProjectSiteTemplate.*" | Select-Object Name, Length, LastWriteTime

Why two formats? The .xml file is plain text you can read and edit. The .pnp file is a package (a zipped container) that can also hold files and data rows, and Add-PnPDataRowsToSiteTemplate in Step 8 only works with .pnp. In practice I keep the .xml for reading and apply the .pnp.

-Handlers Lists limits the export to lists and their columns and views. Without it, Get-PnPSiteTemplate also exports pages, navigation, theme and site settings. The docs warn that naming handlers “might result in a non-working template” when something depends on a skipped part, so test it, as we do in Step 9.

These export switches are the ones you’ll reach for most:

If you want the whole site instead of two lists, drop -Handlers and -ListsToExtract and add the switches you need:

# Everything the default handlers export (pages, navigation, theme, lists, columns ...)
Get-PnPSiteTemplate -Out "C:\SPGuidesDemo\Templates\FullSite.pnp" -IncludeAllPages -PersistBrandingFiles -IncludeSiteGroups -Force

Checkpoint: ProjectSiteTemplate.xml is 7,949 bytes and ProjectSiteTemplate.pnp is 4,922 bytes.

Step 7: Look Inside the Template File

Goal: confirm the template holds what we expect before we apply it anywhere. Two minutes here saves a confused hour later.

1. Load the .xml file into an [xml] variable.
2. Walk down to Lists.ListInstance and print each list.
3. Print every field inside each list.

# Read the exported template and list what it will create
[xml]$template = Get-Content "C:\SPGuidesDemo\Templates\ProjectSiteTemplate.xml"
$lists = $template.Provisioning.Templates.ProvisioningTemplate.Lists.ListInstance

$lists | Select-Object Title, Url, TemplateType | Format-Table

foreach ($list in $lists) {
    $list.Fields.Field | Select-Object @{n = "List"; e = { $list.Title }}, DisplayName, Name, Type
}

There’s one surprise: a seventh field, Checked Out To (CheckoutUser), which SharePoint adds to every document library on its own. It’s harmless.

The template records each list’s TemplateType (100 and 101) and URL, and the file uses the 2022/09 schema with SITEPAGEPUBLISHING#0 as its base template. To read the same details from a live site, see how to get SharePoint list column details using PnP PowerShell.

Checkpoint: Two lists (Project Documents, Project Tasks) and seven fields: Document Type, Review Date, Checked Out To, Assigned To, Due Date, Status and Priority.

Step 8: Add the Sample Tasks to the Template as Data Rows

Goal: make every new site start with the four tasks, not an empty list.

1. Stay connected to the source site (the cmdlet reads the items from there).
2. Run Add-PnPDataRowsToSiteTemplate against the .pnp file.
3. Name the list and the internal names of the fields to copy.

# Replace yourtenant with your tenant name
Connect-PnPOnline -Url "https://yourtenant.sharepoint.com/sites/SPGuidesProjectTemplate" -DeviceLogin -PersistLogin

# Copy the 4 sample tasks into the .pnp package (works with .pnp files only)
Add-PnPDataRowsToSiteTemplate -Path "C:\SPGuidesDemo\Templates\ProjectSiteTemplate.pnp" `
    -List "Project Tasks" -Fields "Title", "AssignedTo", "DueDate", "TaskStatus", "Priority"

Get-Item "C:\SPGuidesDemo\Templates\ProjectSiteTemplate.pnp" | Select-Object Name, Length, LastWriteTime

Add-PnPDataRowsToSiteTemplate also takes -Query (a CAML query) to copy only some items, -IncludeSecurity for item permissions, and -TokenizeUrls to swap site URLs for tokens. The rows land with an empty KeyColumn and UpdateBehavior Overwrite, which matters in the test below. To edit or remove rows on a live site instead, see SharePoint list item CRUD with PnP PowerShell.

Checkpoint: The .pnp file grows from 4,922 to 5,187 bytes and now contains 4 data rows for Project Tasks.

Step 9: Create a New Site and Apply the Template with Invoke-PnPSiteTemplate

Goal: the payoff. A new project site gets both lists, all columns and the starter tasks.

1. Create the target site, SPGuides Project Alpha, with New-PnPSite (again, give it 90 seconds or more).
2. Connect to the new site’s URL. This line matters: Invoke-PnPSiteTemplate applies to whatever site you’re connected to.
3. Run Invoke-PnPSiteTemplate with the .pnp path.
4. Count the items in both lists.

# 1. Create the empty target site (replace yourtenant with your tenant name)
Connect-PnPOnline -Url "https://yourtenant.sharepoint.com/sites/SPGuides" -DeviceLogin -PersistLogin
$newSite = New-PnPSite -Type CommunicationSite -Title "SPGuides Project Alpha" `
    -Url "https://yourtenant.sharepoint.com/sites/SPGuidesProjectAlpha" -SiteDesign Blank -Wait
"Created: $newSite"

# 2. Connect to the new site and apply the template
Connect-PnPOnline -Url $newSite -DeviceLogin -PersistLogin
Invoke-PnPSiteTemplate -Path "C:\SPGuidesDemo\Templates\ProjectSiteTemplate.pnp"

# 3. Check the result
Get-PnPList | Where-Object Title -like "Project*" | Select-Object Title, ItemCount

Project Tasks arrived with all four tasks. Project Documents arrived with Document Type and Review Date, but no files. That’s expected: the Lists handler exports list structure and data rows, not library documents.

If new projects also need starter documents, upload them after the apply step. My guide to upload files to a SharePoint document library using PnP PowerShell has a ready loop for a whole folder, and you can pull the originals off the model site with a script to download all files from a document library.

Checkpoint: The output shows Created: https://yourtenant.sharepoint.com/sites/SPGuidesProjectAlpha, Project Documents 0 items and Project Tasks 4 items.

Test the Template: Apply It Twice to the Same Site

Real templates get re-applied: someone adds a column to the model, and you push the update to existing sites. So let’s run the exact same Invoke against Alpha a second time.

# Replace yourtenant with your tenant name
Connect-PnPOnline -Url "https://yourtenant.sharepoint.com/sites/SPGuidesProjectAlpha" -DeviceLogin -PersistLogin

# Apply the same template a second time
Invoke-PnPSiteTemplate -Path "C:\SPGuidesDemo\Templates\ProjectSiteTemplate.pnp"

Get-PnPList | Where-Object Title -like "Project*" | Select-Object Title, ItemCount

The lists and columns were fine, because the engine skips what already exists. The data rows weren’t: Project Tasks went from 4 to 8 items, with every task twice. With an empty KeyColumn, the engine has no way to tell that a row is already there, so it adds it again.

Important: never re-apply a template that has data rows to a live site until you’ve set a key column, or every run adds another copy of the starter tasks.

Stop Duplicate Rows With KeyColumn and UpdateBehavior

Same template, one change: tell the data rows which column identifies a row. I removed the four extra tasks first, then ran this:

1. Load the .pnp file with Read-PnPSiteTemplate.
2. Find the Project Tasks list in $template.Lists.
3. Set DataRows.KeyColumn to Title and DataRows.UpdateBehavior to Overwrite.
4. Write it back with Save-PnPSiteTemplate, then apply it again.

$path = "C:\SPGuidesDemo\Templates\ProjectSiteTemplate.pnp"

# Tell the engine how to recognize a row that already exists
$template = Read-PnPSiteTemplate -Path $path
$tasks = $template.Lists | Where-Object Title -eq "Project Tasks"
$tasks.DataRows.KeyColumn = "Title"            # match rows on the Title column
$tasks.DataRows.UpdateBehavior = "Overwrite"   # update the match instead of adding a copy
Save-PnPSiteTemplate -Template $template -Out $path -Force

# Apply it again to the same site: still 4 tasks, no duplicates (replace yourtenant)
Connect-PnPOnline -Url "https://yourtenant.sharepoint.com/sites/SPGuidesProjectAlpha" -DeviceLogin -PersistLogin
Invoke-PnPSiteTemplate -Path $path
Get-PnPList | Where-Object Title -like "Project*" | Select-Object Title, ItemCount

Now the engine matches each row on Title. Overwrite means a match gets updated, not copied.

In my re-apply, the existing tasks took the Due Date values from the template, and no copies were added. Pick a column whose values are unique in that list. If you ever need to clean up duplicates by hand, see how to delete all items from a SharePoint list using PnP PowerShell.

Checkpoint: After the second apply, Project Tasks still has 4 items.

Make It Reusable: One Command per New Project Site

Typing three commands for every project gets old. Wrap them in a function that takes the project name, builds the URL, creates the site, applies the template and reports back:

1. Paste the function into your session (or a .ps1 file you dot-source).
2. Call it with -ProjectName "Beta".
3. Read the summary it prints.

function New-SPGuidesProjectSite {
    param(
        [Parameter(Mandatory)] [string] $ProjectName,   # e.g. "Beta"
        [string] $TemplatePath = "C:\SPGuidesDemo\Templates\ProjectSiteTemplate.pnp",
        [string] $Tenant = "https://yourtenant.sharepoint.com"   # replace yourtenant
    )
    $url = "$Tenant/sites/SPGuidesProject$ProjectName"

    Connect-PnPOnline -Url "$Tenant/sites/SPGuides" -DeviceLogin -PersistLogin
    $site = New-PnPSite -Type CommunicationSite -Title "SPGuides Project $ProjectName" `
        -Url $url -SiteDesign Blank -Wait

    Connect-PnPOnline -Url $site -DeviceLogin -PersistLogin
    Invoke-PnPSiteTemplate -Path $TemplatePath

    $lists = Get-PnPList | Where-Object Title -like "Project*"
    [pscustomobject]@{ Site = $site; Lists = ($lists.Title -join ", "); Tasks = ($lists | Where-Object Title -eq "Project Tasks").ItemCount }
}

New-SPGuidesProjectSite -ProjectName "Beta" | Format-List

That one call created /sites/SPGuidesProjectBeta with Project Documents and Project Tasks and the 4 starter tasks. To check later which sites you’ve created this way, list them with the script that shows how to get all SharePoint Online sites using PnP PowerShell.

Invoke-PnPSiteTemplate Options Worth Knowing

Our build only needed -Path, but these switches cover most of what people ask about. The cheat sheet of SharePoint PowerShell commands for SPO and PnP lists the related cmdlets.

Parameters let one template serve many projects. Put a token in the XML, then pass the value when you apply it:

# In the template XML, a value can be a token such as {parameter:ProjectName}
Invoke-PnPSiteTemplate -Path "C:\SPGuidesDemo\Templates\ProjectSiteTemplate.xml" -Parameters @{"ProjectName" = "Alpha"}

What a PnP Site Template Copies (and What It Doesn’t)

From the tests above and the docs, here’s the short version. If you only need to move one list between sites, the copy items from one list to another with PnP PowerShell approach is lighter than a template.

That last row is the big one. A site template applies to an existing site. A tenant template can also create site collections through a Sequence and is applied with Invoke-PnPTenantTemplate, which is the route for provisioning many sites from one file.

Make It Production-Ready

• Keep the template in source control. The .xml diff shows exactly what changed between versions.
• Set a KeyColumn on every list with data rows before anyone re-applies the template.
• Check the connection before every apply. Print (Get-PnPWeb).Url; a script that checks whether a site or list exists first is safer still.
• Test on a throwaway site. Apply to a new test site, check the lists, then delete it.
• Name sites consistently (SPGuidesProject + name), so the function builds predictable URLs.

Troubleshooting

These are the problems I actually hit while building this, with the fix for each:

• “Default authentication request failed. Please specify the -Tenant parameter”: Connect-PnPOnline -DeviceLogin couldn’t work out the tenant. Add -Tenant yourtenant.onmicrosoft.com and it connects.
• The template went to the wrong site: when a Connect-PnPOnline call fails, the PREVIOUS connection stays active, so the next Invoke runs against the old site. Always check (Get-PnPWeb).Url before applying.
• Due dates one day early: “2026-11-02” is stored as midnight UTC, which a US time-zone site shows as 11/1/2026. Write “2026-11-02T12:00:00Z” (noon UTC) instead.
• New-PnPSite seems frozen: with -Wait it can take more than 90 seconds. Let it finish; don’t start the apply step early.
• Duplicate list items after re-applying: set DataRows.KeyColumn and UpdateBehavior Overwrite (see above).
• Library arrives empty: templates don’t carry documents. Upload the files after applying.

Note: if Connect-PnPOnline still fails after adding -Tenant, go back to the app registration from Step 2. The app needs consent before anyone can sign in through it.

Where to Take It Next

• Add a document library structure: extend the model with folders using the steps to create a document library with folders using PnP PowerShell, then export again.
• Let site owners apply it themselves: for a no-PowerShell option, rebuild the lists as a site design (linked above), and browse the SharePoint tutorials hub for the site setup guides around it.
• Clean up test sites: remove the throwaway sites you created while testing with the script to delete a SharePoint Online site using PowerShell.

If you’re automating more of your SharePoint setup, these PnP PowerShell guides pair well with this one:

• PnP PowerShell Scripts for SharePoint Developers
• How to Get All Lists and Libraries from a SharePoint Online Site Using PnP PowerShell
• How to Get a SharePoint List GUID Using PowerShell (PnP and Get-SPWeb)
• How to Get SharePoint Site Members Using PowerShell (PnP and SPO)

Frequently Asked Questions