Install-Module
Syntax
Install-Module
[-Name] <String[]>
[-MinimumVersion <String>]
[-MaximumVersion <String>]
[-RequiredVersion <String>]
[-Repository <String[]>]
[-Credential <PSCredential>]
[-Scope <String>]
[-Proxy <Uri>]
[-ProxyCredential <PSCredential>]
[-AllowClobber]
[-SkipPublisherCheck]
[-Force]
[-AllowPrerelease]
[-AcceptLicense]
[-WhatIf]
[-Confirm]
[<CommonParameters>]
Install-Module
[-InputObject] <PSObject[]>
[-Credential <PSCredential>]
[-Scope <String>]
[-Proxy <Uri>]
[-ProxyCredential <PSCredential>]
[-AllowClobber]
[-SkipPublisherCheck]
[-Force]
[-AcceptLicense]
[-WhatIf]
[-Confirm]
[<CommonParameters>]
Description
The Install-Module
cmdlet gets one or more modules that meet specified criteria from an online
gallery, verifies that search results are valid modules, and copies module folders to the
installation location.
You can filter your results based on minimum and exact versions of specified modules.
Examples
Example 1: Find a module and install it
In this example, modules with a name that starts with MyDSC that are found by Find-Module
in the
online gallery are installed to the default folder, C:\ProgramFiles\WindowsPowerShell\Modules
.
Find-Module -Name "MyDSC*" | Install-Module
Example 2: Install a module by name
In this example, the newest version of the module MyDscModule from the online gallery is installed to the default folder.
Install-Module -Name "MyDscModule"
If no module named MyDscModule exists, an error occurs.
Example 3: Install a module using its minimum version
In this example, the most current version of the module ContosoServer is installed that matches the specified minimum version.
Install-Module -Name "ContosoServer" -MinimumVersion 1.0
If the most current version of the module is a lower number than 1.0, the command returns errors.
Example 4: Install a specific version of a module
This example installs version 1.1.3 of the module ContosoServer to the Program Files folder.
Install-Module -Name "ContosoServer" -RequiredVersion 1.1.3
If version 1.1.3 is not available, an error occurs.
Example 5: Install the current version of a module
This example installs the newest version of the module ContosoServer to
$home\Documents\WindowsPowerShell\Modules
.
Install-Module -Name "ContosoServer" -Scope "CurrentUser"
Required Parameters
Used for pipeline input.
Type: | PSObject[] |
Position: | 0 |
Default value: | None |
Accept pipeline input: | True (ByPropertyName, ByValue) |
Accept wildcard characters: | False |
Specifies the exact names of modules to install from the online gallery. This parameter supports wildcard characters. If wildcard characters are not specified, only modules that exactly match the specified names are returned. If no matches are found, and you have not used any wildcard characters, the command returns an error. If you use wildcard characters, but do not find matching results, no error is returned.
Type: | String[] |
Position: | 0 |
Default value: | None |
Accept pipeline input: | True (ByPropertyName) |
Accept wildcard characters: | False |
Optional Parameters
Automatically accept the license agreement during installation if the module requires it.
Type: | SwitchParameter |
Position: | Named |
Default value: | None |
Accept pipeline input: | False |
Accept wildcard characters: | False |
Allows you install module that contains commands those have the same names as commands that already exists.
Type: | SwitchParameter |
Position: | Named |
Default value: | None |
Accept pipeline input: | False |
Accept wildcard characters: | False |
Allows you to install a module marked as a prerelease.
Type: | SwitchParameter |
Position: | Named |
Default value: | None |
Accept pipeline input: | False |
Accept wildcard characters: | False |
Prompts you for confirmation before running the cmdlet.
Type: | SwitchParameter |
Aliases: | cf |
Position: | Named |
Default value: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
Specifies a user account that has rights to install a module for a specified package provider or source.
Type: | PSCredential |
Position: | Named |
Default value: | None |
Accept pipeline input: | True (ByPropertyName) |
Accept wildcard characters: | False |
Forces the installation of modules. If a module of the same name and version already exists on the computer, this parameter overwrites the existing module with one of the same name that was found by the command.
Type: | SwitchParameter |
Position: | Named |
Default value: | None |
Accept pipeline input: | False |
Accept wildcard characters: | False |
Specifies the maximum version of a single module to install. You cannot add this parameter if you are attempting to install multiple modules. The MaximumVersion and the RequiredVersion parameters are mutually exclusive; you cannot use both parameters in the same command.
Type: | String |
Position: | Named |
Default value: | None |
Accept pipeline input: | True (ByPropertyName) |
Accept wildcard characters: | False |
Specifies the minimum version of a single module to install. You cannot add this parameter if you are attempting to install multiple modules. The MinimumVersion and the RequiredVersion parameters are mutually exclusive; you cannot use both parameters in the same command.
If you are installing multiple modules in a single command, and a specified minimum version for a
module is not available for installation, the Install-Module
command silently continues without
installing the unavailable module. For example, if you try to install the ContosoServer module with
a minimum version of 2.0, but the latest version of the ContosoServer module is 1.5, the
Install-Module
command does not install the ContosoServer module; it goes to install the next
specified module, and PowerShell display errors when the command is finished.
Type: | String |
Position: | Named |
Default value: | None |
Accept pipeline input: | True (ByPropertyName) |
Accept wildcard characters: | False |
Specifies a proxy server for the request, rather than connecting directly to the Internet resource.
Type: | Uri |
Position: | Named |
Default value: | None |
Accept pipeline input: | True (ByPropertyName) |
Accept wildcard characters: | False |
Specifies a user account that has permission to use the proxy server that is specified by the Proxy parameter.
Type: | PSCredential |
Position: | Named |
Default value: | None |
Accept pipeline input: | True (ByPropertyName) |
Accept wildcard characters: | False |
Specifies the friendly name of a repository that has been registered by running
Register-PSRepository
.
Type: | String[] |
Position: | Named |
Default value: | None |
Accept pipeline input: | False |
Accept wildcard characters: | False |
Specifies the exact version of a single module to install. You cannot add this parameter if you are attempting to install multiple modules. The MinimumVersion and the RequiredVersion parameters are mutually exclusive; you cannot use both parameters in the same command.
Type: | String |
Position: | Named |
Default value: | None |
Accept pipeline input: | True (ByPropertyName) |
Accept wildcard characters: | False |
Specifies the installation scope of the module. The acceptable values for this parameter are: AllUsers and CurrentUser.
The AllUsers scope lets modules be installed in a location that is accessible to all users of the
computer, that is, $env:ProgramFiles\WindowsPowerShell\Modules
.
The CurrentUser scope lets modules be installed only to
$home\Documents\WindowsPowerShell\Modules
, so that the module is available only to the current
user.
When no Scope is defined, the default will be set based on the current session:
- For an elevated PowerShell session, Scope defaults to AllUsers;
- For non-elevated PowerShell sessions in PowerShellGet versions 2.0.0 and above, Scope is CurrentUser;
- For non-elevated PowerShell sessions in PowerShellGet versions 1.6.7 and earlier, Scope is
undefined, and
Install-Module
fails.
Type: | String |
Accepted values: | CurrentUser, AllUsers |
Position: | Named |
Default value: | None |
Accept pipeline input: | False |
Accept wildcard characters: | False |
Allows you to install a newer version of a module that already exists on your computer in the case when a newer one is not digitally signed by a trusted publisher and the newest existing module is digitally signed by a trusted publisher.
Type: | SwitchParameter |
Position: | Named |
Default value: | None |
Accept pipeline input: | False |
Accept wildcard characters: | False |
Shows what would happen if the cmdlet runs. The cmdlet is not run.
Type: | SwitchParameter |
Aliases: | wi |
Position: | Named |
Default value: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
Inputs
PSGetItemInfo
Notes
This cmdlet runs on PowerShell 5.0 or later releases, on Windows 7 or Windows 2008 R2 and later releases of Windows.
If an installed module cannot be imported (that is, if it does not have a .psm1, .psd1, or .dll of the same name within the folder), installation fails unless you add the Force parameter to your command.
If a version of the module on the computer matches the value specified for the Name parameter,
and you have not added the MinimumVersion or RequiredVersion parameter, Install-Module
silently continues without installing that module.
If the MinimumVersion or RequiredVersion parameters are specified, and the existing module does not match the values in that parameter, then an error occurs. To be more specific: if the version of the currently-installed module is either lower than the value of the MinimumVersion parameter, or not equal to the value of the RequiredVersion parameter, an error occurs.
If the version of the installed module is greater than the value of the MinimumVersion
parameter, or equal to the value of the RequiredVersion parameter, Install-Module
silently
continues without installing that module.
Install-Module
returns an error if no module exists in the online gallery that matches the
specified name.
To install multiple modules, specify an array of the module names, separated by commas. You cannot add MinimumVersion or RequiredVersion if you specify multiple module names.
By default, modules are installed to the Program Files folder, to prevent confusion when you are
installing Windows PowerShell Desired State Configuration (DSC) resources.You can pipe multiple
PSGetItemInfo objects to Install-Module
; this is another way of specifying multiple modules
to install in a single command.
To help prevent running modules that contain malicious code, installed modules are not automatically imported by installation.
As a security best practice, evaluate module code before running any cmdlets or functions in a module for the first time.
Related Links
Feedback
We'd love to hear your thoughts. Choose the type you'd like to provide:
Our feedback system is built on GitHub Issues. Read more on our blog.
Loading feedback...