Install-Script

Installs a script.

Syntax

Install-Script
       [-Name] <String[]>
       [-MinimumVersion <String>]
       [-MaximumVersion <String>]
       [-RequiredVersion <String>]
       [-Repository <String[]>]
       [-Scope <String>]
       [-NoPathUpdate]
       [-Proxy <Uri>]
       [-ProxyCredential <PSCredential>]
       [-Credential <PSCredential>]
       [-Force]
       [-AllowPrerelease]
       [-AcceptLicense]
       [-PassThru]
       [-WhatIf]
       [-Confirm]
       [<CommonParameters>]
Install-Script
       [-InputObject] <PSObject[]>
       [-Scope <String>]
       [-NoPathUpdate]
       [-Proxy <Uri>]
       [-ProxyCredential <PSCredential>]
       [-Credential <PSCredential>]
       [-Force]
       [-AcceptLicense]
       [-PassThru]
       [-WhatIf]
       [-Confirm]
       [<CommonParameters>]

Description

The Install-Script cmdlet acquires a script payload from a repository, verifies that the payload is a valid PowerShell script, and copies the script file to a specified installation location.

The default repositories Install-Script operates against are configurable through the Register-PSRepository, Set-PSRepository, Unregister-PSRepository, and Get-PSRepository cmdlets. When operating against multiple repositories, Install-Script installs the first script that matches the specified search criteria (Name, MinimumVersion, or MaximumVersion) from the first repository without any error.

Examples

Example 1: Find a script and install it

PS C:\> Find-Script -Repository "Local1" -Name "Required-Script2"
Version    Name                           Type       Repository           Description
-------    ----                           ----       ----------           -----------
2.5        Required-Script2               Script     local1               Description for the Required-Script2 script

PS C:\> Find-Script -Repository "Local1" -Name "Required-Script2" | Install-Script
PS C:\> Get-Command -Name "Required-Script2"
CommandType     Name                      Version    Source
-----------     ----                      -------    ------
ExternalScript  Required-Script2.ps1      2.0       C:\Users\pattif\Documents\WindowsPowerShell\Scripts\Required-Script2.ps1

PS C:\> Get-InstalledScript -Name "Required-Script2"
Version    Name                  Type     Repository           Description
-------    ----                  ----     ----------           -----------
2.5        Required-Script2      Script   local1               Description for the Required-Script2 script

PS C:\> Get-InstalledScript -Name "Required-Script2" | Format-List *
Name                       : Required-Script2
Version                    : 2.5
Type                       : Script
Description                : Description for the Required-Script2 script
Author                     : pattif
CompanyName                :
Copyright                  : 2015 Microsoft Corporation. All rights reserved.
PublishedDate              : 8/15/2015 12:42:39 AM
LicenseUri                 : http://required-script2.com/license
ProjectUri                 : http://required-script2.com/
IconUri                    : http://required-script2.com/icon
Tags                       : {Tag1, Tag2, Tag-Required-Script2-2.5, PSScript...}
Includes                   : {Function, DscResource, Cmdlet, Command}
PowerShellGetFormatVersion :
ReleaseNotes               : Required-Script2 release notes
Dependencies               : {}
RepositorySourceLocation   : http://pattif-dev:8765/api/v2/
Repository                 : local1
PackageManagementProvider  : NuGet
InstalledLocation          : C:\Users\pattif\Documents\WindowsPowerShell\Scripts

The first command finds the script named Required-Script2 from the Local1 repository and displays the results.

The second command finds the Required-Script2 script, and then uses the pipeline operator to pass it to the Install-Script cmdlet to install it.

The third command uses the Get-Command cmdlet to get Required-Script2, and then displays the results.

The fourth command uses the Get-InstalledScript cmdlet to get Required-Script2 and display the results.

The fifth command gets Required-Script2 and uses the pipeline operator to pass it to the Format-List cmdlet to format the output.

Example 2: Install a script with AllUsers scope

PS C:\> Install-Script -Repository "Local1" -Name "Required-Script3" -Scope "AllUsers"
PS C:\> Get-InstalledScript -Name "Required-Script3"
Version    Name                  Type       Repository    Description
-------    ----                  ----       ----------    -----------
2.5        Required-Script3      Script     local1        Description for the Required-Script3 script

PS C:\> Get-InstalledScript -Name "Required-Script3" | Format-List *
Name                       : Required-Script3
Version                    : 2.5
Type                       : Script
Description                : Description for the Required-Script3 script
Author                     : pattif
CompanyName                :
Copyright                  : 2015 Microsoft Corporation. All rights reserved.
PublishedDate              : 8/15/2015 12:42:45 AM
LicenseUri                 : http://required-script3.com/license
ProjectUri                 : http://required-script3.com/
IconUri                    : http://required-script3.com/icon
Tags                       : {Tag1, Tag2, Tag-Required-Script3-2.5, PSScript...}
Includes                   : {Function, DscResource, Cmdlet, Command}
PowerShellGetFormatVersion :
ReleaseNotes               : Required-Script3 release notes
Dependencies               : {}
RepositorySourceLocation   : http://pattif-dev:8765/api/v2/
Repository                 : local1
PackageManagementProvider  : NuGet
InstalledLocation          : C:\Program Files\WindowsPowerShell\Scripts

The first command installs the script named Required-Script3 and assigns it AllUsers scope.

The second command gets the installed script Required-Script3 and displays information about it.

The third command gets Required-Script3 and uses the pipeline operator to pass it to the Format-List cmdlet to format the output.

