Modules were introduced with the release of PowerShell version 2.0. A module is a packaged set of commands that includes any required supporting content; modules often include help content.

Modules tend to target a specific system or focus on a small set of related operations. For example, the Microsoft.PowerShell.Archive module contains a small number of commands for interacting with ZIP files.

The modules available on a system can be discovered using the Get-Module command.

The Get-Module command

Get-Module is used to find the modules either in the current PowerShell session, or available on the current system.

PowerShell itself comes with several built-in modules, including PowerShellGet, ThreadJob, PSReadLine, and the commands in the Microsoft.PowerShell.* modules.

The Windows platform, especially the most recent versions, comes with a wide variety of modules installed. These, as well as any other available modules, can be viewed using the Get-Module -ListAvailable command.

By default, Get-Module returns information about each module that has been imported (either automatically or by using Import-Module). For example, if the command is run from PowerShell 7, it shows that the ISE module has been loaded:

PS> Get-Module
ModuleType    Version    Name                            ExportedCommands 
----------    -------    ----                            ---------------- 
Script        1.0.0.0    ISE                             {Get-IseSnippe...}
Manifest      3.1.0.0    Microsoft.PowerShell.Management {Add-Computer...}

The ListAvailable parameter shows the list of modules that are available on the system instead of just those that have been imported:

Get-Module -ListAvailable

Modules are discovered using the paths in the PSModulePath environment variable, which contains a delimited list of paths for PowerShell to search.

Get-Module will show all instances of a module regardless of the path and version when using the All parameter:

Get-Module <ModuleName> -All -ListAvailable 

Modules that are available on a system can be imported either by running Import-Module or by running a command from the module.

The Import-Module command

PowerShell 3 and later attempts to automatically load modules if a command from that module is used and the module is under one of the paths in the $env:PSModulePath environment variable. Explicit use of the Import-Module command is less important than it was before Windows PowerShell 3.

For example, if PowerShell is started and the CimCmdlets module is not imported, running the Get-CimInstance command will cause the module to be automatically imported. This is shown in the following example:

