about_PSModulePath
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.
By default, the effective locations assigned to $env:PSModulePath are:
System-wide locations: These folders contain modules that ship with PowerShell. These modules are store in the
$PSHOME\Modulesfolder. This is also the location where the Windows management modules are installed.User-installed modules: These are modules installed by the user.
Install-Modulehas 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.- On Windows, the location of the user-specific CurrentUser scope is
the
$HOME\Documents\PowerShell\Modulesfolder. The location of the AllUsers scope is$env:ProgramFiles\PowerShell\Modules. - On non-Windows systems, the location of the user-specific CurrentUser
scope is the
$HOME/.local/share/powershell/Modulesfolder. The location of the AllUsers scope is/usr/local/share/powershell/Modules.
- On Windows, the location of the user-specific CurrentUser scope is
the
In addition, setup programs that install modules in other directories, such
as the Program Files directory, can append their locations to the value of
$env:PSModulePath.
Note
On Windows, the user-specific location is the PowerShell\Modules folder
located in the Documents folder in your user profile. The specific path
of that location varies by version of Windows and whether or not you are
using folder redirection. Microsoft OneDrive can also change the location of
your Documents folder. You can verify the location of your Documents
folder using the following command:
[Environment]::GetFolderPath('MyDocuments').
PowerShell PSModulePath construction
The value of $env:PSModulePath is constructed each time PowerShell starts.
The value varies by version of PowerShell and how it is launched.
Windows PowerShell startup
Windows PowerShell uses the following logic to construct the PSModulePath at
startup:
- If
PSModulePathdoesn't exist, combine CurrentUser, AllUsers, and the$PSHOMEmodules paths - If
PSModulePathdoes exist:- If
PSModulePathcontains$PSHOMEmodules path:- AllUsers modules path is inserted before
$PSHOMEmodules path
- AllUsers modules path is inserted before
- else:
- Just use
PSModulePathas defined since the user deliberately removed the$PSHOMElocation
- Just use
- If
The CurrentUser module path is prefixed only if User scope
$env:PSModulePath doesn't exist. Otherwise, the User scope
$env:PSModulePath is used as defined.
PowerShell 7 startup
In Windows, for most environment variables, if the User-scoped variable exists, a new process uses that value only even if a Machine-scoped variable of the same name exists.
In PowerShell 7, PSModulePath is treated similar to how the Path
environment variable is treated on Windows. On Windows, Path is treated
differently from other environment variables. When a process is started,
Windows combines the User-scoped Path with the Machine-scoped Path.
- Retrieve the User-scoped
PSModulePath - Compare to process inherited
PSModulePathenvironment variable- If the same:
- Append the AllUsers
PSModulePathto the end following the semantics of thePathenvironment variable - The Windows
System32path comes from the machine definedPSModulePathso does not need to be added explicitly
- Append the AllUsers
- If different, treat as though user explicitly modified it and don't append
AllUsers
PSModulePath
- If the same:
- Prefix with PS7 User, System, and
$PSHOMEpaths in that order- If
powershell.config.jsoncontains a user scopedPSModulePath, use that instead of the default for the user - If
powershell.config.jsoncontains a system scopedPSModulePath, use that instead of the default for the system
- If
Unix systems don't have a separation of User and System environment variables.
PSModulePath is inherited and the PS7-specific paths are prefixed if not
already defined.
Starting Windows PowerShell from PowerShell 7
For this discussion, Windows PowerShell means both powershell.exe and
powershell_ise.exe.
The value of $env:PSModulePath is copied to WinPSModulePath with the
following modifications:
- Remove PS7 the User module path
- Remove PS7 the System module path
- Remove PS7 the
$PSHOMEmodule path
The PS7 paths are removed so that PS7 modules don't get loaded in Windows
PowerShell. The WinPSModulePath value is used when starting Windows
PowerShell.
Starting PowerShell 7 from Windows PowerShell
The PowerShell 7 startup continues as-is with the addition of inheriting paths that Windows PowerShell added. Since the PS7-specific paths are prefixed, there is no functional issue.
Module search behavior
PowerShell recursively searches each folder in the PSModulePath for module
(.psd1 or .psm1) files. This search pattern allows multiple versions of the
same module to be installed in different folders. For example:
Directory: C:\Program Files\WindowsPowerShell\Modules\PowerShellGet
Mode LastWriteTime Length Name
---- ------------- ------ ----
d---- 8/14/2020 5:56 PM 1.0.0.1
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.
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.
For example, to temporarily add the C:\Program Files\Fabrikam\Modules
directory to $env:PSModulePath for the current session, type:
$Env:PSModulePath = $Env:PSModulePath+";C:\Program Files\Fabrikam\Modules"
The semi-colon (;) in the command separates the new path from the path that
precedes it in the list. On non-Windows platforms, the colon (:) separates
the path locations in the environment variable.
Modifying PSModulePath in non-Windows
To change the value of PSModulePath for every session in a non-Windows
environment, add the previous command to your PowerShell profile.
Modifying PSModulePath in Windows
To change the value of PSModulePath for every session in a Windows
environment, edit the registry key storing the PSModulePath values. The
PSModulePath values are stored in the registry as un-expanded strings. To
avoid permanently saving the PSModulePath values as expanded strings, use
the GetValue method on the sub-key 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.
$key = (Get-Item 'HKLM:\SYSTEM\CurrentControlSet\Control\Session Manager').OpenSubKey('Environment', $true)
$path = $key.GetValue('PSModulePath','','DoNotExpandEnvironmentNames')
$path += ';C:\Program Files\Fabrikam\Modules' # or '%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:\.
$key = (Get-Item 'HKCU:\SYSTEM\CurrentControlSet\Control\Session Manager').OpenSubKey('Environment', $true)
$path = $key.GetValue('PSModulePath','','DoNotExpandEnvironmentNames')
$path += ';C:\Program Files\Fabrikam\Modules' # or '%ProgramFiles%\Fabrikam\Modules'
$key.SetValue('PSModulePath',$path,[Microsoft.Win32.RegistryValueKind]::ExpandString)
See also
Feedback
Submit and view feedback for