Document PSContentPath Feature in PowerShell

[jshigetomi]

Prerequisites

• Existing Issue: Search the existing issues for this repository. If there is an issue that fits your needs do not file a new one. Subscribe, react, or comment on that issue instead.
• Descriptive Title: Write the title for this issue as a short synopsis. If possible, provide context. For example, "Document new Get-Foo cmdlet" instead of "New cmdlet."

Summary

Requires documentation for two new cmdlets, a new automatic variable, and updated conceptual guidance.

New Cmdlets

Get-PSContentPath

• Module: Microsoft.PowerShell.Core
• Synopsis: Gets the current PowerShell user content path.
• Description: Returns a System.IO.DirectoryInfo object representing the directory where PowerShell stores user-scoped content (modules, scripts, profiles, help). The object includes a ConfigFile NoteProperty containing the path to powershell.config.json where the setting is persisted. Access via (Get-PSContentPath).ConfigFile or Get-PSContentPath | Select-Object -Property ConfigFile.
• Parameters: None
• Output type: System.IO.DirectoryInfo (with ConfigFile NoteProperty)
• HelpUri: https://go.microsoft.com/fwlink/?linkid=2344910

Examples:

# Get the current content path
(Get-PSContentPath).FullName

# Use in string interpolation
"Modules are stored in $(Get-PSContentPath)\Modules"

# Get the config file location
(Get-PSContentPath).ConfigFile

# Pipe to other commands
Get-PSContentPath | Get-ChildItem

Set-PSContentPath

• Module: Microsoft.PowerShell.Core
• Synopsis: Sets the PowerShell user content path.
• Description: Configures a custom directory for PowerShell user content (modules, scripts, profiles, help). The setting is persisted in powershell.config.json and takes effect in the current and future sessions. Environment variables in the path are expanded. The ConfirmImpact is High, so users are prompted for confirmation by default.
• HelpUri: https://go.microsoft.com/fwlink/?linkid=2344807

Parameter sets:

Parameter Set	Parameters
Path	-Path <string> (Mandatory, Position 0) — Absolute path for the content directory
Default	-Default (Mandatory, switch) — Resets to platform default

Both sets support -WhatIf and -Confirm.

Examples:

# Set a custom content path
Set-PSContentPath -Path "D:\PowerShell"

# Use environment variables
Set-PSContentPath -Path "$env:LOCALAPPDATA\PowerShell"

# Avoid OneDrive sync issues
Set-PSContentPath -Path "$env:LOCALAPPDATA\PowerShell"

# Reset to platform default
Set-PSContentPath -Default

# Preview the change without applying
Set-PSContentPath -Path "D:\PowerShell" -WhatIf

New Automatic Variable

$PSUserContentPath

• Type: System.String (readonly)
• Description: Contains the current PSContentPath value. This is a readonly variable — attempting to assign to it produces an error directing the user to use Set-PSContentPath.
• Scope: Global, readonly

PS> $PSUserContentPath
C:\Users\user\Documents\PowerShell

PS> $PSUserContentPath = "D:\Other"
# Error: Cannot modify the readonly variable 'PSUserContentPath'. Use Set-PSContentPath to configure this value.

Conceptual Documentation Updates

The following existing topics need updates:

1. about_Profiles — The user profile path is now determined by Get-PSContentPath. If a user changes their PSContentPath, $PROFILE reflects the new location. Existing profiles in the old location are NOT loaded automatically; users must copy or recreate them.

2. about_Modules — The personal module path ($env:PSModulePath) now includes both the PSContentPath-based location and the legacy Documents\PowerShell\Modules as a fallback, ensuring backward compatibility with PowerShellGet-installed modules.

3. about_Updatable_Help — User-scoped help files are stored under {PSContentPath}\Help. If a user changes their PSContentPath, they should re-run Update-Help to populate the new location.

4. about_PSModulePath — Document that the first user entry in $env:PSModulePath comes from PSContentPath, with the legacy Documents path appended as a fallback.

What Content is Affected by PSContentPath

Content	Path	Fallback to old location?
Modules	{PSContentPath}\Modules	Yes — legacy Documents\PowerShell\Modules remains in $env:PSModulePath
Profiles	{PSContentPath}\profile.ps1	No — user must migrate
Help	{PSContentPath}\Help	No — user can re-run Update-Help
Scripts	{PSContentPath}\Scripts	No (PSResourceGet only)

Platform Defaults

Platform	Default PSContentPath
Windows	Documents\PowerShell
Linux	~/.local/share/powershell
macOS	~/.local/share/powershell

Note: The Windows default will change to $env:LOCALAPPDATA\PowerShell in a future release, once a migration story is in place.

Related Links

• RFC: PowerShell-RFC#388

Details

I kept this feature as an opt-in in the following way: users must use Set-PSContentPath to start using a new path. Recommend "$env:LOCALAPPDATA\PowerShell" but not required.

We search two locations for config files, first "$env:LOCALAPPDATA\PowerShell" and second the onedrive location. If it doesn't find any in either location, it will create the file in "$env:LOCALAPPDATA\PowerShell" .

It is recommended for users to migrate their profile and config file to "$env:LOCALAPPDATA\PowerShell" and Set-PSContentPath -Path "$env:LOCALAPPDATA\PowerShell"

Articles

No response

Related Source Pull Requests

• PowerShell PR: Add PSContentPath Infrastructure PowerShell/PowerShell#26509
• PSResourceGet PR: PSResourceGet#1912

Related Source Issues

• Let's move PSModulePath out of the documents folder PowerShell/PowerShell#15552