Live training: next batches coming soon. Join the waitlist:Waitlists open:Developer Training →Developer →Copilot Studio Training →Copilot Studio →

How to Move Files in SharePoint Online with PowerShell (PnP)

Dragging documents between SharePoint folders is fine for five files. It’s painful for 500, or for a cleanup that has to run every Friday.

To move files in SharePoint Online with PowerShell, connect with PnP PowerShell and run Move-PnPFile with the file’s path and the destination folder, library or site.

In this tutorial, we’ll cover the move files sharepoint powershell scripts I tested: one file, an existing target, a bulk loop, another library, another site, a whole folder, and Windows PowerShell 5.1.

Here’s the shortest working version once the module is installed:

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

Move-PnPFile -SourceUrl "SPGuidesProjects/Incoming/Q4-Sales-Summary.csv" -TargetUrl "SPGuidesProjects/Q4 2026 Reports" -Force

It moves Q4-Sales-Summary.csv from the Incoming folder into the Q4 2026 Reports folder. On success, Move-PnPFile prints nothing at all.

What you need before you move files

You need the PnP.PowerShell module, your own Entra ID app registration, and Edit permission on both the source and the target. I covered the install and app registration in my post on creating a folder in SharePoint with PowerShell.

Since September 9, 2024, PnP PowerShell has no shared sign-in app, so -ClientId must be your own app’s client ID. Current versions also need PowerShell 7.4 or later.

I ran every script here on 10/25/2026 with PowerShell 7.6.7 and PnP.PowerShell 3.3.0. This script connects and lists what’s waiting in the Incoming folder of my SPGuides Projects library (URL name SPGuidesProjects):

$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

# What's waiting in the Incoming folder?
Get-PnPFolderItem -FolderSiteRelativeUrl "SPGuidesProjects/Incoming" -ItemType File |
    Select-Object Name, Length, TimeLastModified | Format-Table -AutoSize
PowerShell 7 connecting with Connect-PnPOnline and listing five files in the SPGuidesProjects Incoming folder

Five files came back: three invoices, meeting notes and a sales summary. TimeLastModified is shown in UTC. For other sign-in options, see connecting to SharePoint Online with PowerShell.

If the cmdlet isn’t recognized, the module didn’t load in that window; here’s how to fix Connect-PnPOnline is not recognized.

Move-PnPFile syntax and parameters

Move-PnPFile takes a source and a target, plus a few switches that decide what happens when something gets in the way:

ParameterWhat it does
-SourceUrlSite- or server-relative path of the file (or folder) to move, including the file name
-TargetUrlSite- or server-relative destination: a library, a folder, or a full new file path
-OverwriteReplaces a file that already exists at the target
-AllowSchemaMismatchLets the move finish when the destination library has different columns
-AllowSmallerVersionLimitOnDestinationAllows a target library that keeps fewer versions
-IgnoreVersionHistoryMoves only the latest version
-NoWaitReturns a job right away; check it with Receive-PnPCopyMoveJobStatus
-ForceSkips the confirmation prompt

Paths use the library’s URL name, not its display name. The default Documents library is Shared Documents in a path.

How do I move a single file to another folder?

Point -TargetUrl at the destination folder. The PnP docs mostly show a library or a full file name as the target, but a folder path works too, and the file keeps its name:

# Move one file: TargetUrl can be the destination folder (the file keeps its name)
Move-PnPFile -SourceUrl "SPGuidesProjects/Incoming/Q4-Sales-Summary.csv" `
             -TargetUrl "SPGuidesProjects/Q4 2026 Reports" -Force

Get-PnPFile -Url "SPGuidesProjects/Q4 2026 Reports/Q4-Sales-Summary.csv" -AsListItem |
    ForEach-Object { "Now at: " + $_.FieldValues.FileRef }
$left = Get-PnPFile -Url "SPGuidesProjects/Incoming/Q4-Sales-Summary.csv" -ErrorAction SilentlyContinue
"Still in Incoming? " + [bool]$left
Move-PnPFile moving Q4-Sales-Summary.csv from Incoming to the Q4 2026 Reports folder with the new path confirmed

The two check lines confirm the file arrived and left the source:

Now at: /sites/SPGuides/SPGuidesProjects/Q4 2026 Reports/Q4-Sales-Summary.csv
Still in Incoming? False

To rename while moving, end the target with a new file name instead, such as "SPGuidesProjects/Q4 2026 Reports/Q4-Summary-Final.csv".

What happens if the file already exists at the target?

This one surprised me. When the destination already has a file with the same name, Move-PnPFile doesn’t throw an error, even with -ErrorAction Stop. It returns a job error object, and the source file stays put.

I dropped a fresh copy into Incoming and ran the same move again, then repeated it with -Overwrite:

# Run the same move again after a new copy lands in Incoming
Add-PnPFile -Path ".\samples\Q4-Sales-Summary.csv" -Folder "SPGuidesProjects/Incoming" | Out-Null

$result = Move-PnPFile -SourceUrl "SPGuidesProjects/Incoming/Q4-Sales-Summary.csv" `
                       -TargetUrl "SPGuidesProjects/Q4 2026 Reports" -Force
