The PowerShell Gallery is an online repository that features PowerShell module downloads and other code, but you'll need to be aware of some potential hang-ups associated with its use.
The gallery and the PowerShellGet module are a subset of the PowerShell package management system. You can view your currently installed repositories using the Get-PSRepository cmdlet. A PowerShell installation will only show the gallery.
New versions of PowerShell module downloads are frequently published to the gallery, and modules need to be kept up to date for full functionality. For instance, without the latest version of the PowerShellGet module, you cannot publish modules to the gallery. Because the PowerShell Gallery is a public code repository, you should always test any code before using it.
This article is part of
My favorite modules
There are more than 3,300 PowerShell module downloads available in the PowerShell Gallery; here are some worth a closer look.
- ISESteroids. This module provides a set of extensions for the PowerShell Integrated Scripting Environment. You'll need to buy a license from the author if you want to use it beyond the 10-day trial period. I've found it invaluable for catching coding issues, analyzing scripts and formatting code.
- Pester. This module runs a testing framework for PowerShell code and infrastructure configurations. Pester is also helpful for troubleshooting. Pester is installed with Windows PowerShell v5.1 -- it's not in PowerShell Core from v6.1 onwards -- but newer versions are available from the PowerShell Gallery.
- PlatyPS. This module generates a PowerShell help file in XAML from a markdown file.
- PoshRSJob. This module uses PowerShell runspaces to provide parallel execution. A good replacement for workflows.
- Dbatools. This module provides a huge number of commands to automate SQL Server database development and administration.
The time you try to use the PowerShellGet cmdlets on a machine, you'll get a notice to install the NuGet provider:
NuGet provider is required to continue
PowerShellGet requires NuGet provider version '22.214.171.124' or newer to interact with NuGet-based repositories. The NuGet provider must be available in
'C:\Program Files\PackageManagement\ProviderAssemblies' or
'C:\Users\richard\AppData\Local\PackageManagement\ProviderAssemblies'. You can also install the NuGet provider by running 'Install-PackageProvider -Name NuGet -MinimumVersion 126.96.36.199 -Force'. Do you want PowerShellGet to install and import the NuGet provider now?
[Y] Yes [N] No [S] Suspend [?] Help (default is "Y"):
Press Y for the install to proceed.
The PowerShellGet module is one of a set of providers. Others include the following:
- NuGet: a .NET package manager
- DockerProvider: offers access to container images
- Chocolatey: provides access to the Chocolatey software package management system
You can find the current list of possible providers using the following cmdlet:
A provider will access one or more sources, such as the PowerShell Gallery. You can view the available packages on NuGet using this command:
Find-Package -Provider NuGet -Source https://www.nuget.org/api/v2
The focus of this article is fetching PowerShell code from the PowerShell Gallery using the PowerShellGet module.
PowerShellGet comes with PowerShell, but it might require an update. The following table shows the PowerShellGet versions installed with the latest three versions of PowerShell.
Windows PowerShell 5.1.17134.228
Content offered by the PowerShell Gallery
The gallery offers three types of code:
- Modules, accessed with the Find-Module cmdlet.
- Desired State Configuration (DSC) resources, found with the Find-DscResource cmdlet, which shows individual resources, but you have to download the whole module that contains the resource.
- scripts, accessed with the Find-Script cmdlet.
The format of the command used to find the code types is Find-X, where X is the module, DSC resource or script.
Use the Find-Command cmdlet to search modules in the PowerShell Gallery for specific commands. The Find-RoleCapability cmdlet searches for Just Enough Administration role capabilities. None were available at the time this article was published.
Discover and install a PowerShell module
There is a lot of code available in the PowerShell Gallery. At last count, there were more than 3,000 modules to download. To fetch a module, use the PowerShell Community Extensions module. I know the name of the module -- PSCX -- but you can search the gallery on partial names:
Find-Module -Name *community*
Or the description:
Find-Module | where Description -like "*PowerShell Community Extensions*"
By default, a module search only shows the latest version.
Find-Module -Name pscx
This command shows version 3.3.2 as the current version. To see all available versions, use:
Find-Module -Name pscx -AllVersions
To show the beta versions, use this command:
Find-Module -Name pscx -AllVersions -AllowPrerelease
Most users download the latest version of the module, but it's possible to supply a minimum, maximum or required version to download a specific version.
To install a module, use this command:
Install-Module -Name pscx
The PowerShell Gallery is a public repository and, as such, is untrusted. Before the install occurs, PowerShell issues a warning and asks if you want to continue. You can avoid these messages and set the PowerShell Gallery to be a trusted repository, but I don't recommend it.
The progress bar will indicate what is happening during the download and install process. Also, PSCX contains some commands that have the same name as commands in PowerShell, so you'll get an error.
To import the commands in the module, use the -AllowClobber parameter:
Install-Module -Name pscx -AllowClobber
You won't get any feedback to indicate if the installation was completed. Run the following command to show if the module was installed in the C:\Program Files\WindowsPowerShell\Modules folder:
Get-Module -ListAvailable pscx
On machines that have Windows PowerShell v5.1 and PowerShell Core v6.x installed, you'll need to install the module twice -- once for each version -- because PowerShell Core stores downloaded modules in the C:\Program Files\PowerShell\Modules folder. Don't be tempted to add the Windows PowerShell v5.1 folder to the PowerShell v6 module path or vice versa.
The PowerShell Gallery installation process works in a similar fashion to PowerShell Core.
Set the scope of the module installation
You can control where the module installs with the -Scope parameter on Install-Module. You have two choices:
- The AllUsers option installs the module in the C:\Program Files\WindowsPowerShell\Modules. folder -- Windows PowerShell -- or the C:\Program Files\PowerShell\Modules -- PowerShell Core -- folder.
- The CurrentUser option installs the module in the $home\Documents\WindowsPowerShell\Module folder -- Windows PowerShell -- or the $home\Documents\PowerShell\Modules folder -- PowerShell Core.
Without a defined scope, the defaults are:
- Elevated session: scope defaults to AllUsers.
- Non-elevated session using PowerShellGet 2.0 and later: scope defaults to CurrentUser.
- Non-elevated session using PowerShellGet 1.6.7 and earlier: scope is undefined and installation fails.
My preference is to install with AllUsers because it results in a single copy of the module on the system, which makes it easier to keep track of what is installed using the Get-InstalledModule cmdlet.
Distributing modules to multiple machines
In a situation that requires the installation of a module from the PowerShell Gallery on many machines, the best option is to create a local gallery, download the module and republish it to the local gallery, from which you can then install the module. This is also a good technique to distribute your own modules throughout your organization.
Removing a module is a simple matter of uninstalling it with the following command:
Uninstall-Module pscx -Force
As a new version of a module gets released to the PowerShell Gallery, you'll want to upgrade your installed version. For instance, I have version 0.7.6 of the PlatyPS module on my machine, but checking for an update shows version 0.12 is available in the gallery. To update this installed module, I used the Update-Module cmdlet:
Update-Module -Name platyPS
If you try to update a module that was installed as part of the PowerShell installation, the following error occurs:
Update-Module -Name PowerShellGet
Update-Module : Module 'PowerShellGet' was not installed by using Install-Module, so it cannot be updated.
At line:1 char:1
+ Update-Module -Name PowerShellGet
+ CategoryInfo : InvalidOperation: (PowerShellGet:String) [Write-Error], WriteErrorException
+ FullyQualifiedErrorId : ModuleNotInstalledUsingInstallModuleCmdlet,Update-Module
The way around this is to force the installation of the module:
Install-Module -Name PowerShellGet -AllowClobber -Force
The newly installed version of the module will then be used by default. You can then use Update-Module to perform future updates when new versions arrive in the PowerShell Gallery.