Install-Module
Downloads one or more modules from a repository, and installs them on the local computer.
Syntax
Install-Module
[-Name] <string[]>
[-MinimumVersion <version>]
[-MaximumVersion <version>]
[-RequiredVersion <version>]
[-Repository <string[]>]
[-Scope <string>]
[-Force]
[-WhatIf]
[-Confirm]
[<CommonParameters>]Install-Module
[-InputObject] <psobject[]>
[-Scope <string>]
[-Force]
[-WhatIf]
[-Confirm]
[<CommonParameters>]Description
The Install-Module cmdlet gets one or more modules that meet specified criteria from an online
repository. The cmdlet verifies that search results are valid modules and copies the module folders
to the installation location. Installed modules are not automatically imported after installation.
You can filter which module is installed based on the minimum, maximum, and exact versions of
specified modules.
If the module being installed has the same name or version, or contains commands in an existing
module, warning messages are displayed. After you confirm that you want to install the module and
override the warnings, use the -Force parameter. Dependent upon your repository settings, you
might need to answer a prompt for the module installation to continue.
These 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 and install a module
This example finds a module in the repository and installs the module.
Find-Module -Name PowerShellGet | Install-ModuleThe Find-Module uses the Name parameter to specify the PowerShellGet module. By default,
the newest version of the module is downloaded from the repository. The object is sent down the
pipeline to the Install-Module cmdlet. Install-Module installs the module for all users in
$env:ProgramFiles\WindowsPowerShell\Modules.
Example 2: Install a module by name
In this example, the newest version of the PowerShellGet module is installed.
Install-Module -Name PowerShellGetThe Install-Module uses the Name parameter to specify the PowerShellGet module. By
default, the newest version of the module is downloaded from the repository and installed.
Example 3: Install a module using its minimum version
In this example, the minimum version of the PowerShellGet module is installed. The MinimumVersion parameter specifies the lowest version of the module that should be installed. If a newer version of the module is available, that version is downloaded and installed for all users.
Install-Module -Name PowerShellGet -MinimumVersion 2.0.1The Install-Module uses the Name parameter to specify the PowerShellGet module. The
MinimumVersion parameter specifies that version 2.0.1 is downloaded from the repository and
installed. Because version 2.0.4 is available, that version is downloaded and installed for all
users.
Example 4: Install a specific version of a module
In this example, a specific version of the PowerShellGet module is installed.
Install-Module -Name PowerShellGet -RequiredVersion 2.0.0The Install-Module uses the Name parameter to specify the PowerShellGet module. The
RequiredVersion parameter specifies that version 2.0.0 is downloaded and installed for all
users.
Example 5: Install a module only for the current user
This example downloads and installs the newest version of a module, only for the current user.
Install-Module -Name PowerShellGet -Scope CurrentUserThe Install-Module uses the Name parameter to specify the PowerShellGet module.
Install-Module downloads and installs the newest version of PowerShellGet into the current
user's directory, $home\Documents\WindowsPowerShell\Modules.
Parameters
-Confirm
Prompts you for confirmation before running the Install-Module cmdlet.
| Type: | SwitchParameter |
| Aliases: | cf |
| Position: | Named |
| Default value: | False |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-Force
Installs a module and overrides warning messages about module installation conflicts. If a module with the same name already exists on the computer, Force allows for multiple versions to be installed. If there is an existing module with the same name and version, Force overwrites that version.
| Type: | SwitchParameter |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-InputObject
Used for pipeline input.
| Type: | PSObject[] |
| Position: | 0 |
| Default value: | None |
| Required: | True |
| Accept pipeline input: | True |
| Accept wildcard characters: | False |
-MaximumVersion
Specifies the maximum version of a single module to install. If you want to install multiple
modules, you cannot use MaximumVersion. MaximumVersion and RequiredVersion cannot be
used in the same Install-Module command.
| Type: | String |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | True |
| Accept wildcard characters: | False |
-MinimumVersion
Specifies the minimum version of a single module to install. If there is a newer version of the
module available, the newer version is installed. If you want to install multiple modules, you
cannot use MinimumVersion. MinimumVersion and RequiredVersion cannot be used in the same
Install-Module command.
| Type: | String |
| Aliases: | Version |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | True |
| Accept wildcard characters: | False |
-Name
Specifies the exact names of modules to install from the online gallery. A comma-separated list of
module names is accepted. The module name must match the module name in the repository. Use
Find-Module to get a list of module names.
| Type: | String[] |
| Position: | 0 |
| Default value: | None |
| Required: | True |
| Accept pipeline input: | True |
| Accept wildcard characters: | False |
-Repository
Use the Repository parameter to specify which repository is used to download and install a
module. Used when multiple repositories are registered. Specifies the name of a registered
repository in the Install-Module command. To register a repository, use Register-PSRepository.
To display registered repositories, use Get-PSRepository.
| Type: | String[] |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-RequiredVersion
Specifies the exact version of a single module to install. If there is no match in the repository
for the specified version, an error is displayed. If you want to install multiple modules, you
cannot use RequiredVersion. RequiredVersion cannot be used in the same Install-Module
command as MinimumVersion or MaximumVersion.
| Type: | String |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | True |
| Accept wildcard characters: | False |
-Scope
Specifies the installation scope of the module. The acceptable values for this parameter are AllUsers and CurrentUser.
The AllUsers scope installs modules in a location that is accessible to all users of the computer:
$env:ProgramFiles\WindowsPowerShell\Modules
The CurrentUser installs modules in a location that is accessible only to the current user of the computer:
$home\Documents\WindowsPowerShell\Modules
When no Scope is defined, the default is 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, the Scope is CurrentUser.
- For non-elevated PowerShell sessions in PowerShellGet versions 1.6.7 and earlier, Scope is
undefined, and
Install-Modulefails.
| Type: | String |
| Accepted values: | AllUsers, CurrentUser |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-WhatIf
Shows what would happen if an Install-Module command was run. The cmdlet is not run.
| Type: | SwitchParameter |
| Aliases: | wi |
| Position: | Named |
| Default value: | False |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
Inputs
PSRepositoryItemInfo
Find-Module creates PSRepositoryItemInfo objects that can be sent down the pipeline to
Install-Module.
Notes
Install-Module runs on PowerShell 5.0 or later releases, on Windows 7 or Windows 2008 R2 and later
releases of Windows.
As a security best practice, evaluate a module's code before running any cmdlets or functions for the first time. To prevent running modules that contain malicious code, installed modules are not automatically imported after installation.
If the module name specified by the Name parameter does not exist in the repository,
Install-Module returns an error.
To install multiple modules, use the Name parameter and specify a comma-separated array of
module names. If you specify multiple module names, you cannot use MinimumVersion,
MaximumVersion, or RequiredVersion. Find-Module creates PSRepositoryItemInfo objects
that can be sent down the pipeline to Install-Module. The pipeline is another way to specify
multiple modules to install in a single command.
By default, modules for the scope of AllUsers are installed in
$env:ProgramFiles\WindowsPowerShell\Modules. The default prevents confusion when you install
PowerShell Desired State Configuration (DSC) resources.
A module installation fails and cannot be imported if it does not have a .psm1, .psd1, or .dll
of the same name within the folder. Use the Force parameter to install the module.
If an existing module's version matches the name specified by the Name parameter, and the
MinimumVersion or RequiredVersion parameter are not used, Install-Module silently
continues but does not install the module.
If an existing module's version is greater than the value of the MinimumVersion parameter, or
equal to the value of the RequiredVersion parameter, Install-Module silently continues but
does not install the module.
If the existing module does not match the values specified by the MinimumVersion or
RequiredVersion parameters, an error occurs in the Install-Module command. For example, if the
version of the existing installed module is lower than the MinimumVersion value or not equal to
the RequiredVersion value.