Skip to content

Resets the permissions on every item in a SharePoint document library

Jump to bottom
directorcia edited this page Apr 10, 2026 · 1 revision

spo-doclib-reset.ps1

Resets the permissions on every item in a SharePoint document library so that each item inherits its permissions from the library rather than having unique (broken) permissions set directly on it.

Prerequisites

Requirement Detail
PowerShell version 7 or later
Module PnP PowerShell (PnP.PowerShell)
Active connection Must already be connected to the target SharePoint site via PnP before running this script. Use o365-connect-pnp.ps1 to establish the connection.

Parameters

Parameter Type Default Description
-debug Switch $false When set, enables transcript logging. All console output is written to ..\spo-doclib-reset.txt in the parent directory. The log file is overwritten on each run.
-prompt Switch $false When set, prompts the user to confirm before any permissions are changed. The script will not proceed until Y or N is entered.

Execution Flow

1. Initialisation

  • Parameters are evaluated and console message colours are assigned (cyan = system, green = process, red = error, yellow = warning).
  • The console is cleared.
  • If -debug is set, a transcript is started at ..\spo-doclib-reset.txt.
  • The active parameter values are printed to the console.

2. Retrieve Site Lists

$lists = Get-PnPList
  • Calls Get-PnPList to retrieve all lists and libraries from the currently connected SharePoint site.
  • If this call fails (e.g. no active PnP connection), error code [001] is displayed, the transcript is stopped (if active), and the script exits with exit code 1.

3. Select a List

  • The retrieved lists are piped through Select-Object (Title, Id), sorted alphabetically by Title, and presented in a graphical grid view (Out-GridView) with single-selection mode.
  • The operator clicks a row and presses OK to confirm their selection.
  • If the grid view is closed without a selection (e.g. clicking Cancel or pressing Escape), a warning is displayed and the script exits with exit code 0.

4. Read All Items

$items = (Get-PnPListItem -List $selectedList.id -pagesize 5000 -Fields "Title","GUID","FileRef").FieldValues
  • Reads all items from the selected list in pages of up to 5,000 items at a time.
  • The fields Title, GUID, and FileRef (the server-relative file path) are fetched for each item.
  • The total item count is printed to the console.
  • This step can take considerable time for large libraries.

5. Confirmation Prompt (optional)

  • Only executed when -prompt is set.
  • The operator is asked Are you sure [Y/N] in a loop until a non-empty response is given.
  • Entering N or n stops the script immediately with exit code 2 (transcript stopped if active).
  • Any other non-empty response (including Y or y) continues execution.

6. Reset Permissions

Set-PnPListItemPermission -List $selectedList.id -Identity $item.ID -InheritPermissions
  • Iterates over every item retrieved in step 4.
  • For each item, the current progress ([n of total]), item ID, and file path are printed.
  • Set-PnPListItemPermission -InheritPermissions removes any unique permissions on the item and restores inheritance from the parent library.
  • A per-item Success or Failed result is printed. Failures display the exception message but do not stop the loop — all remaining items continue to be processed.

7. Completion

  • A completion message is printed.
  • If -debug is set, the transcript is stopped.

Exit Codes

Code Meaning
0 Normal exit — no list was selected in the grid view, or the script completed successfully.
1 Failed to retrieve site lists (no active PnP connection or insufficient permissions).
2 Operator chose not to proceed at the confirmation prompt (-prompt mode).

Output Colours

Colour Usage
Cyan Start and completion banners
Green Progress and informational messages
Yellow Warnings (e.g. no list selected)
Red Errors and failure details

Examples

Basic run (no logging, no confirmation):

.\spo-doclib-reset.ps1

Run with transcript logging enabled:

.\spo-doclib-reset.ps1 -debug

Run with confirmation prompt before making changes:

.\spo-doclib-reset.ps1 -prompt

Run with both logging and confirmation:

.\spo-doclib-reset.ps1 -debug -prompt

Notes

  • The script requires an active PnP connection to the target site before it is run. It does not connect itself.
  • The transcript log (..\spo-doclib-reset.txt) is written to the parent directory of wherever the script is located, and is overwritten on each run — it does not accumulate across runs.
  • Individual item failures are reported and skipped; the script does not abort mid-run on item-level errors.
  • The page size for item retrieval is fixed at 5,000. For libraries with more than 5,000 items, Get-PnPListItem will make multiple requests automatically.

Script provided as is. Use at own risk. No guarantees or warranty provided.
Source: https://github.com/directorcia/patron/blob/master/spo-doclib-reset.ps1

Clone this wiki locally