$result | Format-List   # no exception: the cmdlet returns the failure as output

# Replace the file that's already there
Move-PnPFile -SourceUrl "SPGuidesProjects/Incoming/Q4-Sales-Summary.csv" `
             -TargetUrl "SPGuidesProjects/Q4 2026 Reports" -Overwrite -Force
"Moved with -Overwrite"
Move-PnPFile returning a JobError object that says the file already exists at the destination, then the move with -Overwrite

The returned object held the real reason (trimmed to the useful lines):

Event              : JobError
MigrationDirection : MoveCleanup
ObjectType         : File
Url                : SPGuidesProjects/Incoming/Q4-Sales-Summary.csv
ErrorCode          : -2147024713
Message            : A file or folder with the name 'Q4-Sales-Summary.csv' already exists at the destination.

The second command, with -Overwrite, replaced the existing file and printed Moved with -Overwrite.

So in scripts, don’t rely on try/catch for this case. Capture the output and check it, or test the target first as shown in checking if a file or folder exists in SharePoint:

$result = Move-PnPFile -SourceUrl $src -TargetUrl $dst -Force
if ($result -and $result.Event -eq "JobError") {
    Write-Warning "Not moved: $($result.Message)"
}

Move multiple files from one folder to another

For bulk moves, list the folder with Get-PnPFolderItem, filter the files you want, and move each one. This loop moves every invoice from Incoming to the Finance 2026 folder:

$source = "SPGuidesProjects/Incoming"
$target = "SPGuidesProjects/Departments/Finance/2026"

$files = Get-PnPFolderItem -FolderSiteRelativeUrl $source -ItemType File |
    Where-Object Name -like "Invoice-*"

foreach ($file in $files) {
    Move-PnPFile -SourceUrl "$source/$($file.Name)" -TargetUrl $target -Force
    "Moved $($file.Name)"
}
"{0} invoices moved to $target" -f $files.Count
PowerShell loop moving three Invoice files from Incoming to Departments/Finance/2026 with Move-PnPFile

It printed one Moved line per invoice and 3 invoices moved to SPGuidesProjects/Departments/Finance/2026. Drop the Where-Object line to move every file in the folder.

In the browser, Finance > 2026 now shows the three invoices, modified about a minute earlier:

SPGuides Projects library Finance 2026 folder showing the three invoice files moved with PowerShell

The target folder must exist first. If it doesn’t, create it with Resolve-PnPFolder, or upload files with PnP PowerShell straight into the right path next time.

Move a file to another document library

For a different library on the same site, set -TargetUrl to that library’s URL name. Here the meeting notes go to the Project Documents library:

# Another library on the same site: point TargetUrl at the library's URL
Move-PnPFile -SourceUrl "SPGuidesProjects/Incoming/Meeting-Notes-2026-10-20.txt" `
             -TargetUrl "Project Documents" -Force

$item = Get-PnPFile -Url "Project Documents/Meeting-Notes-2026-10-20.txt" -AsListItem
"Item ID     : " + $item.Id
"File        : " + $item.FieldValues.FileRef
"Modified by : " + $item.FieldValues.Editor.LookupValue
Move-PnPFile moving the meeting notes file to the Project Documents library and showing its new item ID 6

The file got a new list item (ID 6) in Project Documents, and Modified By shows Bijay Kumar, the account that ran the move. If you’re unsure of a library’s URL name, list all libraries with PnP PowerShell first.

Move files to another SharePoint site

For another site, use the server-relative URL of the target library, starting with /sites/. You stay connected to the source site:

# Another site: use the server-relative URL of the target library
$src = "Project Documents/Meeting-Notes-2026-10-20.txt"
$dst = "/sites/SPGuidesIntranet/Shared Documents"

try {
    Move-PnPFile -SourceUrl $src -TargetUrl $dst -Force -ErrorAction Stop
} catch {
    "First try failed: " + $_.Exception.Message
}

Move-PnPFile -SourceUrl $src -TargetUrl $dst -AllowSchemaMismatch -Force
"Moved with -AllowSchemaMismatch"
Cross-site Move-PnPFile failing on the TaxKeyword field definition, then succeeding with -AllowSchemaMismatch

