Clean up docs on PSModulePath (#11454)

Author: sdwheeler

reference/5.1/Microsoft.PowerShell.Core/About/about_Modules.md

@@ -1,7 +1,7 @@
 ---
 description: Explains how to install, import, and use PowerShell modules.
 Locale: en-US
-ms.date: 08/09/2024
+ms.date: 10/09/2024
 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_modules?view=powershell-5.1&WT.mc_id=ps-gethelp
 schema: 2.0.0
 title: about_Modules
@@ -18,29 +18,24 @@ PowerShell are implemented as scripts, functions, or cmdlets. The language
 includes [keywords][07], which provide the structure and logic of processing,
 and other resources, such as variables, providers, aliases.
 
-A module is a self-contained, reusable unit that can include cmdlets, providers,
-functions, variables, and other resources that can be imported into a PowerShell
-session or any custom PowerShell program.
-
-Before the functionality contained in a module is usable, the module must be
-loaded into the PowerShell session. By default, PowerShell automatically loads
-an installed module the first time you use a command from the module. You can
-configure automatic module loading behavior using the variable
-`$PSModuleAutoloadingPreference`. For more information, see
+A module is a self-contained, reusable unit that can include cmdlets,
+providers, functions, variables, and other resources. By default, PowerShell
+automatically loads an installed module the first time you use a command from
+the module. You can configure automatic module loading behavior using the
+variable `$PSModuleAutoloadingPreference`. For more information, see
 [about_Preference_Variables][08].
 
-You can also manually unload or reload modules during a PowerShell session. To
-unload a module, use the `Remove-Module` cmdlet. To load or reload a module,
-use `Import-Module`.
+You can also manually load or unload modules during a PowerShell session. To
+load or reload a module, use `Import-Module`. To unload a module, use the
+`Remove-Module` cmdlet.
 
-PowerShell comes with a base set of modules. Anyone can create new PowerShell
-commands or other resources, and publish them as modules that users can install
-as needed.
+PowerShell includes a base set of modules. Anyone can create new modules using
+C# or the PowerShell scripting language itself. Modules written in C# as
+compiled .NET assemblies are known as native modules. Modules written in
+PowerShell are known as script modules.
 
-You can write modules in C# as compiled .NET assemblies, known as native
-modules, or in plain PowerShell, known as script modules. This topic explains
-how to use PowerShell modules. For information about how to create PowerShell
-modules, see [Writing a PowerShell Module][02].
+This article explains how to use PowerShell modules. For information about how
+to create PowerShell modules, see [Writing a PowerShell Module][02].
 
 > [!NOTE]
 > Prior to PowerShell 3.0, cmdlets and providers were packaged in PowerShell
@@ -49,42 +44,13 @@ modules, see [Writing a PowerShell Module][02].
 > remaining in PowerShell. All other snap-ins were converted to modules.
 > Creation of new snap-ins is no longer supported.
 
-## Install a published module
+## Default module locations
 
-A published module is a module that is available from a registered repository,
-such as the PowerShell Gallery. The **PowerShellGet** and
-**Microsoft.PowerShell.PSResourceGet** modules provide cmdlets for finding,
-installing, and publishing PowerShell modules to a registered repository.
+PowerShell stores modules in the following default locations:
 
-The **PowerShellGet** module is included with PowerShell 5.0 and later
-releases. The **Microsoft.PowerShell.PSResourceGet** module is included with
-PowerShell 7.4 and later releases. **Microsoft.PowerShell.PSResourceGet** is
-the new preferred package manager for PowerShell and can be installed on
-previous versions of PowerShell. Use the `Install-Module` or
-`Install-PSResource` cmdlet to install modules from the PowerShell Gallery.
-
-```powershell
- Get-Command Install-Module, Install-PSResource
-```
-
-```Output
-CommandType  Name                Version    Source
------------  ----                -------    ------
-Function     Install-Module      2.9.0      PowerShellGet
-Cmdlet       Install-PSResource  1.0.0      Microsoft.PowerShell.PSResourceGet
-```
-
-For more information, see [PowerShellGet Overview][01].
-
-## Manually install a module
-
-If you receive a module as a folder with files in it, you need to install it on
-your computer before you can use it in PowerShell.
-
-PowerShell comes with several preinstalled modules. On Windows-based computers,
-many Windows features include modules for managing the feature. Those modules
-get installed when the feature is installed. Other modules may come in an
-installer or setup program that installs the module.
+  - All users scope - `$env:ProgramFiles\WindowsPowerShell\Modules`
+  - Current user scope - `$HOME\Documents\WindowsPowerShell\Modules`
+  - Modules shipped with PowerShell - `$PSHOME\Modules`
 
 By default, the `Modules` folder for the current user doesn't exist. If you
 installed a module in the `CurrentUser` scope using `Install-Module` or
@@ -97,31 +63,19 @@ Use the following command to create a `Modules` folder for the current user:
 $folder = New-Item -Type Directory -Path $HOME\Documents\WindowsPowerShell\Modules
 ```
 
-Copy the entire module folder into the new created folder. In PowerShell use
-the `Copy-Item` cmdlet. For example, run the following command to copy the
-`MyModule` folder from `C:\PSTest` to the folder you just created:
-
-```powershell
-Copy-Item -Path C:\PSTest\MyModule -Destination $folder
-```
-
-You can install a module in any location, but installing your modules in a
-default module location makes them easier to manage. For more information about
-the default module locations, see [about_PSModulePath][10].
+These locations are automatically included in the `$env:PSModulePath`
+environment variable. For more information about the default module locations,
+see [about_PSModulePath][10].
 
 ## Module autoloading
 
 The first time that you run a command from an installed module, PowerShell
 automatically imports (loads) that module. The module must be stored in the
-locations specified in the `$env:PSModulePath` environment variable. Modules in
-other locations must be imported using the `Import-Module` cmdlet.
+locations specified in the `$env:PSModulePath` environment variable.
 
 Module autoloading allows you to use commands in a module without any setup or
-profile configuration. There's no need to manage modules after you install them
-on your computer.
-
-Each of the following examples cause the **CimCmdlets** module, which contains
-`Get-CimInstance`, to be imported into your session.
+profile configuration. Each of the following examples causes the **CimCmdlets**
+module, which contains `Get-CimInstance`, to be imported into your session.
 
 - Run the Command
 
@@ -141,17 +95,9 @@ Each of the following examples cause the **CimCmdlets** module, which contains
   Get-Help Get-CimInstance
   ```
 
-You can use the `Get-Command` cmdlet list the commands in all installed
-modules, even if they're not yet in the session. When you use `Get-Command`
-with a wildcard character (`*`), PowerShell doesn't import any modules. You can
-use wildcards for command discovery without loading modules that you may not
-need in your session.
-
-Also, commands that use PowerShell providers don't automatically import a
-module. For example, if you use a command that requires the `WSMan:` drive,
-such as the `Get-PSSessionConfiguration` cmdlet, you might need to run the
-`Import-Module` cmdlet to import the **Microsoft.WSMan.Management** module that
-includes the `WSMan:` drive.
+When you use `Get-Command` with a wildcard character (`*`), PowerShell doesn't
+import any modules. You can use wildcards for command discovery without loading
+modules that you might not need in your session.
 
 ## Manually import a module
 
@@ -160,16 +106,21 @@ locations specified by the `$env:PSModulePath` environment variable, or when
 the module is provided as a standalone `.dll` or `.psm1` file, rather than a
 packaged module.
 
+Also, commands that use PowerShell providers don't automatically import a
+module. For example, if you use a command that requires the `WSMan:` drive,
+such as the `Get-PSSessionConfiguration` cmdlet, you might need to run the
+`Import-Module` cmdlet to import the **Microsoft.WSMan.Management** module that
+includes the `WSMan:` drive.
+
 You might also want to change how the module is imported in your session. For
 example, the **Prefix** parameter of `Import-Module` adds a distinctive prefix
 to the noun portion of the cmdlets imported from the module. The **NoClobber**
 parameter prevents the module from adding commands that would hide or replace
 existing commands in the session. For more information, see
 [Manage name conflicts][03].
 
-You can import a module that's installed in your `$env:PSModulePath` by
-specifying the module name. For example, the following command imports the
-**BitsTransfer** module into the current session.
+The following example imports the **BitsTransfer** module into the current
+session.
 
 ```powershell
 Import-Module BitsTransfer
@@ -202,10 +153,56 @@ the `Import-Module` command to your PowerShell profile.
 
 For more information about profiles, see [about_Profiles][09].
 
+## Install a published module
+
+A published module is a module that's available from a registered repository,
+such as the PowerShell Gallery. The **PowerShellGet** and
+**Microsoft.PowerShell.PSResourceGet** modules provide cmdlets for finding,
+installing, and publishing PowerShell modules to a registered repository.
+
+The **PowerShellGet** module is included with PowerShell 5.0 and later
+releases. The **Microsoft.PowerShell.PSResourceGet** module is included with
+PowerShell 7.4 and later releases and is the preferred package manager for
+PowerShell. **Microsoft.PowerShell.PSResourceGet** can be installed, side by
+side with **PowerShellGet**, on older versions of PowerShell. Use the
+`Install-Module` or `Install-PSResource` cmdlet to install modules from the
+PowerShell Gallery.
+
+```powershell
+ Get-Command Install-Module, Install-PSResource
+```
+
+```Output
+CommandType  Name                Version    Source
+-----------  ----                -------    ------
+Function     Install-Module      2.9.0      PowerShellGet
+Cmdlet       Install-PSResource  1.0.0      Microsoft.PowerShell.PSResourceGet
+```
+
+For more information, see [PowerShellGet Overview][01].
+
+## Manually install a module
+
+You can manually install a module by copying the module contents from another
+folder. That folder can be in another location on the local machine or
+installed on another machine. To install a module manually, copy the entire
+module folder into a new location included in your `$env:PSModulePath`.
+
+In PowerShell use the `Copy-Item` cmdlet. For example, run the following
+command to copy the `MyModule` folder from `C:\PSTest`:
+
+```powershell
+$modulePath = $HOME\Documents\PowerShell\Modules\MyModule
+Copy-Item -Path C:\PSTest\MyModule\* -Destination $modulePath -Recurse
+```
+
+You can install a module in any location, but installing your modules in a
+default module location makes them easier to manage.
+
 ## Find installed modules
 
-The `Get-Module` cmdlet gets the PowerShell modules that have been imported in
-your session.
+The `Get-Module` cmdlet gets the PowerShell modules that are loaded in the
+current PowerShell session.
 
 ```powershell
 Get-Module
@@ -312,7 +309,7 @@ have the same names as commands or items in the session.
 current session. Name conflicts can result in commands being hidden or
 replaced. Command replacement occurs when the imported module contains a
 command with the same name as an existing command in the session. The newly
-imported command replaces takes precedence over the existing command.
+imported command takes precedence over the existing command.
 
 For example, when a session includes a function and a cmdlet with the same
 name, PowerShell runs the function by default. When the session includes
@@ -322,9 +319,9 @@ name, by default, it runs the most recently added command.
 For more information, including an explanation of the precedence rules and
 instructions for running hidden commands, see [about_Command_Precedence][04].
 
-You can run a command that has been hidden or replaced by qualifying the
-command name. To qualify the command name, add the name of module than contains
-the version of the command you want. For example:
+You can run a hidden or replaced command by qualifying the command name. To
+qualify the command name, add the name of module that contains the version of
+the command you want. For example:
 
 ```powershell
 Microsoft.PowerShell.Utility\Get-Date

reference/5.1/Microsoft.PowerShell.Core/About/about_PSModulePath.md

@@ -1,52 +1,37 @@
 ---
 description: The PSModulePath environment variable contains a list of folder locations that are searched to find modules and resources.
 Locale: en-US
-ms.date: 03/24/2023
+ms.date: 10/09/2024
 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_PSModulePath?view=powershell-5.1&WT.mc_id=ps-gethelp
 schema: 2.0.0
 title: about_PSModulePath
 ---
 # about_PSModulePath
 
 ## Short description
+
 This article describes the purpose and usage of the `$env:PSModulePath`
 environment variable.
 
 ## Long description
 
 The `$env:PSModulePath` environment variable contains a list of folder
-locations that are searched to find modules and resources. PowerShell
-recursively searches each folder for module (`.psd1` or `.psm1`) files.
-
-`Install-Module` has a **Scope** parameter that allows you to specify whether
-the module is installed for the current user or for all users. For more
-information, see [Install-Module][01].
+locations. PowerShell recursively searches each folder for module (`.psd1` or
+`.psm1`) files.
 
 By default, the effective locations assigned to `$env:PSModulePath` are:
 
-- **System-wide locations**: These folders contain modules that ship with
-  PowerShell. These modules are stored in the `$PSHOME\Modules` folder. This is
-  also the location where the Windows management modules are installed.
-
-  Modules installed in the **AllUsers** scope are stored in
-  `$env:ProgramFiles\WindowsPowerShell\Modules`.
-
-- **User-installed modules**: These are modules installed in the
-  **CurrentUser** scope. The location of the **CurrentUser** scope is typically
-  the `$HOME\Documents\WindowsPowerShell\Modules` folder. The specific location
-  of the `Documents` folder varies by version of Windows and when you use
-  folder redirection. Also, Microsoft OneDrive can change the location of your
-  `Documents` folder. You can verify the location of your `Documents` folder
-  using the following command: `[Environment]::GetFolderPath('MyDocuments')`.
-
-- **Application specific modules**: Setup programs can install modules in other
-  directories, such as the `Program Files` directory. The installer may append
-  the application location to the value of `$env:PSModulePath`.
+- Modules installed in the **CurrentUser** scope are stored in
+  `$HOME\Documents\WindowsPowerShell\Modules`.
+- Modules installed in the **AllUsers** scope are stored in
+  `$env:ProgramFiles\PowerShell\Modules`.
+- Modules that ship with Windows PowerShell stored in `$PSHOME\Modules`, which
+  is `$env:SystemRoot\System32\WindowsPowerShell\1.0\Modules`.
 
 ## PowerShell PSModulePath construction
 
 The value of `$env:PSModulePath` is constructed each time PowerShell starts.
-The value varies by version of PowerShell and how it's launched.
+The value varies by version of PowerShell and how you launched it.
 
 ### Windows PowerShell startup
 
@@ -84,13 +69,13 @@ d----           9/13/2019  3:53 PM                2.1.2
 By default, PowerShell loads the highest version number of a module when
 multiple versions are found. To load a specific version, use `Import-Module`
 with the **FullyQualifiedName** parameter. For more information, see
-[Import-Module][02].
+[Import-Module][03].
 
 ## Modifying PSModulePath
 
 For most situations, you should be installing modules in the default module
-locations. However, you may have a need to change the value of the
-`PSModulePath` environment variable.
+locations. However, you might need to change the value of the `PSModulePath`
+environment variable.
 
 For example, to temporarily add the `C:\Program Files\Fabrikam\Modules`
 directory to `$env:PSModulePath` for the current session, type:
@@ -102,35 +87,35 @@ $Env:PSModulePath = $Env:PSModulePath+";C:\Program Files\Fabrikam\Modules"
 To change the value of `PSModulePath` in every session, edit the registry key
 storing the `PSModulePath` values. The `PSModulePath` values are stored in the
 registry as _unexpanded_ strings. To avoid permanently saving the
-`PSModulePath` values as _expanded_ strings, use the **GetValue** method on the
+`PSModulePath` values as _expanded_ strings, use the `GetValue()` method on the
 subkey and edit the value directly.
 
 The following example adds the `C:\Program Files\Fabrikam\Modules` path to the
 value of the `PSModulePath` environment variable without expanding the
-un-expanded strings.
+unexpanded strings.
 
 ```powershell
-$key = (Get-Item 'HKLM:\SYSTEM\CurrentControlSet\Control\Session Manager').OpenSubKey('Environment', $true)
+$key = (Get-Item 'HKLM:\SYSTEM\CurrentControlSet\Control\Session Manager\Environment')
 $path = $key.GetValue('PSModulePath','','DoNotExpandEnvironmentNames')
 $path += ';%ProgramFiles%\Fabrikam\Modules'
 $key.SetValue('PSModulePath',$path,[Microsoft.Win32.RegistryValueKind]::ExpandString)
 ```
 
-To add a path to the user setting, change the registry provider from `HKLM:\`
-to `HKCU:\`.
+To add a path to the user setting, use the following code:
 
 ```powershell
-$key = (Get-Item 'HKCU:\').OpenSubKey('Environment', $true)
+$key = (Get-Item 'HKCU:\Environment')
 $path = $key.GetValue('PSModulePath','','DoNotExpandEnvironmentNames')
 $path += ';%ProgramFiles%\Fabrikam\Modules'
 $key.SetValue('PSModulePath',$path,[Microsoft.Win32.RegistryValueKind]::ExpandString)
 ```
 
 ## See also
 
-- [about_Modules][03]
+- [about_Modules][01]
+- [about_Windows_PowerShell_Compatibility][02]
 
 <!-- link references -->
-[01]: xref:PowerShellGet.Install-Module
-[02]: xref:Microsoft.PowerShell.Core.Import-Module
-[03]: about_Modules.md
+[01]: about_Modules.md
+[02]: /powershell/module/microsoft.powershell.core/about/about_windows_powershell_compatibility
+[03]: xref:Microsoft.PowerShell.Core.Import-Module