Upload Single or Multiple Files to SharePoint with Metadata Using PnP PowerShell

While working with SharePoint document libraries, we often need to upload files to the library. We can achieve this either by using the Upload option in the command bar or by dragging and dropping. At the same time, we can also upload multiple files. Even though this approach is simple, we may sometimes need to upload files to the SharePoint library automatically or need to update the metadata of those files automatically.

So in those cases, we can follow the programmatic approach. With this approach, we can upload a single file, multiple files, or even update the metadata of a file while uploading, and avoid uploading if the file already exists.

In this article, I will explain how to upload files to a SharePoint document library using PnP PowerShell with various examples.

Upload a Single File to SharePoint Library Using PnP PowerShell

In this section, we will see how to upload a single file to a SharePoint library using PnP PowerShell. Make sure you have “Contribute” permissions to the document library.

The Add-PnPFile cmdlet in PowerShell allows us to upload the file to a document library. So, let’s first understand the syntax of this command:

Add-PnPFile -Path <String> -Folder <FolderPipeBind> 
[-Values <Hashtable>]
[-NewFileName <String>] 
[-ContentType <ContentTypePipeBind>] 

Here:

• -Path = Provide the local file path.
• -Folder = Provide the destination folder path in the SharePoint Online site.
• -Values = Used to update the field values while uploading files to the library. Provide the internal names of the fields. For exe:  -Values @{“StartDate” = “20/01/2025”}
• -NewFileName = Provide file name, if needed.
• -ContentType = Assign a content type to the file.

To upload a single file from your local system to the SharePoint library, run the PnP PowerShell script below in VSCode or any other platform. Once it runs, you can see the uploaded file name, type, size, and last modified date in the Terminal pane.

$SiteURL = "https://<tenant_name>.sharepoint.com/sites/EmployeeManagementTeam"
$ClientID = "z0323-scas-ab35ed3d-gysrt"
$LocalFilePath ="D:\ExpenseDocuments\ExpenseReport_1.pdf"
$LibraryPath= "ExpenseDocuments" 

Connect-PnPOnline -Url $SiteURL -ClientId $ClientID -Interactive
Add-PnPFile -Path $LocalFilePath -Folder $LibraryPath

Here,

• $SiteURL = Provide your SharePoint site url.
• $ClientID = Provide your Microsoft Entra application (client) ID.
• $LocalFilePath = Provide the local file path where your file is present.
• $LibraryPath = Provide the destination path, where you want to upload the file.
• Connect-PnPOnline = Used to connect with the SharePoint site.

In the image below, you can see that the file was uploaded successfully to the specified document library.

Check out Enable Item-level Permissions in a SharePoint Document Library Using PowerShell

Upload File to SharePoint Library with Metadata Using PnP PowerShell

Let’s see how to upload a file to a SharePoint document library with metadata using PnP PowerShell. In the image below, you can see a file uploaded along with metadata, expense type, status, and the updated modified date.

To achieve this, run the code below by updating the variables with your actual values.

$SiteURL = "https://<tenant name>.sharepoint.com/sites/EmployeeManagementTeam"
$ClientID = "z0323-scas-ab35ed3d-gysrt"
$LocalFilePath ="D:\ExpenseDocuments\ExpenseReport_2.pdf"
$LibraryPath = "ExpenseDocuments" 

Connect-PnPOnline -Url $SiteURL -ClientId $ClientID  -Interactive
Add-PnPFile -Path $LocalFilePath -Folder $LibraryPath -Values @{Modified="12/28/2023"; ExpenseType="Travel"; Status="Approved"} 

Once it runs successfully, you can see the uploaded file name along with the modified date.

This way, we can upload a file to the document library along with metadata. In the section below, we will see how to upload multiple files to the document library.

Upload Multiple Files to SharePoint Online Using PnP PowerShell

When we need to automatically upload hundreds or more files to a SharePoint document library, using PnP PowerShell, we can easily achieve this; the running time will depend on the number of files present in the local system.

To illustrate, I stored PDF files on the local system. After running the PnP PowerShell script, the files are uploaded to the document library as shown in the image below.

