Uploading Files to a Document Library using PnP PowerShell

Uploading files to a SharePoint Online Document Library is a common requirement for automating document management. Using PnP PowerShell, you can upload files individually or in bulk, set metadata, and manage file versions efficiently.

What You’ll Learn:

✔️ How to connect to SharePoint Online
✔️ How to upload a single file
✔️ How to upload multiple files
✔️ How to set metadata for uploaded files
✔️ How to check if a file exists before uploading
✔️ How to handle errors and versioning

Prerequisites

Before proceeding, ensure that:
PnP PowerShell is installed
You have the necessary SharePoint permissions
You have the SharePoint site URL
You have a local file or folder to upload

Step 1: Install and Import PnP PowerShell

If you haven’t installed PnP PowerShell, install it using:

Install-Module -Name PnP.PowerShell -Scope CurrentUser -AllowClobber -Force

Then, import the module:

Import-Module PnP.PowerShell

PnP PowerShell is ready!

Step 2: Connect to SharePoint Online

Before uploading files, connect to your SharePoint site:

# Connect to SharePoint Online
Connect-PnPOnline -Url "https://yourtenant.sharepoint.com/sites/yoursite" -Interactive

🔹 Replace "yourtenant" with your tenant name
🔹 Replace "yoursite" with the site name

Connected successfully!

Step 3: Upload a Single File to a Document Library

To upload a single file to a specific document library, use the following script:

# Define variables
$libraryName = "Project Documents"
$localFilePath = "C:\Users\YourName\Documents\report.pdf"
$serverRelativePath = "/sites/yoursite/Shared Documents/report.pdf"

# Upload the file
Add-PnPFile -Path $localFilePath -Folder $libraryName

Write-Host "File uploaded successfully to $libraryName"

Replace:

"Project Documents" with your document library name
"C:\Users\YourName\Documents\report.pdf" with the file path
"Shared Documents" with the actual library folder

Single file uploaded successfully!

Step 4: Upload Multiple Files to a Document Library

To upload all files from a folder, use:

# Define variables
$libraryName = "Project Documents"
$localFolderPath = "C:\Users\YourName\Documents\UploadFolder"

# Upload all files in the folder
Get-ChildItem -Path $localFolderPath -File | ForEach-Object {
    Add-PnPFile -Path $_.FullName -Folder $libraryName
    Write-Host "Uploaded: $($_.Name)"
}

This script loops through all files in the specified folder and uploads them.

Multiple files uploaded successfully!

Step 5: Set Metadata for Uploaded Files

After uploading, you can update metadata such as Title, Category, or Custom Columns:

# Define metadata values
$libraryName = "Project Documents"
$fileName = "report.pdf"
$metadata = @{
    "Title" = "Annual Report"
    "Category" = "Finance"
}

# Update metadata
Set-PnPListItem -List $libraryName -Identity $fileName -Values $metadata

Write-Host "Metadata updated for $fileName"

Replace:

"Title" and "Category" with your SharePoint column names
"Annual Report" and "Finance" with metadata values

Metadata updated successfully!

Step 6: Check If a File Exists Before Uploading

To avoid overwriting existing files, check if a file exists:

# Define variables
$libraryName = "Project Documents"
$filePath = "C:\Users\YourName\Documents\report.pdf"
$fileName = "report.pdf"

# Check if file exists
$fileExists = Get-PnPListItem -List $libraryName | Where-Object { $_.FieldValues.FileLeafRef -eq $fileName }

if ($fileExists) {
    Write-Host "File '$fileName' already exists. Skipping upload."
} else {
    Add-PnPFile -Path $filePath -Folder $libraryName
    Write-Host "File uploaded successfully."
}

File existence check implemented!

Step 7: Handle Versioning While Uploading

If versioning is enabled, you can overwrite existing files:

# Upload and overwrite existing file
Add-PnPFile -Path "C:\Users\YourName\Documents\report.pdf" -Folder "Project Documents" -Overwrite

🔹 If a file already exists, this will replace it with the new version.

Versioning handled successfully!

Step 8: Verify Uploaded Files in SharePoint

To list all files in the document library, use:

# Get all files in the library
Get-PnPListItem -List "Project Documents" | Select-Object FieldValues.FileLeafRef

File verification successful!

Step 9: Delete an Uploaded File (If Needed)

If you need to remove a file, use:

# Define variables
$libraryName = "Project Documents"
$fileName = "report.pdf"

# Remove file
Remove-PnPFile -ServerRelativeUrl "/sites/yoursite/Shared Documents/$fileName" -Force

Write-Host "File '$fileName' deleted successfully!"

File deleted successfully!

Common Errors & Solutions

Error	Cause	Solution
`Access Denied`	Insufficient permissions	Ensure you have Contribute or Full Control rights
`Cannot find library`	Incorrect library name	Use `Get-PnPList` to verify the name
`File already exists`	Uploading a duplicate file	Use `-Overwrite` to replace existing files