Menu
AWS Tools for Windows PowerShell
User Guide

Setting up the AWS Tools for Windows PowerShell

Prerequisites

To use the AWS Tools for Windows PowerShell or the AWS Tools for PowerShell Core, you must have an AWS account. If you do not yet have an AWS account, see AWS Account and Access Keys for instructions on how to sign up.

To use the AWS Tools for Windows PowerShell, your installed system must meet the following prerequisites:

  • Microsoft Windows XP or later

  • Windows PowerShell 2.0 or later (PowerShell 5.1 or later for the Tools for PowerShell Core)

Windows 7 and Windows Server 2008 R2 come with Windows PowerShell 2.0 installed. Windows 8 and Windows Server 2012 come with Windows PowerShell 3.0 installed. For earlier releases of Windows, such as Windows XP, Windows Vista, Windows Server 2003, and Windows Server 2008, you can get PowerShell 2.0 by installing the Windows Management Framework.

Download and Install the AWS Tools for Windows PowerShell

Install the AWS Tools for Windows PowerShell on a Windows-based computer

The AWS Tools for Windows PowerShell is one of the optional components that you can install by running the AWS Tools for Windows installer .msi. Download the installer by opening the following webpage, and clicking AWS Tools for Windows.

The installer for the Tools for Windows PowerShell installs the most recent versions of the AWS SDK for .NET assemblies for the .NET 3.5 and 4.5 Frameworks. If you have Microsoft Visual Studio 2013 and/or 2015 installed, the installer can also install the AWS Toolkit for Visual Studio.

Users with PowerShell version 5 or higher can also install and update the Tools for Windows PowerShell from Microsoft's PowerShell Gallery website using the following command:

Copy
PS C:\> Install-Package -Name AWSPowerShell

All Windows Amazon Machine Images (AMIs) have the AWS Tools for Windows PowerShell pre-installed.

Install the AWS Tools for PowerShell Core

The AWS Tools for PowerShell Core can be installed on computers that are running Microsoft PowerShell 5.1 or a later release of PowerShell. AWS Tools for PowerShell Core is therefore supported on the following operating systems. For more information about how to install PowerShell 5.1 on computers that do not run Windows, see Package installation instructions (Linux) in the GitHub repository for the Microsoft PowerShell project. For more information about how to install PowerShell 5.1 on computers that run Windows 8.1 or Windows 10, see Package installation instructions (Windows), also in the GitHub repository for PowerShell.

  • Ubuntu 14.04 LTS and later

  • CentOS Linux 7

  • Mac OS X

  • Windows 8.1 Enterprise

  • Windows Server 2012 R2

  • Windows 10 for Business

After you have PowerShell 5.1 installed, you can find the AWS Tools for PowerShell Core on Microsoft's PowerShell Gallery website. The simplest way to install the Tools for PowerShell Core is by running the Install-Package cmdlet.

Copy
PS C:\> Install-Package -Name AWSPowerShell.NetCore