Here is the script to upload multiple files along with metadata.

$SiteURL = "https://<tenant name>.sharepoint.com/sites/EmployeeManagementTeam"
$ClientID = "z0323-scas-ab35ed3d-gysrt"
$LocalFolderPath = "D:\ExpenseDocuments"
$LibraryPath = "ExpenseDocuments"
Connect-PnPOnline -Url $SiteURL -ClientId $ClientID -Interactive

$Files = Get-ChildItem -Path $LocalFolderPath -Force -Recurse
if ($Files.Count -eq 0) {
    Write-Host "No files found in $LocalFolderPath"
    return
}
foreach ($File in $Files) {
    Write-Host "LocalFile path: $($File.Directory)\$($File.Name)"
    Add-PnPFile -Path "$($File.Directory)\$($File.Name)" -Folder $LibraryPath -Values @{ExpenseType="Travel"; Status="Approved"} 
}

Here:

• The Get-ChildItem command retrieves all files from the local folder path and stores them in $Files.
• If there are no files present in the specified local path, a message will display in the terminal pane.
• Then, using the foreach loop, we are fetching each file and uploading it to the document library using the Add-PnPFile cmd.

This way, we can upload multiple files to the document library using PnP PowerShell. While performing this action, it replaces the existing files with new ones.

If you prefer not to replace the existing file, follow the section below for instructions on how to achieve this.

Check out Get All Microsoft 365 Group Connected SharePoint Sites using PowerShell

Check File Exists Before Uploading to SharePoint Library Using PnP PowerShell

To verify if the file to be uploaded already exists in the SharePoint document library, we need to compare our file name with the existing files in the library.

For this purpose, we utilize the Get-PnPFolderItem cmd to retrieve all specified folder items. Then, we apply a filter to fetch the files only if the file name matches the uploaded file name. If it exists, the process will stop uploading; otherwise, it will proceed with the upload.

$SiteURL = "https://<tenant-name>.sharepoint.com/sites/EmployeeManagementTeam"
$ClientID = "z0323-scas-ab35ed3d-gysrt"
$LocalFilePath = "D:\ExpenseDocuments\ExpenseReport_2.pdf"
$LibraryPath = "ExpenseDocuments"
$FileName = [System.IO.Path]::GetFileName($LocalFilePath)
Connect-PnPOnline -Url $SiteURL -ClientId $ClientID -Interactive
$FileExists = Get-PnPFolderItem -FolderSiteRelativeUrl $LibraryPath -ItemType File | Where-Object { $_.Name -eq $FileName }

if ($FileExists) {
    Write-Host "File '$FileName' already exists in '$LibraryPath'." -ForegroundColor Yellow
}
else {
    Write-Host "Uploading file: $FileName"
    Add-PnPFile -Path $LocalFilePath -Folder $LibraryPath -Values @{ExpenseType="Travel"; Status="Approved"}
}

In the image below, you can see that I tried to upload a file that already exists in the document library. In the Terminal pane, it displays the message “File ‘ExpenseReport_2.pdf’ already exists in ‘ExpenseDocuments’.”

This way, we can easily avoid overriding the existing file with a new file while uploading using PnP powershell.

I hope you found this article helpful! Here, I have explained four different examples of uploading files to SharePoint document libraries using PnP PowerShell. If you need to upload single or multiple files automatically or update metadata during the upload process, this article will assist you.

Also, you may like:

• How to Add SharePoint Online List Items Using PowerShell?
• How to Get All SharePoint Site Collections Using PowerShell?
• How to Add SharePoint Online List Items Using PowerShell?

Bijay Kumar

After working for more than 18 years in Microsoft technologies like SharePoint, Microsoft 365, and Power Platform (Power Apps, Power Automate, and Power BI), I thought will share my SharePoint expertise knowledge with the world. Our audiences are from the United States, Canada, the United Kingdom, Australia, New Zealand, etc. For my expertise knowledge and SharePoint tutorials, Microsoft has been awarded a Microsoft SharePoint MVP (12 times). I have also worked in companies like HP, TCS, KPIT, etc.