Draft documentation tracking issue filed by the PowerShell team for an upcoming feature. The target release remains subject to the implementation PR being merged.
Current implementation: PowerShell/PowerShell#27535
Earlier design prototype: PowerShell/PowerShell#27632
Design discussion: PowerShell/PowerShell#27697
Umbrella: PowerShell/PowerShell#27565
Summary
For Windows MSIX-packaged PowerShell only, machine-wide configuration writes are redirected from the read-only $PSHOME installation directory to an admin-controlled, package-family-isolated directory under ProgramData:
%ProgramData%\Microsoft\PowerShell\<PackageFamilyName>\powershell.config.json
%ProgramData% is normally C:\ProgramData.
The shipped file at $PSHOME\powershell.config.json remains a read-only product-defaults layer. PowerShell does not copy or seed the whole product file into ProgramData. It writes only keys changed by an administrator.
This change is MSIX-specific:
- Windows MSIX packages use the new ProgramData override.
- Windows MSI, ZIP, and other unpackaged installations continue using
$PSHOME.
- Linux and macOS continue using
$PSHOME; no /etc/powershell relocation is included.
- Current-user configuration remains in the existing per-user configuration directory.
- Profiles are not relocated by this work.
Why the location changes
MSIX installs PowerShell into a read-only, tamper-protected package location. Machine-wide settings therefore cannot be safely written into $PSHOME.
PowerShell detects the current process's package identity with GetCurrentPackageFamilyName() and composes the ProgramData path itself. The implementation does not use the Windows App SDK MachineFolder manifest extension or its WindowsApps-backed path.
Using the package family name isolates Stable, Preview, and LTS packages when they have different package identities, preventing configuration from bleeding across channels.
Creation, permissions, and cleanup
PowerShell creates the ProgramData directory tree on the first redirected machine-wide write. It protects the PowerShell root and package-family directory from inheriting ambient ProgramData permissions, then applies inheritable rules at those directory boundaries:
- Owner: Built-in Administrators
SYSTEM: Full Control- Built-in Administrators: Full Control
- Built-in Users: Read and Execute
The configuration file and any future children inside the package-family directory inherit those rules. This avoids duplicating protected ACLs on every file while keeping broader or attacker-controlled parent permissions out of the machine configuration path.
Machine-wide writes require elevation. All users can read the resulting configuration.
For defense in depth, PowerShell rejects reparse points, inherited ACLs on the protected directory boundaries, a configuration file that does not inherit from the package-family directory, an untrusted owner, or a write-capable allow rule for an identity other than Administrators or SYSTEM.
The ProgramData file is intentionally outside the MSIX package and survives package upgrades and ordinary uninstall/reinstall operations. PowerShell does not automatically remove it during uninstall. Documentation should explain how an administrator can remove the package-family directory manually when permanent cleanup is desired.
Configuration layers and merge behavior
The implementation adds an internal MachineFolder configuration layer between the current-user configuration and the shipped $PSHOME defaults.
Preference settings
Preference settings use the first scope that defines the key:
CurrentUser > MachineFolder > $PSHOME (AllUsers product defaults)
Examples include:
ExecutionPolicy from JSON configurationDisableImplicitWinCompatWindowsPowerShellCompatibilityNoClobberModuleList
Policy-list settings
Policy-style lists are combined as a case-insensitive union across CurrentUser, MachineFolder, and $PSHOME. A higher-precedence scope cannot remove an entry supplied by another scope.
The current setting using this behavior is:
WindowsPowerShellCompatibilityModuleDenyList
Group Policy
Registry-backed Group Policy remains above all JSON configuration:
MachinePolicy > UserPolicy > Process > CurrentUser > LocalMachine
The new storage location does not change this public execution-policy ordering.
User-facing command behavior
Set-ExecutionPolicy
For an MSIX installation:
Set-ExecutionPolicy -Scope LocalMachine writes the changed value to the package-family ProgramData file.- Removing the LocalMachine execution-policy value removes it from that same ProgramData file.
- Reading LocalMachine policy checks the ProgramData override first and then falls back to the shipped
$PSHOME value.
LocalMachine remains the public scope name. Users do not need to select an additional scope to get the redirected behavior.
Experimental-feature cmdlets
Enable-ExperimentalFeature and Disable-ExperimentalFeature retain their existing implementation. Their AllUsers behavior is not redirected by this change and still targets $PSHOME, which remains read-only for MSIX.
The redesign needed to merge experimental-feature enable/disable state across machine layers is tracked separately in PowerShell/PowerShell#27702.
Configuration-discovery cmdlet
This implementation does not add Get-PowerShellConfiguration or another new configuration-discovery cmdlet. Configuration discovery/export remains separate work.
Documentation to add or update
about_PowerShell_Config
- Document the MSIX-only ProgramData path.
- Explain the three effective layers and their merge behavior.
- Make clear that
$PSHOME\powershell.config.json remains the immutable product-defaults file.
- Explain elevation, ACLs, package-family isolation, and uninstall persistence.
about_Execution_Policies
- Explain that
LocalMachine uses the ProgramData override for MSIX.
- Preserve the existing public scope ordering.
- Distinguish JSON execution-policy preferences from registry-backed Group Policy.
about_Windows_PowerShell_Compatibility
- Document union behavior for
WindowsPowerShellCompatibilityModuleDenyList.
- Document preference behavior for
DisableImplicitWinCompat and WindowsPowerShellCompatibilityNoClobberModuleList.
- Windows/MSIX installation documentation
- Explain that the ProgramData configuration survives uninstall/reinstall.
- Provide optional manual-cleanup instructions.
- Add a practical how-to for editing machine-wide settings in MSIX PowerShell:
- Locate
%ProgramData%\Microsoft\PowerShell\<PackageFamilyName>.
- Start an elevated editor or PowerShell session.
- Create or edit
powershell.config.json.
- Avoid editing the
$PSHOME copy.
Documentation should not reference the superseded WindowsApps Families\ApplicationData\<PFN>\Machine path or the appdata:MachineFolder manifest SDDL.
Out of scope
References
This issue reflects the latest implementation plan in PowerShell/PowerShell#27535. Exact release targeting and final wording should be confirmed when the implementation merges.
Summary
For Windows MSIX-packaged PowerShell only, machine-wide configuration writes are redirected from the read-only
$PSHOMEinstallation directory to an admin-controlled, package-family-isolated directory under ProgramData:%ProgramData%is normallyC:\ProgramData.The shipped file at
$PSHOME\powershell.config.jsonremains a read-only product-defaults layer. PowerShell does not copy or seed the whole product file into ProgramData. It writes only keys changed by an administrator.This change is MSIX-specific:
$PSHOME.$PSHOME; no/etc/powershellrelocation is included.Why the location changes
MSIX installs PowerShell into a read-only, tamper-protected package location. Machine-wide settings therefore cannot be safely written into
$PSHOME.PowerShell detects the current process's package identity with
GetCurrentPackageFamilyName()and composes the ProgramData path itself. The implementation does not use the Windows App SDKMachineFoldermanifest extension or its WindowsApps-backed path.Using the package family name isolates Stable, Preview, and LTS packages when they have different package identities, preventing configuration from bleeding across channels.
Creation, permissions, and cleanup
PowerShell creates the ProgramData directory tree on the first redirected machine-wide write. It protects the PowerShell root and package-family directory from inheriting ambient ProgramData permissions, then applies inheritable rules at those directory boundaries:
SYSTEM: Full ControlThe configuration file and any future children inside the package-family directory inherit those rules. This avoids duplicating protected ACLs on every file while keeping broader or attacker-controlled parent permissions out of the machine configuration path.
Machine-wide writes require elevation. All users can read the resulting configuration.
For defense in depth, PowerShell rejects reparse points, inherited ACLs on the protected directory boundaries, a configuration file that does not inherit from the package-family directory, an untrusted owner, or a write-capable allow rule for an identity other than Administrators or
SYSTEM.The ProgramData file is intentionally outside the MSIX package and survives package upgrades and ordinary uninstall/reinstall operations. PowerShell does not automatically remove it during uninstall. Documentation should explain how an administrator can remove the package-family directory manually when permanent cleanup is desired.
Configuration layers and merge behavior
The implementation adds an internal
MachineFolderconfiguration layer between the current-user configuration and the shipped$PSHOMEdefaults.Preference settings
Preference settings use the first scope that defines the key:
Examples include:
ExecutionPolicyfrom JSON configurationDisableImplicitWinCompatWindowsPowerShellCompatibilityNoClobberModuleListPolicy-list settings
Policy-style lists are combined as a case-insensitive union across CurrentUser, MachineFolder, and
$PSHOME. A higher-precedence scope cannot remove an entry supplied by another scope.The current setting using this behavior is:
WindowsPowerShellCompatibilityModuleDenyListGroup Policy
Registry-backed Group Policy remains above all JSON configuration:
The new storage location does not change this public execution-policy ordering.
User-facing command behavior
Set-ExecutionPolicyFor an MSIX installation:
Set-ExecutionPolicy -Scope LocalMachinewrites the changed value to the package-family ProgramData file.$PSHOMEvalue.LocalMachineremains the public scope name. Users do not need to select an additional scope to get the redirected behavior.Experimental-feature cmdlets
Enable-ExperimentalFeatureandDisable-ExperimentalFeatureretain their existing implementation. TheirAllUsersbehavior is not redirected by this change and still targets$PSHOME, which remains read-only for MSIX.The redesign needed to merge experimental-feature enable/disable state across machine layers is tracked separately in PowerShell/PowerShell#27702.
Configuration-discovery cmdlet
This implementation does not add
Get-PowerShellConfigurationor another new configuration-discovery cmdlet. Configuration discovery/export remains separate work.Documentation to add or update
about_PowerShell_Config$PSHOME\powershell.config.jsonremains the immutable product-defaults file.about_Execution_PoliciesLocalMachineuses the ProgramData override for MSIX.about_Windows_PowerShell_CompatibilityWindowsPowerShellCompatibilityModuleDenyList.DisableImplicitWinCompatandWindowsPowerShellCompatibilityNoClobberModuleList.%ProgramData%\Microsoft\PowerShell\<PackageFamilyName>.powershell.config.json.$PSHOMEcopy.Documentation should not reference the superseded WindowsApps
Families\ApplicationData\<PFN>\Machinepath or theappdata:MachineFoldermanifest SDDL.Out of scope
$PROFILE.AllUsersAllHostsand$PROFILE.AllUsersCurrentHost) - PS7-packaged: $profile.AllUsersAllHosts not writable by administrators PowerShell/PowerShell#27564Update-Help -Scope AllUsers) - PS7-packaged: Update-Help -Scope AllUsers fails under MSIX ($PSHOME read-only) PowerShell/PowerShell#27699.pssc) relocation - Some cmdlets and config require writing to $PSHOME\SessionConfig folder PowerShell/PowerShell#9278References
This issue reflects the latest implementation plan in PowerShell/PowerShell#27535. Exact release targeting and final wording should be confirmed when the implementation merges.