Example 3: Install a script and its dependencies

PS C:\> Find-Script -Repository "Local1" -Name "Script-WithDependencies2" -IncludeDependencies
Version    Name                        Type       Repository    Description
-------    ----                        ----       ----------    -----------
2.0        Script-WithDependencies2    Script     local1        Description for the Script-WithDependencies2 script
2.5        RequiredModule1             Module     local1        RequiredModule1 module
2.5        RequiredModule2             Module     local1        RequiredModule2 module
2.5        RequiredModule3             Module     local1        RequiredModule3 module
2.5        Required-Script1            Script     local1        Description for the Required-Script1 script
2.5        Required-Script2            Script     local1        Description for the Required-Script2 script
2.5        Required-Script3            Script     local1        Description for the Required-Script3 script

PS C:\> Install-Script -Repository "Local1" -Name "Script-WithDependencies2"
PS C:\> Get-InstalledScript
Version    Name                        Type       Repository    Description
-------    ----                        ----       ----------    -----------
2.5        Required-Script1            Script     local1        Description for the Required-Script1 script
2.5        Required-Script2            Script     local1        Description for the Required-Script2 script
2.5        Required-Script3            Script     local1        Description for the Required-Script3 script
2.0        Script-WithDependencies2    Script     local1        Description for the Script-WithDependencies2 script

PS C:\> Get-InstalledModule
Version    Name                        Type       Repository    Description
-------    ----                        ----       ----------    -----------
2.5        RequiredModule1             Module     local1        RequiredModule1 module
2.5        RequiredModule2             Module     local1        RequiredModule2 module
2.5        RequiredModule3             Module     local1        RequiredModule3 module

PS C:\> Find-Script -Repository "Local1" -Name "Required-Script*"
Version    Name                        Type       Repository    Description
-------    ----                        ----       ----------    -----------
2.5        Required-Script1            Script     local1        Description for the Required-Script1 script
2.5        Required-Script2            Script     local1        Description for the Required-Script2 script
2.5        Required-Script3            Script     local1        Description for the Required-Script3 script

PS C:\> Install-Script -Repository "Local1" -Name "Required-Script*"
PS C:\> Get-InstalledScript
Version    Name                        Type       Repository    Description
-------    ----                        ----       ----------    -----------
2.5        Required-Script1            Script     local1        Description for the Required-Script1 script
2.5        Required-Script2            Script     local1        Description for the Required-Script2 script
2.5        Required-Script3            Script     local1        Description for the Required-Script3 script

The first command finds the script named Script-WithDependencies2 and its dependencies in the Local1 repository and displays the results.

The second command installs Script-WithDependencies2.

The third command uses the Get-InstalledScript script cmdlet to get installed scripts and display the results.

The fourth command uses the Get-InstalledModule cmdlet to get installed modules and display the results.

The fifth command uses the Find-Script cmdlet to find scripts where the name begins with Required-Script and display the results.

The sixth command installs the scripts where the name begins with Required-Script in the Local1 repository.

The final command gets installed scripts and displays the results.

Parameters

-AcceptLicense

Automatically accept the license agreement during installation if the module requires it.

Type:SwitchParameter
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-AllowPrerelease

Allows you to install a script marked as a prerelease.

Type:SwitchParameter
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-Confirm

Prompts you for confirmation before running the cmdlet.

Type:SwitchParameter
Aliases:cf
Position:Named
Default value:False
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-Credential

Specifies a user account that has rights to install a script for a specified package provider or source.

Type:PSCredential
Position:Named
Default value:None
Required:False
Accept pipeline input:True
Accept wildcard characters:False

-Force

Forces the command to run without asking for user confirmation.

Type:SwitchParameter
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-InputObject

Used for pipeline input. An error is thrown if a value supplied directly to InputObject. Use the pipeline to pass objects with the InputObject parameter.

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 scripts to install. You cannot add this parameter if you are attempting to install multiple scripts. 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
Required:False
Accept pipeline input:True
Accept wildcard characters:False

-MinimumVersion

Specifies the minimum version of a single script to install. You cannot add this parameter if you are attempting to install multiple scripts. 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
Required:False
Accept pipeline input:True
Accept wildcard characters:False

-Name

Specifies an array of names of scripts to install.

Type:String[]
Position:0
Default value:None
Required:True
Accept pipeline input:True
Accept wildcard characters:False

-NoPathUpdate

Type:SwitchParameter
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-PassThru

Type:SwitchParameter
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-Proxy

Specifies a proxy server for the request, rather than connecting directly to the Internet resource.

Type:Uri
Position:Named
Default value:None
Required:False
Accept pipeline input:True
Accept wildcard characters:False

-ProxyCredential

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
Required:False
Accept pipeline input:True
Accept wildcard characters:False

-Repository

Specifies the friendly name of a repository that has been registered with the Register-PSRepository cmdlet. The default is all registered repositories.

Type:String[]
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-RequiredVersion

Specifies the exact version number of the script to install.

Type:String
Position:Named
Default value:None
Required:False
Accept pipeline input:True
Accept wildcard characters:False

-Scope

Specifies the installation scope of the script. Valid values 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\Scripts.

The CurrentUser scope lets modules be installed only to $HOME\Documents\WindowsPowerShell\Scripts, 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
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-WhatIf

Shows what would happen if the cmdlet runs. 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

String[]

PSObject[]

String

Uri

PSCredential

Outputs

Object

Notes

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.