The first try failed with an SPMigrationQosException: Missing or mismatched field definition on the destination list for source field ‘TaxKeyword’. Project Documents has an Enterprise Keywords column that the intranet library doesn’t have.

Unlike the already-exists case, this error does throw, so try/catch caught it. Adding -AllowSchemaMismatch moved the file, but values in columns the target lacks don’t come along.

The same cross-site move from SPGuides Projects, which has no extra columns, worked without the switch. Microsoft limits one cross-site move or copy to 100 GB and 30,000 files.

Move a whole folder with Move-PnPFolder

To move a folder with everything in it, use Move-PnPFolder. -TargetFolder is the new parent, not the new full path:

# Move a whole folder (with its files) into another folder
Move-PnPFolder -Folder "SPGuidesProjects/Incoming/Scans" `
               -TargetFolder "SPGuidesProjects/Archive 2025"

$moved = Get-PnPFolder -Url "SPGuidesProjects/Archive 2025/Scans"
"Folder now at: " + $moved.ServerRelativeUrl

Get-PnPFolderItem -FolderSiteRelativeUrl "SPGuidesProjects/Archive 2025/Scans" -ItemType File |
    ForEach-Object { "  File inside: " + $_.Name }
Move-PnPFolder moving the Scans folder and its file into the Archive 2025 folder

The cmdlet returned the Scans folder with one item, and the check printed Folder now at: /sites/SPGuides/SPGuidesProjects/Archive 2025/Scans with Scan-0001.txt inside.

Move-PnPFolder only works within the current site. For another site, pass the folder path to Move-PnPFile instead. To remove a folder once it’s empty, see deleting a folder in SharePoint with PowerShell.

Move files in Windows PowerShell 5.1

PnP.PowerShell 3.x won’t load in Windows PowerShell 5.1. The last version that runs there is 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

Move-PnPFile has the same parameters in 1.12.0, so the script is unchanged:

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

Move-PnPFile -SourceUrl "SPGuidesProjects/Incoming/Q4-Sales-Summary.csv" `
             -TargetUrl "SPGuidesProjects/Q4 2026 Reports" -Force

Get-PnPFolderItem -FolderSiteRelativeUrl "SPGuidesProjects/Q4 2026 Reports" -ItemType File |
    ForEach-Object Name
Windows PowerShell 5.1 with PnP.PowerShell 1.12.0 moving Q4-Sales-Summary.csv into the Q4 2026 Reports folder

The output confirmed PowerShell 5.1.26100.9444 with PnP.PowerShell 1.12.0, and Q4 2026 Reports listed Q4-Sales-Summary.csv. Version 1.12.0 no longer gets updates, so plan the move to PowerShell 7.

Common errors and fixes

  • “A file or folder with the name … already exists at the destination”: returned as an object, not thrown. Add -Overwrite or check the output.
  • “Missing or mismatched field definition”: the target library lacks a source column. Add the column there, or use -AllowSchemaMismatch.
  • File not found: check the library’s URL name and the exact file name, including the extension.
  • Connect-PnPOnline asks for a ClientId, or 5.1 asks for -Tenant: register your own Entra app, and add -Tenant with 1.12.0.

A moved file keeps its version history by default. If a move went to the wrong place, run it back the other way, and clean up test files with -Recycle so they land in the SharePoint recycle bin.

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

Prefer no code? You can move files from OneDrive to SharePoint with Power Automate or copy files with Power Automate instead.

Once your files are where they belong, these PowerShell tutorials cover the next jobs:

Frequently Asked Questions

How do I move files from one folder to another in SharePoint using PowerShell?

Connect with Connect-PnPOnline, then run Move-PnPFile -SourceUrl “Library/Folder/file.docx” -TargetUrl “Library/OtherFolder” -Force. The target can be a folder; the file keeps its name.

Does Move-PnPFile keep metadata and version history?

Yes, by default the move keeps version history and column values. The Move-PnPFile reference lists -IgnoreVersionHistory to move only the latest version, and -AllowSchemaMismatch drops values the target library can’t hold.

Why didn’t Move-PnPFile move my file, with no error?

The target already has a file with that name. Move-PnPFile returns a JobError object instead of throwing, and the source stays put. Add -Overwrite or check the returned object’s Message.

Can I move files between SharePoint sites with PowerShell?

Yes. Use Move-PnPFile with a server-relative target such as /sites/OtherSite/Shared Documents. Microsoft’s SharePoint limits page caps one cross-site move at 100 GB and 30,000 files.

How do I move a folder in SharePoint with PowerShell?

Use Move-PnPFolder -Folder “Library/Folder” -TargetFolder “Library/NewParent” within the same site. For another site, pass the folder path to Move-PnPFile.