Some users have reported issues with the Install-Module cmdlet built into earlier versions PowerShell Core with errors related to semantic versioning (see https://github.com/OneGet/oneget/issues/202). Using the NuGet provider appears to resolve the issue. Later versions of PowerShell Core have resolved this issue.

To install using the NuGet provider run this command, setting an appropriate destination folder (on Linux for example try -Destination ~/.local/share/powershell/Modules):

Copy
PS C:\> Install-Package -Name AWSPowerShell.NetCore -Source https://www.powershellgallery.com/api/v2/ -ProviderName NuGet -ExcludeVersion -Destination <path to destination folder>

For more information about the release of AWS Tools for PowerShell Core, see the AWS blog post, Introducing AWS Tools for PowerShell Core Edition.

Enable Script Execution

To load the AWS Tools for Windows PowerShell module, enable PowerShell script execution if you have not already done so. To enable script execution, run the Set-ExecutionPolicy cmdlet to set a policy of RemoteSigned. By default, PowerShell uses a policy of Restricted. For more information about execution policies, see Microsoft's TechNet documentation.

To enable script execution

  1. Administrator rights are required to set the execution policy. If you are not logged on as a user with administrator rights, open a PowerShell session as Administrator: Click Start and then click All Programs; click Accessories, and then click Windows PowerShell; now right-click Windows PowerShell, and then choose Run as administrator from the context menu.

  2. At the command prompt, type: Set-ExecutionPolicy RemoteSigned

Note

On a 64-bit system, you must also perform these steps for the 32-bit version of PowerShell, Windows PowerShell (x86).

If you do not have the execution policy set correctly, PowerShell generates the following message.

Copy
File C:\Users\teslan\Documents\WindowsPowerShell\Microsoft.PowerShell_profile.ps1 cannot be loaded because the execution of scripts is disabled on this system. Please see "get-help about_signing" for more details. At line:1 char:2 + . <<<< 'C:\Users\teslan\Documents\WindowsPowerShell\Microsoft.PowerShell_profile.ps1' + CategoryInfo : NotSpecified: (:) [], PSSecurityException + FullyQualifiedErrorId : RuntimeException

The installer for the Tools for Windows PowerShell updates the PSModulePath to include the location of the directory that contains the AWSPowerShell module. As a result, if you are running PowerShell 3.0, the AWSPowerShell module is loaded automatically whenever you run one of the AWS cmdlets. This lets you use the AWS cmdlets interactively, even if the execution policy on your system is set to disallow script execution.

Because the PSModulePath includes the location of the AWS module's directory, the Get-Module -ListAvailable cmdlet shows the module.

Copy
PS C:\> Get-Module -ListAvailable ModuleType Name ExportedCommands ---------- ---- ---------------- Manifest AppLocker {} Manifest BitsTransfer {} Manifest PSDiagnostics {} Manifest TroubleshootingPack {} Manifest AWSPowerShell {Update-EBApplicationVersion, Set-DPStatus, Remove-IAMGroupPol...

Configure a PowerShell Console to Use the AWS Tools for Windows PowerShell

The installer creates a Start Menu group called, Amazon Web Services, which contains a shortcut called Windows PowerShell for AWS. For PowerShell 2.0, this shortcut automatically imports the AWSPowerShell module and then runs the Initialize-AWSDefaultConfiguration cmdlet. For PowerShell 3.0, the AWSPowerShell module is loaded automatically whenever you run an AWS cmdlet. So, for PowerShell 3.0, the shortcut created by the installer only runs the Initialize-AWSDefaultConfiguration cmdlet. For more information about Initialize-AWSDefaultConfiguration, see Using AWS Credentials. In earlier (pre-v3.3.96.0) versions of the modules this cmdlet was named Initialize-AWSDefaults.

The installer also creates an additional shortcut called AWS Tools for Windows, which opens a visual display of AWS resources for Windows developers.

If you run PowerShell 3.0, or if you only use the shortcut installed by the installer, you do not need to configure a PowerShell window to use the AWS Tools for Windows PowerShell. However, if, for example, you use PowerShell 2.0 with a specially-configured PowerShell console, and you want to add support for the tools, you must load the AWS module yourself.

How to Load the AWS Tools for Windows PowerShell Module (PowerShell 2.0)

To load the Powershell Tools module into your current session

  1. Open a PowerShell prompt and type the following command:

    Copy
    PS C:\> Import-Module "C:\Program Files (x86)\AWS Tools\PowerShell\AWSPowerShell\AWSPowerShell.psd1"

    Note

    In PowerShell 4.0 and later releases, Import-Module also searches the Program Files folder for installed modules, so it is not necessary to provide the full path to the module. You can run the following command to import the AWSPowerShell module. In PowerShell 3.0 and later, running a cmdlet in the module also automatically imports a module into your session.

    Copy
    PS C:\> Import-Module AWSPowerShell
  2. To verify that the module was loaded, type the following command:

    Copy
    PS C:\> Get-Module

    If you see an entry in the list named AWSPowerShell, then the Tools for Windows PowerShell module was loaded successfully.

    Copy
    ModuleType Version Name ExportedCommands ---------- ------- ---- ---------------- Binary 3.3.96.0 AWSPowerShell {Add-AASScalableTarget, Add-ACMCertificateTag, Add-ADSConfigurationItemsToApplication, Add-ASAAttachmentsToSet...} ...

Load AWS Tools for Windows PowerShell Module into Every Session (PowerShell 2.0)

To load the AWSPowerShell module automatically every time you start a PowerShell session, add it to your PowerShell profile. Note, however, that adding commands to your PowerShell profile can slow down the speed at which a PowerShell session starts.

The PowerShell $profile variable contains the full path to the text file that contains your PowerShell profile. This variable is available only in a PowerShell session; it is not a Windows environment variable. To view the value of this variable, run echo.

Copy
echo $profile C:\Users\{username}\Documents\WindowsPowerShell\Microsoft.PowerShell_profile.ps1

You can edit this file with any text editor, such as notepad.exe.

Copy
notepad $profile

You might need to create both the profile directory and the profile itself if they do not already exist.

Versioning

New versions of the Tools for Windows PowerShell release periodically to support new AWS services and features. To see what version of the Tools for Windows PowerShell you have installed, run the Get-AWSPowerShellVersion cmdlet:

Copy
PS C:\> Get-AWSPowerShellVersion AWS Tools for Windows PowerShell Version 3.3.96.0 Copyright 2012-2017 Amazon.com, Inc. or its affiliates. All Rights Reserved. Amazon Web Services SDK for .NET Core Runtime Version 3.3.14.0 Copyright 2009-2015 Amazon.com, Inc. or its affiliates. All Rights Reserved. Release notes: https://aws.amazon.com/releasenotes/PowerShell This software includes third party software subject to the following copyrights: - Logging from log4net, Apache License [http://logging.apache.org/log4net/license.html]

You can also specify the -ListServiceVersionInfo parameter of Get-AWSPowerShellVersion to see a list of which AWS services are supported in the current version of the tools.

Copy
PS C:\> Get-AWSPowerShellVersion -ListServiceVersionInfo AWS Tools for Windows PowerShell Version 3.3.96.0 Copyright 2012-2017 Amazon.com, Inc. or its affiliates. All Rights Reserved. Amazon Web Services SDK for .NET Core Runtime Version 3.3.14.0 Copyright 2009-2015 Amazon.com, Inc. or its affiliates. All Rights Reserved. Release notes: https://aws.amazon.com/releasenotes/PowerShell This software includes third party software subject to the following copyrights: - Logging from log4net, Apache License [http://logging.apache.org/log4net/license.html] Service Noun Prefix Version ------- ----------- ------- AWS AppStream APS 2016-12-01 AWS Batch BAT 2016-08-10 AWS Budgets BGT 2016-10-20 AWS Certificate Manager ACM 2015-12-08 AWS Cloud Directory CDIR 2016-05-10 AWS Cloud HSM HSM 2014-05-30 AWS CloudFormation CFN 2010-05-15 AWS CloudTrail CT 2013-11-01 AWS CodeBuild CB 2016-10-06 AWS CodeCommit CC 2015-04-13 AWS CodeDeploy CD 2014-10-06 AWS CodePipeline CP 2015-07-09 AWS CodeStar CST 2017-04-19 AWS Config CFG 2014-11-12 AWS Cost and Usage Report CUR 2017-01-06 AWS Data Pipeline DP 2012-10-29 AWS Database Migration Service DMS 2016-01-01 AWS Device Farm DF 2015-06-23 AWS Direct Connect DC 2012-10-25 AWS Directory Service DS 2015-04-16 AWS Elastic Beanstalk EB 2010-12-01 AWS Health HLTH 2016-08-04 AWS Identity and Access Management IAM 2010-05-08 AWS Import/Export IE 2010-06-01 AWS Import/Export Snowball SNOW 2016-06-30 AWS IoT IOT 2015-05-28 AWS Key Management Service KMS 2014-11-01 AWS Marketplace Commerce Analytics MCA 2015-07-01 AWS Marketplace Entitlement Service MES 2017-01-11 AWS Marketplace Metering MM 2016-01-14 AWS OpsWorks OPS 2013-02-18 AWS OpsWorksCM OWCM 2016-11-01 AWS Organizations ORG 2016-11-28 AWS Resource Groups Tagging API RGT 2017-01-26 AWS Security Token Service STS 2011-06-15 AWS Service Catalog SC 2015-12-10 AWS Shield SHLD 2016-06-02 AWS Storage Gateway SG 2013-06-30 AWS Support API ASA 2013-04-15 AWS WAF WAF 2015-08-24 AWS WAF Regional WAFR 2016-11-28 AWS X-Ray XR 2016-04-12 Amazon API Gateway AG 2015-07-09 Amazon Athena ATH 2017-05-18 Amazon CloudFront CF 2017-03-25 Amazon CloudSearch CS 2013-01-01 Amazon CloudSearchDomain CSD 2013-01-01 Amazon CloudWatch CW 2010-08-01 Amazon CloudWatch Events CWE 2015-10-07 Amazon CloudWatch Logs CWL 2014-03-28 Amazon Cognito Identity CGI 2014-06-30 Amazon Cognito Identity Provider CGIP 2016-04-18 Amazon DynamoDB DDB 2012-08-10 Amazon EC2 Container Registry ECR 2015-09-21 Amazon EC2 Container Service ECS 2014-11-13 Amazon ElastiCache EC 2015-02-02 Amazon Elastic Compute Cloud EC2 2016-11-15 Amazon Elastic File System EFS 2015-02-01 Amazon Elastic MapReduce EMR 2009-03-31 Amazon Elastic Transcoder ETS 2012-09-25 Amazon Elasticsearch ES 2015-01-01 Amazon GameLift Service GML 2015-10-01 Amazon Inspector INS 2016-02-16 Amazon Kinesis KIN 2013-12-02 Amazon Kinesis Analytics KINA 2015-08-14 Amazon Kinesis Firehose KINF 2015-08-04 Amazon Lambda LM 2015-03-31 Amazon Lex LEX 2016-11-28 Amazon Lex Model Building Service LMB 2017-04-19 Amazon Lightsail LS 2016-11-28 Amazon MTurk Service MTR 2017-01-17 Amazon Machine Learning ML 2014-12-12 Amazon Pinpoint PIN 2016-12-01 Amazon Polly POL 2016-06-10 Amazon Redshift RS 2012-12-01 Amazon Rekognition REK 2016-06-27 Amazon Relational Database Service RDS 2014-10-31 Amazon Route 53 R53 2013-04-01 Amazon Route 53 Domains R53D 2014-05-15 Amazon Server Migration Service SMS 2016-10-24 Amazon Simple Email Service SES 2010-12-01 Amazon Simple Notification Service SNS 2010-03-31 Amazon Simple Queue Service SQS 2012-11-05 Amazon Simple Storage Service S3 2006-03-01 Amazon Simple Systems Management SSM 2014-11-06 Amazon Step Functions SFN 2016-11-23 Amazon WorkDocs WD 2016-05-01 Amazon WorkSpaces WKS 2015-04-08 Application Auto Scaling AAS 2016-02-06 Application Discovery Service ADS 2015-11-01 Auto Scaling AS 2011-01-01 Elastic Load Balancing ELB 2012-06-01 Elastic Load Balancing V2 ELB2 2015-12-01

To determine the version of PowerShell that you are running, enter $PSVersionTable to view the contents of the $PSVersionTable automatic variable.

Copy
PS C:\> $PSVersionTable Name Value ---- ----- PSVersion 5.0.10586.117 PSCompatibleVersions {1.0, 2.0, 3.0, 4.0...} BuildVersion 10.0.10586.117 CLRVersion 4.0.30319.34209 WSManStackVersion 3.0 PSRemotingProtocolVersion 2.3 SerializationVersion 1.1.0.1

Updating the AWS Tools for Windows PowerShell and AWS Tools for PowerShell Core

Periodically, as updated versions of the Tools for Windows PowerShell or Tools for PowerShell Core are released, you'll want to update the version that you are running locally. Run the Get-AWSPowerShellVersion cmdlet to determine the version that you are running, and compare that with the version of Tools for Windows PowerShell that is available at AWS Tools for Windows PowerShell or PowerShell Gallery. A suggested time period for checking for an updated AWS Tools for PowerShell package is every two to three weeks.

Update the Tools for Windows PowerShell

Update your installed Tools for Windows PowerShell by downloading the most recent version of the MSI package from AWS Tools for Windows PowerShell and comparing the package version number in the MSI file name with the version number you get when you run the Get-AWSPowerShellVersion cmdlet.

If the download version is a higher number than the version you have installed, close all Tools for Windows PowerShell consoles, then uninstall AWS Tools for Windows by selecting it in the Control Panel | Programs and Features | Uninstall a program dialog box, and then clicking Uninstall. Wait for uninstallation to finish.

Install the newer version of the Tools for Windows PowerShell by running the MSI package you downloaded.

Update the Tools for PowerShell Core

Before you install a newer release of the AWS Tools for PowerShell Core, uninstall the existing package. Close any open PowerShell or AWS Tools for PowerShell sessions before you uninstall the existing Tools for PowerShell Core package. Run the following command to uninstall the package.

Copy
PS C:\> Uninstall-Package -Name AWSPowerShell.NetCore -AllVersions

When uninstallation is finished, install the updated package by running the following command. By default, this command installs the latest version of the AWS Tools for PowerShell Core. This package is available on the PowerShell Gallery, but the easiest method of installation is to run Install-Package.

Copy
PS C:\> Install-Package -Name AWSPowerShell.NetCore -ProviderName NuGet -Destination <path to destination folder>

See Also