Installing a PowerShell Module - PowerShell (2023)

  • Article
  • 8 minutes to read

After you have created your PowerShell module, you will likely want to install the module on asystem, so that you or others may use it. Generally speaking, this consists of copying the modulefiles (ie, the .psm1, or the binary assembly, the module manifest, and any other associated files)onto a directory on that computer. For a very small project, this may be as simple as copying andpasting the files with Windows Explorer onto a single remote computer; however, for larger solutionsyou may wish to use a more sophisticated installation process. Regardless of how you get your moduleonto the system, PowerShell can use a number of techniques that will let users find and use yourmodules. Therefore, the main issue for installation is ensuring that PowerShell will be able to findyour module. For more information, seeImporting a PowerShell Module.

Rules for Installing Modules

The following information pertains to all modules, including modules that you create for your ownuse, modules that you get from other parties, and modules that you distribute to others.

Install Modules in PSModulePath

Whenever possible, install all modules in a path that is listed in the PSModulePath environmentvariable or add the module path to the PSModulePath environment variable value.

The PSModulePath environment variable ($Env:PSModulePath) contains the locations of WindowsPowerShell modules. Cmdlets rely on the value of this environment variable to find modules.

By default, the PSModulePath environment variable value contains the following system and usermodule directories, but you can add to and edit the value.

  • $PSHome\Modules (%Windir%\System32\WindowsPowerShell\v1.0\Modules)


    This location is reserved for modules that ship with Windows. Do not install modules to thislocation.

  • $HOME\Documents\WindowsPowerShell\Modules (%HOMEDRIVE%%HOMEPATH%\Documents\WindowsPowerShell\Modules)

  • $Env:ProgramFiles\WindowsPowerShell\Modules (%ProgramFiles%\WindowsPowerShell\Modules)

    To get the value of the PSModulePath environment variable, use either of the followingcommands.


    To add a module path to value of the PSModulePath environment variable value, use thefollowing command format. This format uses the SetEnvironmentVariable method of theSystem.Environment class to make a session-independent change to the PSModulePathenvironment variable.

    #Save the current value in the $p variable.$p = [Environment]::GetEnvironmentVariable("PSModulePath")#Add the new path to the $p variable. Begin with a semi-colon separator.$p += ";C:\Program Files (x86)\MyCompany\Modules\"#Add the paths in $p to the PSModulePath value.[Environment]::SetEnvironmentVariable("PSModulePath",$p)


    Once you have added the path to PSModulePath, you should broadcast an environment messageabout the change. Broadcasting the change allows other applications, such as the shell, to pickup the change. To broadcast the change, have your product installation code send aWM_SETTINGCHANGE message with lParam set to the string "Environment". Be sure to send themessage after your module installation code has updated PSModulePath.

Use the Correct Module Directory Name

A well-formed module is a module that is stored in a directory that has the same name as the basename of at least one file in the module directory. If a module is not well-formed, WindowsPowerShell does not recognize it as a module.

The "base name" of a file is the name without the file name extension. In a well-formed module, thename of the directory that contains the module files must match the base name of at least one filein the module.

For example, in the sample Fabrikam module, the directory that contains the module files is named"Fabrikam" and at least one file has the "Fabrikam" base name. In this case, both Fabrikam.psd1 andFabrikam.dll have the "Fabrikam" base name.

C:\Program Files Fabrikam Technologies Fabrikam Manager Modules Fabrikam Fabrikam.psd1 (module manifest) Fabrikam.dll (module assembly)

Effect of Incorrect Installation

If the module is not well-formed and its location is not included in the value of thePSModulePath environment variable, basic discovery features of Windows PowerShell, such as thefollowing, do not work.

  • The Module Auto-Loading feature cannot import the module automatically.

  • The ListAvailable parameter of theGet-Module cmdlet cannot find themodule.

  • The Import-Module cmdlet cannot findthe module. To import the module, you must provide the full path to the root module file or modulemanifest file.

    Additional features, such as the following, do not work unless the module is imported into thesession. In well-formed modules in the PSModulePath environment variable, these features workeven when the module is not imported into the session.

  • The Get-Command cmdlet cannot findcommands in the module.

  • The Update-Help andSave-Help cmdlets cannot update or savehelp for the module.

  • The Show-Command cmdlet cannotfind and display the commands in the module.

    The commands in the module are missing from the Show-Command window in Windows PowerShellIntegrated Scripting Environment (ISE).

Where to Install Modules

This section explains where in the file system to install Windows PowerShell modules. The locationdepends on how the module is used.

Installing Modules for a Specific User

If you create your own module or get a module from another party, such as a Windows PowerShellcommunity website, and you want the module to be available for your user account only, install themodule in your user-specific Modules directory.

$HOME\Documents\WindowsPowerShell\Modules\<Module Folder>\<Module Files>

The user-specific Modules directory is added to the value of the PSModulePath environmentvariable by default.

Installing Modules for all Users in Program Files

If you want a module to be available to all user accounts on the computer, install the module in theProgram Files location.

$Env:ProgramFiles\WindowsPowerShell\Modules\<Module Folder>\<Module Files>


The Program Files location is added to the value of the PSModulePath environment variable bydefault in Windows PowerShell 4.0 and later. For earlier versions of Windows PowerShell, you canmanually create the Program Files location (%ProgramFiles%\WindowsPowerShell\Modules) and addthis path to your PSModulePath environment variable as described above.

Installing Modules in a Product Directory

If you are distributing the module to other parties, use the default Program Files locationdescribed above, or create your own company-specific or product-specific subdirectory of the%ProgramFiles% directory.

