Find-Module
Finds modules in a repository that match specified criteria.
Syntax
All
Find-Module
[[-Name] <string[]>]
[-MinimumVersion <string>]
[-MaximumVersion <string>]
[-RequiredVersion <string>]
[-AllVersions]
[-IncludeDependencies]
[-Filter <string>]
[-Tag <string[]>]
[-Includes <string[]>]
[-DscResource <string[]>]
[-RoleCapability <string[]>]
[-Command <string[]>]
[-Proxy <uri>]
[-ProxyCredential <pscredential>]
[-Repository <string[]>]
[-Credential <pscredential>]
[-AllowPrerelease]
[<CommonParameters>]
Description
The Find-Module cmdlet finds modules in a repository that match the specified criteria.
Find-Module returns a PSRepositoryItemInfo object for each module it finds. The objects can be
sent down the pipeline to cmdlets such as Install-Module.
The first time Find-Module attempts to use a repository, you might be prompted to install updates.
If the repository source is not registered with Register-PSRepository cmdlet, an error is
returned.
Find-Module returns the newest version of a module if no parameters are used that limit the
version. To get a repository's list of a module's versions, use the parameter AllVersions.
If the MinimumVersion parameter is specified, Find-Module returns the module's version that is
equal to or greater than the minimum. If there is a newer version available in the repository, the
newer version is returned.
If the MaximumVersion parameter is specified, Find-Module returns the newest version of the
module that does not exceed the version specified.
If the RequiredVersion parameter is specified, Find-Module only returns the module version
that is an exact match to the specified version. Find-Module searches through all available
modules, because name conflicts between sources can occur.
The parameters that take module version numbers expect strings formatted as version numbers.
- Standard version numbers have a format of
x.y.zwhere x, y, and z are numbers - Prerelease versions have a format of
x.y.z-<prerelease_label>where the<prerelease_label>is arbitrary string assigned to that release.
The following examples use the PowerShell Gallery as the only
registered repository. Get-PSRepository displays the registered repositories. If you have multiple
registered repositories, use the -Repository parameter to specify the repository's name.
Examples
Example 1: Find a module by name
This example finds a module in the default repository.
Find-Module -Name PowerShellGet
Version Name Repository Description
------- ---- ---------- -----------
2.1.0 PowerShellGet PSGallery PowerShell module with commands for discovering...
The Find-Module cmdlet uses the Name parameter to specify the PowerShellGet module.
Example 2: Find modules with similar names
This example uses the asterisk (*) wildcard to find modules with similar names.
Find-Module -Name PowerShell*
Version Name Repository Description
------- ---- ---------- -----------
0.4.0 powershell-yaml PSGallery Powershell module for serializing and...
2.1.0 PowerShellGet PSGallery PowerShell module with commands for...
1.9 Powershell.Helper.Extension PSGallery # Powershell.Helper.Extension...
3.1 PowerShellHumanizer PSGallery PowerShell Humanizer wraps Humanizer...
4.0 PowerShellISEModule PSGallery a module that adds capability to the ISE
The Find-Module cmdlet uses the Name parameter with the asterisk (*) wildcard to find all
modules that contain PowerShell.
Example 3: Find a module by minimum version
This example searches for a module's minimum version. If the repository contains a newer version of the module, the newer version is returned.
Find-Module -Name PowerShellGet -MinimumVersion 1.6.5
Version Name Repository Description
------- ---- ---------- -----------
2.1.0 PowerShellGet PSGallery PowerShell module with commands for discovering...
The Find-Module cmdlet uses the Name parameter to specify the PowerShellGet module. The
MinimumVersion specifies version 1.6.5. Find-Module returns PowerShellGet version
2.1.0 because it exceeds the minimum version and is the most current version.
Example 4: Find a module by specific version
This example shows how to install a specific prerelease version of a module. Prerelease versions
have a format of <version_number>-<prerelease_label>.
Find-Module PSReadLine -AllowPrerelease -RequiredVersion 2.2.4-beta1
Version Name Repository Description
------- ---- ---------- -----------
2.2.4-beta1 PSReadLine PSGallery Great command line editing in the PowerS…
Example 5: Find a module in a specific repository
This example uses the Repository parameter to find a module in a specific repository.
Find-Module -Name PowerShellGet -Repository PSGallery
Version Name Repository Description
------- ---- ---------- -----------
2.1.0 PowerShellGet PSGallery PowerShell module with commands for discovering...
The Find-Module cmdlet uses the Name parameter to specify the PowerShellGet module. The
Repository parameter specifies to search the PSGallery repository.
Example 6: Find a module in multiple repositories
This example uses the Register-PSRepository to specify a repository. Find-Module uses the
repository to search for a module.
Register-PSRepository -Name MySource -SourceLocation https://www.myget.org/F/powershellgetdemo/
Find-Module -Name Contoso* -Repository PSGallery, MySource
Repository Version Name Description
---------- ------- ---- -----------
PSGallery 2.0.0.0 ContosoServer Cmdlets and DSC resources for managing Contoso Server...
MySource 1.2.0.0 ContosoClient Cmdlets and DSC resources for managing Contoso Client...
The Register-PSRepository cmdlet registers a new repository. The Name parameter assigns the
name MySource. The SourceLocation parameter specifies the repository's address.
The Find-Module cmdlet uses the Name parameter with the asterisk (*) wildcard to specify the
Contoso module. The Repository parameter specifies to search two repositories, PSGallery
and MySource.
Example 7: Find a module that contains a DSC resource
This command returns modules that contain DSC resources. The Includes parameter has four predefined functionalities that are used to search the repository. Use tab-complete to display the four functionalities supported by the Includes parameter.
Find-Module -Repository PSGallery -Includes DscResource
Version Name Repository Description
------- ---- ---------- -----------
2.7.0 Carbon PSGallery Carbon is a PowerShell module...
8.5.0.0 xPSDesiredStateConfiguration PSGallery The xPSDesiredStateConfiguration module...
1.3.1 PackageManagement PSGallery PackageManagement (a.k.a. OneGet) is...
2.7.0.0 xWindowsUpdate PSGallery Module with DSC Resources...
3.2.0.0 xCertificate PSGallery This module includes DSC resources...
3.1.0.0 xPowerShellExecutionPolicy PSGallery This DSC resource can change the user...
The Find-Module cmdlet uses the Repository parameter to search the repository, PSGallery.
The Includes parameter specifies DscResource, which is a functionality that the parameter
can search for in the repository.
Example 8: Find a module with a filter
In this example, to find modules, a filter is used to search the repository.
For a NuGet-based repository, the Filter parameter searches through the name, description, and tags for the argument.
Find-Module -Filter AppDomain
Version Name Repository Description
------- ---- ---------- -----------
1.0.0.0 AppDomainConfig PSGallery Manipulate AppDomain configuration...
1.1.0 ClassExplorer PSGallery Quickly search the AppDomain for classes...
The Find-Module cmdlet uses the Filter parameter to search the repository for AppDomain.
Example 9: Find a module by tag
This example shows how to find modules by a tag. The CrescendoBuilt value is a tag that is
automatically added to modules created using the Microsoft.PowerShell.Crescendo module.
Find-Module -Tag CrescendoBuilt
Version Name Repository Description
------- ---- ---------- -----------
0.1.0 Foil PSGallery A PowerShell Crescendo wrapper for Chocolatey
0.3.1 Cobalt PSGallery A PowerShell Crescendo wrapper for WinGet
1.1.0 SysInternals PSGallery PowerShell cmdlets for SysInternal tools
0.0.4 Croze PSGallery A PowerShell Crescendo wrapper for Homebrew
0.0.2 AptPackage PSGallery PowerShell Crescendo-generated Module to query APT-Package Information
1.0.1 RoboCopy PSGallery PowerShell cmdlet for the official RoboCopy.exe
1.0.2 TShark PSGallery PowerShell cmdlet for tshark.exe
1.0.0 SpeedTestCLI PSGallery PowerShell cmdlets speedtest-cli
1.0.0 SpeedTest-CLI PSGallery PowerShell cmdlets for Internet Speed Test
1.0.2 Image2Text PSGallery PowerShell Images into ASCII art
0.1.1 Quser.Crescendo PSGallery This module displays session information of users logged onto a local or remote m...
1.0.2 Takeown PSGallery Crescendo Powershell wrapper of takeown.exe
Parameters
-AllowPrerelease
Includes in the results modules marked as a pre-release.
Parameter properties
| Type: | SwitchParameter |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
(All)
| Position: | Named |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
-AllVersions
Specifies to include all versions of a module in the results. You cannot use the AllVersions parameter with the MinimumVersion, MaximumVersion, or RequiredVersion parameters.
Parameter properties
| Type: | SwitchParameter |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
(All)
| Position: | Named |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
-Command
Specifies an array of commands to find in modules. A command can be a function or workflow.
Parameter properties
| Type: | String[] |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
(All)
| Position: | Named |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
-Credential
Specifies a user account that has rights to install a module for a specified package provider or source.
Parameter properties
| Type: | PSCredential |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
(All)
| Position: | Named |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | True |
| Value from remaining arguments: | False |
-DscResource
Specifies the name, or part of the name, of modules that contain DSC resources. Per PowerShell conventions, performs an OR search when you provide multiple arguments.
Parameter properties
| Type: | String[] |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
(All)
| Position: | Named |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
-Filter
Specifies a filter based on the PackageManagement provider-specific search syntax. For NuGet modules, this parameter is the equivalent of searching using the Search bar on the PowerShell Gallery website.
Parameter properties
| Type: | String |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
(All)
| Position: | Named |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
-IncludeDependencies
Indicates that this operation includes all modules that are dependent upon the module specified in the Name parameter.
Parameter properties
| Type: | SwitchParameter |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
(All)
| Position: | Named |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
-Includes
Returns only those modules that include specific kinds of PowerShell functionality. For example, you might only want to find modules that include DSCResource. The acceptable values for this parameter are as follows:
- Cmdlet
- DscResource
- Function
- RoleCapability
Parameter properties
| Type: | String[] |
| Default value: | None |
| Accepted values: | DscResource, Cmdlet, Function, RoleCapability |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
(All)
| Position: | Named |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
-MaximumVersion
Specifies the maximum, or latest, version of the module to include in the search results. MaximumVersion and RequiredVersion cannot be used in the same command.
Parameter properties
| Type: | String |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
(All)
| Position: | Named |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | True |
| Value from remaining arguments: | False |
-MinimumVersion
Specifies the minimum version of the module to include in results. MinimumVersion and RequiredVersion cannot be used in the same command.
Parameter properties
| Type: | String |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
(All)
| Position: | Named |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | True |
| Value from remaining arguments: | False |
-Name
Specifies the names of modules to search for in the repository. A comma-separated list of module names is accepted. Wildcards are accepted.
Parameter properties
| Type: | String[] |
| Default value: | None |
| Supports wildcards: | True |
| DontShow: | False |
Parameter sets
(All)
| Position: | 0 |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | True |
| Value from remaining arguments: | False |
-Proxy
Specifies a proxy server for the request, rather than connecting directly to the Internet resource.
Parameter properties
| Type: | Uri |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
(All)
| Position: | Named |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | True |
| Value from remaining arguments: | False |
-ProxyCredential
Specifies a user account that has permission to use the proxy server that is specified by the Proxy parameter.
Parameter properties
| Type: | PSCredential |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
(All)
| Position: | Named |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | True |
| Value from remaining arguments: | False |
-Repository
Use the Repository parameter to specify which repository to search for a module. Used when
multiple repositories are registered. Accepts a comma-separated list of repositories. To register a
repository, use Register-PSRepository. To display registered repositories, use Get-PSRepository.
Parameter properties
| Type: | String[] |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
(All)
| Position: | Named |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
-RequiredVersion
Specifies the exact version number of the module to include in the results. RequiredVersion cannot be used in the same command as MinimumVersion or MaximumVersion.
Parameter properties
| Type: | String |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
(All)
| Position: | Named |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | True |
| Value from remaining arguments: | False |
-RoleCapability
Specifies an array of role capabilities.
Parameter properties
| Type: | String[] |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
(All)
| Position: | Named |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
-Tag
Specifies an array of tags. Example tags include DesiredStateConfiguration, DSC, DSCResourceKit, or PSModule.
Parameter properties
| Type: | String[] |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
(All)
| Position: | Named |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
CommonParameters
This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, -ProgressAction, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters.
Inputs
String
String
Uri
PSCredential
Outputs
PSRepositoryItemInfo
Find-Module creates PSRepositoryItemInfo objects that can be sent down the pipeline to cmdlets
such as Install-Module.
Notes
PowerShell includes the following aliases for Find-Module:
- All platforms:
fimo
Important
As of April 2020, the PowerShell Gallery no longer supports Transport Layer Security (TLS) versions 1.0 and 1.1. If you are not using TLS 1.2 or higher, you will receive an error when trying to access the PowerShell Gallery. Use the following command to ensure you are using TLS 1.2:
[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
For more information, see the announcement in the PowerShell blog.