PS> Get-Module CimCmdlets
PS> Get-CimInstance Win32_OperatingSystem | Out-Null
PS> Get-Module CimCmdlets
ModuleType Version    PreRelease Name         ExportedCommands
---------- -------    ---------- ----         ----------------
Binary     7.0.0.0               CimCmdlets   {Get-CimAssociatedInstance,...

The autoloader may be disabled using the $PSModuleAutoLoadingPreference variable as shown here:

$PSModuleAutoLoadingPreference = 'None'

You can explicitly import modules in PowerShell using the Import-Module command. Modules may be imported using a name or with a full path, as shown in the following example:

Import-Module -Name ThreadJob
Import-Module -Name $PSHome\Modules\ThreadJob\ThreadJob.psd1

Importing a module using a path is only required if the module is not in a discoverable path.

Once a module has been imported, the commands within the module may be listed using Get-Command as follows:

Get-Command -Module ThreadJob 

Modules installed in Windows PowerShell 5 and later are placed in a folder named after the module version, for example, Modules\ModuleName\1.0.0\<ModuleContent>. This allows multiple versions of the same module to coexist, as shown in the following example:

Figure 2.1: Side-by-side versioning

Version 1.8.1 of PSScriptAnalyzer will be imported by default, as it is the highest version number. It is possible to import a specific version of a module using the MinimumVersion and MaximumVersion parameters:

Import-Module PSScriptAnalyzer -MaxmimumVersion 1.7.0

Modules that have been imported can be removed from a PowerShell session using the Remove-Module command.

The Remove-Module command

The Remove-Module command removes a previously imported module from the current session.

For binary modules or manifest modules that incorporate a Dynamic Link Library (DLL), commands are removed from PowerShell but DLLs are not unloaded. DLL files used in a PowerShell session cannot be unloaded without restarting the PowerShell process.

Remove-Module does not remove or delete the files that make up a module from a computer.

Each of the preceding commands, by default, interacts with modules saved in the PSModulePath environment variable.

PSModulePath in PowerShell

PSModulePath is a delimited list of paths that can be used to store modules. You can import modules in these paths by name and they will be automatically loaded when a command from the module is used.

PowerShell allows the value of $env:PSModulePath to be set using user- and machine-scoped environment variables. By default, the machine-scoped variable should include the following paths, which are used by Windows PowerShell and by PowerShell 7 for compatibility:

C:\Program Files\WindowsPowerShell\Modules
C:\Windows\System32\WindowsPowerShell\v1.0\Modules

If the environment variables do not exist, PowerShell 7 uses the default values:

PS> $Env:PSModulePath -split ';'
C:\Users\whoami\Documents\PowerShell\Modules
C:\Program Files\PowerShell\Modules
c:\program files\powershell\7\Modules

The default values in the preceding list are included regardless of the value of the environment variable.

When using module paths, it is important to note that PowerShell does not search all paths for the latest version of a module. PowerShell searches the list of paths in the order they appear in the PSModulePath environment variable. If a module is listed in more than one path, the most recent version from the first discovered path is used.

For example, if the current user path contains a module with version 1.0.0, and the program files path contains the same module but with version 2.0.0, PowerShell will prefer to load version 1.0.0 because the current user path is searched first. The Version or MinimumVersion parameter must be used with Import-Module to avoid this.

If both Windows PowerShell and PowerShell 7 are in use in an environment, care must be taken when updating the PSModulePath environment variable. The behavior described previously differs from Windows PowerShell. In Windows PowerShell:

• If the user environment variable is set, it completely replaces the user value, which defaults to C:\Users\whoami\Documents\WindowsPowerShell\Modules
• If the machine environment variable is set, it replaces the system32 path: C:\windows\system32\windowspowershell\v1.0\Modules
• In all cases, the C:\Program Files\WindowsPowerShell\Modules path remains

The C:\windows\system32\windowspowershell\v1.0\Modules path should be included in the machine environment variable to allow PowerShell 7 to load modules, either directly or using a Windows PowerShell compatibility session.

The value of $env:PSModulePath may be safely modified within on all PowerShell versions and all platforms, for example, by using a profile script. Changes made to $env:PSModulePath are scoped to the process and only affect the current PowerShell session and any child processes; the changes do not persist.

PowerShell 7 can use modules intended for Windows PowerShell either directly or by using a Windows PowerShell compatibility session.

Using Windows PowerShell modules in PowerShell 7

Many modules available to Windows PowerShell are compatible with PowerShell 7 without requiring any changes.

If a module is not compatible with PowerShell 7, an attempt can be made to load the module in a Windows compatibility session.

In PowerShell 6, the following functionality discussed is part of the WindowsCompatibility module available in the PowerShell Gallery. This module is not required in PowerShell 7. In PowerShell 7, the ability to load a module in a compatibility session is built into the Import-Module command.

The TLS module, for example, will not load PowerShell 7 by default because it does not state that it supports the Core edition of PowerShell, as shown by Get-Module:

PS> Get-Module TLS -ListAvailable -SkipEditionCheck
    Directory: C:\Windows\System32\WindowsPowerShell\v1.0\Modules
ModuleType Version    PreRelease Name       PSEdition ExportedCommands
---------- -------    ---------- ----       --------- ----------------
Manifest   2.0.0.0               TLS        Desk      {New-TlsSessionTic...

The module can be loaded in two ways:

The edition check can be skipped (the module may work, it may just lack testing, and therefore careful testing may be required before using the module in a production scenario):

Import-Module TLS -SkipEditionCheck

Alternatively, if the previous command fails, the module may load in a compatibility session:

PS> Import-Module TLS -UseWindowsPowerShell
WARNING: Module TLS is loaded in Windows PowerShell using WinPSCompatSession remoting session; please note that all input and output of commands from this module will be deserialized objects. If you want to load this module into PowerShell Core please use 'Import-Module -SkipEditionCheck' syntax.

The compatibility session can be seen using the Get-PSSession command after the module has been imported:

Get-PSSession -Name WinPSCompatSession

When importing the preceding TLS module, a warning message is displayed that notes the input and output is deserialized. The impact of this depends on the complexity of the objects returned by the command; typically, it will mean that methods of specialized types will not work from PowerShell 7.

The effect of this can be demonstrated by invoking Get-WmiObject in the compatibility session. Get-WmiObject is not available in PowerShell 7 and cannot be directly used:

$session = Get-PSSession -Name WinPSCompatSession
$process = Invoke-Command -Session $session -ScriptBlock {
    Get-WmiObject Win32_Process -Filter "ProcessID=$PID"
}

If the Get-WmiObject command is run in Windows PowerShell without using Invoke-Command, it will have several methods available. One of these methods is GetRelated, which is typically used as follows when used in Windows PowerShell:

$process = Get-WmiObject Win32_Process -Filter "ProcessID=$PID"
$process.GetRelated('Win32_Session')

Because PowerShell 7 has a copy of the properties only, the method does not exist and an error will be displayed:

PS> $session = Get-PSSession -Name WinPSCompatSession
PS> $process = Invoke-Command -Session $session -ScriptBlock {
>>     Get-WmiObject Win32_Process -Filter "ProcessID=$PID"
>> }
PS> $process.GetRelated('Win32_Session')
InvalidOperation: Method invocation failed because [Deserialized.System.Management.ManagementObject#root\cimv2\Win32_Process] does not contain a method named 'GetRelated'.

The compatibility feature is incredibly useful but does not replace native compatibility with modern versions of PowerShell.

PowerShell on the Windows platform has a wide variety of modules available, or available through installable applications and features to interact with other systems. New modules can also be installed from resources such as the PowerShell Gallery.

PowerShell includes a module named PowerShellGet, which can be used to register repositories and search for and install modules.

By default, PowerShellGet searches the PowerShell Gallery.

What is the PowerShell Gallery?

The PowerShell Gallery is a Microsoft-run repository and distribution platform for PowerShell scripts and modules written by Microsoft or other users.

The PowerShell Gallery has parallels in other scripting languages, as shown in the following examples:

• Perl has cpan.org
• Python has PyPI
• Ruby has RubyGems

Support for the gallery is included by default in PowerShell 5 and above. For Windows PowerShell 3 and 4, PowerShellGet must be installed as described in Microsoft Docs: https://docs.microsoft.com/powershell/scripting/gallery/installing-psget.

The PowerShell Gallery may be searched using https://www.powershellgallery.com as shown in the following screenshot:

Figure 2.2: Searching the PowerShell Gallery

You can use the Find-Module command to search the PowerShell Gallery, or any registered repository, instead of using the web page.

The Find-Module command

Find-Module is used to search registered PowerShell repositories. Modules are identified by name, as shown in the following example:

Find-Module Carbon 
Find-Module -Name Carbon 
Find-Module -Name Azure* 

You can use the Filter parameter when the name alone is not sufficient to find an appropriate module. Supplying a value for the Filter parameter is equivalent to using the search field in the PowerShell Gallery, it expands the search to include tags:

Find-Module -Filter IIS

The Find-Module command cannot filter based on PowerShell edition, and the result of the search does not state which version the module might work with.

Once found, a module can be installed using the Install-Module command.

The Install-Module command

The Install-Module command installs modules from the PowerShell Gallery or any other configured repository. By default, Install-Module adds modules to the path for AllUsers, at C:\Program Files\PowerShell\Modules on Windows and at /usr/local/share/powershell/Modules on Ubuntu.

For example, the posh-git module may be installed using either of the following two commands:

Find-Module -Name posh-git | Install-Module 
Install-Module posh-git 

Modules may be installed under a user-specific path ($home\Documents\WindowsPowerShell\Modules) using the Scope parameter:

Install-Module carbon -Scope CurrentUser

If the most recent version of a module is already installed, the command ends without providing feedback. If a newer version is available, it will be automatically installed alongside the original.

The Force parameter may be used to reinstall a module:

Install-Module posh-git -Force 

Force may also be used to install a newer version of a module when the existing version was not installed from a PS repository, or when changing the scope a module is installed in.

The Install-Module command does not provide an option to install modules under the $PSHOME directory. The $PSHOME directory is reserved for modules that are shipped with the PowerShell installer, or for Windows PowerShell, those that are shipped with the Windows operating system.

The Update-Module command

You can use the Update-Module command to update any module installed using the Install-Module command.

In both Windows PowerShell and PowerShell 7, Update-Module attempts to update the specified module to the latest or specified version.

The Save-Module command

The Save-Module command downloads the module from the PowerShell Gallery (or any other registered repository) to a path without installing it. This is useful if you save a module to an alternate module path, or if you intend to copy the module onto a system that cannot use Install-Module.

The following example command downloads the Carbon module into a Modules directory in the root of the C: drive:

Save-Module -Name Carbon -Path C:\Modules 

Save-Module will download the module and overwrite any previously saved version in the specified path. The command ignores other downloaded versions of the module.

Each of the preceding commands is part of PowerShellGet 2. PowerShellGet 3 is likely to be released in the coming months and adopts a slightly different approach to the commands.

PowerShellGet 2 (for example, PowerShellGet 2.2.4.1) implements the Install-Module, Update-Module, and Save-Module module commands demonstrated at the beginning of this chapter.

PowerShellGet 3.0 is in preview at the time of writing; the following commands are based on the beta7 pre-release. One of the key features is that this new version does not depend on the PackageManagement module, allowing a simpler installation process, avoiding the need to bootstrap the NuGet provider, making upgrading the module simpler.

The preview version also uses new command names, completely divorcing it from the previous implementations of PowerShellGet. The change in command names means the new version can safely be installed alongside any existing version.

PowerShellGet 3.0 can be installed as follows:

Install-Module PowerShellGet -Force -AllowPrerelease

Once installed, you'll need to register the PowerShell Gallery or another repository:

Register-PSResourceRepository -PSGallery

In PowerShellGet 2.0, you implement separate commands to work with modules and scripts. PowerShellGet 3.0 does not differentiate between modules and scripts; all artifacts are termed PSResource, and all searches use the Find-PSResource command. For example, we can find a module by using the following command:

Find-PSResource -Name Indented.Net.IP -Type Module

The Type parameter may be omitted without affecting the search results in this case.

Most of the commands in PowerShellGet 3.0 use the same approach as those in PowerShellGet 2.2.4 and below. Over time, the differences between the commands are likely to start to appear; for example, Install-PSResource includes a Reinstall parameter, which is somewhat like the Force parameter for Install-Module in PowerShellGet 2.

Repositories

Like older versions of PowerShellGet, repositories are registered on a per-user basis. In PowerShellGet 2.2.4 and below, the repository configuration file is found in the following path:

$env:LOCALAPPDATA\Microsoft\Windows\PowerShell\PowerShellGet\PSRepositories.xml

The PSRepositories.xml file is stored in CliXml format and may be read using the Import-CliXml command. The file is normally read and updated using Get-PSRepository, Register-PSRepository, and Unregister-PSRespository.

PowerShellGet 3.0 uses a simpler format for the PSResourceRespository.xml file. The file may be found in the following path:

$env:LOCALAPPDATA\PowerShellGet\PSResourceRepository.xml

The Get-PSResourceRepository, Register-PSResourceRepository, and Unregister-PSResourceRepository commands are the expected way of interacting with this file.

As with older versions of PowerShellGet, storing credentials for a repository is not currently supported. If a repository requires authentication, the Credential parameter must be used explicitly with each operation.

Version ranges

Find-PSResource allows wildcards to be used for the Version parameter; using * will return all available versions except pre-release. The Prerelease parameter may be added to include those:

Find-PSResource -Name PowerShellGet -Version *

A range of versions may be defined using the range syntax used by NuGet, which is described in the following document:

https://docs.microsoft.com/nuget/concepts/package-versioning#version-ranges-and-wildcards

For example, the highest version of PowerShellGet available between 1.0 (inclusive) and 2.0 (exclusive) may be found using this:

Find-PSResource -Name PowerShellGet -Version '[1.0,2.0)'

The search can be changed to be inclusive by changing the closing ) to ]. For example, the following command will find version 2.0.0 of PowerShellGet:

Find-PSResource -Name PowerShellGet -Version '[1.0,2.0]'

The same syntax will be available when declaring dependencies between modules.