For example, Fabrikam Technologies, a fictitious company, is shipping a Windows PowerShell modulefor their Fabrikam Manager product. Their module installer creates a Modules subdirectory in theFabrikam Manager product subdirectory.

C:\Program Files Fabrikam Technologies Fabrikam Manager Modules Fabrikam Fabrikam.psd1 (module manifest) Fabrikam.dll (module assembly)

To enable the Windows PowerShell module discovery features to find the Fabrikam module, the Fabrikammodule installer adds the module location to the value of the PSModulePath environment variable.

$p = [Environment]::GetEnvironmentVariable("PSModulePath")$p += ";C:\Program Files\Fabrikam Technologies\Fabrikam Manager\Modules\"[Environment]::SetEnvironmentVariable("PSModulePath",$p)

Installing Modules in the Common Files Directory

If a module is used by multiple components of a product or by multiple versions of a product,install the module in a module-specific subdirectory of the %ProgramFiles%\Common Files\Modulessubdirectory.

In the following example, the Fabrikam module is installed in a Fabrikam subdirectory of the%ProgramFiles%\Common Files\Modules subdirectory. Note that each module resides in its ownsubdirectory in the Modules subdirectory.

C:\Program Files Common Files Modules Fabrikam Fabrikam.psd1 (module manifest) Fabrikam.dll (module assembly)

Then, the installer assures the value of the PSModulePath environment variable includes the pathof the common files modules subdirectory.

$m = $env:ProgramFiles + '\Common Files\Modules'$p = [Environment]::GetEnvironmentVariable("PSModulePath")$q = $p -split ';'if ($q -notContains $m) { $q += ";$m"}$p = $q -join ';'[Environment]::SetEnvironmentVariable("PSModulePath", $p)

Installing Multiple Versions of a Module

To install multiple versions of the same module, use the following procedure.

  1. Create a directory for each version of the module. Include the version number in the directoryname.
  2. Create a module manifest for each version of the module. In the value of the ModuleVersionkey in the manifest, enter the module version number. Save the manifest file (.psd1) in theversion-specific directory for the module.
  3. Add the module root folder path to the value of the PSModulePath environment variable, asshown in the following examples.

To import a particular version of the module, the end-user can use the MinimumVersion orRequiredVersion parameters of theImport-Module cmdlet.

For example, if the Fabrikam module is available in versions 8.0 and 9.0, the Fabrikam moduledirectory structure might resemble the following.

C:\Program FilesFabrikam Manager Fabrikam8 Fabrikam Fabrikam.psd1 (module manifest: ModuleVersion = "8.0") Fabrikam.dll (module assembly) Fabrikam9 Fabrikam Fabrikam.psd1 (module manifest: ModuleVersion = "9.0") Fabrikam.dll (module assembly)

The installer adds both of the module paths to the PSModulePath environment variable value.

$p = [Environment]::GetEnvironmentVariable("PSModulePath")$p += ";C:\Program Files\Fabrikam\Fabrikam8;C:\Program Files\Fabrikam\Fabrikam9"[Environment]::SetEnvironmentVariable("PSModulePath",$p)

When these steps are complete, the ListAvailable parameter of the Get-Modulecmdlet gets both of the Fabrikam modules. To import a particular module, use the MinimumVersion orRequiredVersion parameters of the Import-Modulecmdlet.

If both modules are imported into the same session, and the modules contain cmdlets with the samenames, the cmdlets that are imported last are effective in the session.

Handling Command Name Conflicts

Command name conflicts can occur when the commands that a module exports have the same name ascommands in the user's session.

When a session contains two commands that have the same name, Windows PowerShell runs the commandtype that takes precedence. When a session contains two commands that have the same name and thesame type, Windows PowerShell runs the command that was added to the session most recently. To run acommand that is not run by default, users can qualify the command name with the module name.

For example, if the session contains a Get-Date function and the Get-Date cmdlet, WindowsPowerShell runs the function by default. To run the cmdlet, preface the command with the modulename, such as:


To prevent name conflicts, module authors can use the DefaultCommandPrefix key in the modulemanifest to specify a noun prefix for all commands exported from the module.

Users can use the Prefix parameter of the Import-Module cmdlet to use an alternate prefix. Thevalue of the Prefix parameter takes precedence over the value of the DefaultCommandPrefixkey.

Supporting paths on non-Windows systems

Non-Windows platforms use the colon (:) character as a path separator and a forward-slash (/)character as a directory separator. The [System.IO.Path] class has static members that can beused to make your code work on any platform:

  • [System.IO.Path]::PathSeparator - returns the character used to separate paths in a PATHenvironment variable for the host platform
  • [System.IO.Path]::DirectorySeparatorChar - returns the character used to separate directorynames with a path for the host platform

Use these static properties to in place of the ; and \ characters when you are constructing pathstrings.

See Also


Writing a Windows PowerShell Module

Top Articles
Latest Posts
Article information

Author: Kerri Lueilwitz

Last Updated: 12/20/2022

Views: 5599

Rating: 4.7 / 5 (67 voted)

Reviews: 90% of readers found this page helpful

Author information

Name: Kerri Lueilwitz

Birthday: 1992-10-31

Address: Suite 878 3699 Chantelle Roads, Colebury, NC 68599

Phone: +6111989609516

Job: Chief Farming Manager

Hobby: Mycology, Stone skipping, Dowsing, Whittling, Taxidermy, Sand art, Roller skating

Introduction: My name is Kerri Lueilwitz, I am a courageous, gentle, quaint, thankful, outstanding, brave, vast person who loves writing and wants to share my knowledge and understanding with you.