Installing Amazon Tools for PowerShell on Linux or macOS - Amazon Tools for PowerShell
Overview of SetupPrerequisitesInstall AWS.ToolsInstall AWSPowerShell.NetCoreScript ExecutionConfiguring the PowerShell ConsoleInitialize Your PowerShell SessionVersioningUpdating the Amazon Tools for PowerShell on Linux or macOSRelated Information
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Installing Amazon Tools for PowerShell on Linux or macOS

This topic provides instructions on how to install the Amazon Tools for PowerShell on Linux or macOS.

Overview of Setup

To install Amazon Tools for PowerShell on a Linux or macOS computer, you can choose from two package options:

  • AWS.Tools – The modularized version of Amazon Tools for PowerShell. Each Amazon service is supported by its own individual, small module, with shared support modules AWS.Tools.Common.

  • AWSPowerShell.NetCore – The single, large-module version of Amazon Tools for PowerShell. All Amazon services are supported by this single, large module.

Setting either of these up on a computer running Linux or macOS involves the following tasks, described in detail later in this topic:

  1. Install PowerShell Core 6.0 or later on a supported system.

  2. After installing PowerShell Core, start PowerShell by running pwsh in your system shell.

  3. Install either AWS.Tools or AWSPowerShell.NetCore.

  4. Run the appropriate Import-Module cmdlet to import the module into your PowerShell session.

  5. Run the Initialize-AWSDefaultConfiguration cmdlet to provide your Amazon credentials.

Prerequisites

Ensure that you meet the requirements listed on Prerequisites for Setting up the Amazon Tools for PowerShell.

To run the Amazon Tools for PowerShell Core, your computer must be running PowerShell Core 6.0 or later.

  • For a list of supported Linux platform releases and for information about how to install the latest version of PowerShell on a Linux-based computer, see Installing PowerShell on Linux on Microsoft's website. Some Linux-based operating systems, such as Arch, Kali, and Raspbian, are not officially supported, but have varying levels of community support.

  • For information about supported macOS versions and about how to install the latest version of PowerShell on macOS, see Installing PowerShell on macOS on Microsoft's website.

Install AWS.Tools on Linux or macOS

You can install the modularized version of Amazon Tools for PowerShell on computers that are running PowerShell Core 6.0 or later. For information about how to install PowerShell Core, see Installing various versions of PowerShell on the Microsoft PowerShell website.

You can install AWS.Tools in one of three ways:

  • Using the cmdlets in the AWS.Tools.Installer module. The AWS.Tools.Installer module simplifies the installation and update of other AWS.Tools modules. AWS.Tools.Installer requires, automatically downloads and installs, an updated version of PowerShellGet. The AWS.Tools.Installer module also automatically keeps your module versions in sync. When you install or update to a newer version of one module, the cmdlets in the AWS.Tools.Installer automatically update all of your other AWS.Tools modules to the same version.

  • Downloading the modules from AWS.Tools.zip and extracting them in one of the module directories. You can discover your module directories by printing the value of the $Env:PSModulePath variable.

  • Installing each service module from the PowerShell Gallery using the Install-Module cmdlet, as described in the following procedure.

To install AWS.Tools on Linux or macOS using the Install-Module cmdlet

  1. Start a PowerShell Core session by running the following command.

    $ pwsh
    Note

    We recommend that you don't run PowerShell as an administrator with elevated permissions except when required by the task at hand. This is because of the potential security risk and is inconsistent with the principle of least privilege.

  2. To install the modularized AWS.Tools package using the AWS.Tools.Installer module, run the following command.

    PS > Install-Module -Name AWS.Tools.Installer

Untrusted repository
You are installing the modules from an untrusted repository. If you trust this repository, change its InstallationPolicy value by running the Set-PSRepository cmdlet. Are you sure
 you want to install the modules from 'PSGallery'?
[Y] Yes  [A] Yes to All  [N] No  [L] No to All  [S] Suspend  [?] Help (default is "N"): y

    If you are notified that the repository is "untrusted", you're asked if you want to install anyway. Enter y to allow PowerShell to install the module. To avoid the prompt and install the module without trusting the repository, you can run the following command.

    PS > Install-Module -Name AWS.Tools.Installer -Force

  3. You can now install the module for each service that you want to use. For example, the following command installs the IAM module. This command also installs any dependent modules that are required for the specified module to work. For example, when you install your first AWS.Tools service module, it also installs AWS.Tools.Common. This is a shared module required by all Amazon service modules. It also removes older versions of the modules, and updates other modules to the same newer version.

    PS > Install-AWSToolsModule AWS.Tools.EC2,AWS.Tools.S3 -CleanUp
Confirm
Are you sure you want to perform this action?
  Performing the operation "Install-AWSToolsModule" on target "AWS Tools version 4.0.0.0".
  [Y] Yes  [A] Yes to All  [N] No  [L] No to All  [S] Suspend  [?] Help (default is "Y"):

  Installing module AWS.Tools.Common version 4.0.0.0
  Installing module AWS.Tools.EC2 version 4.0.0.0
  Installing module AWS.Tools.Glacier version 4.0.0.0
  Installing module AWS.Tools.S3 version 4.0.0.0

  Uninstalling AWS.Tools version 3.3.618.0
  Uninstalling module AWS.Tools.Glacier
  Uninstalling module AWS.Tools.S3
  Uninstalling module AWS.Tools.SimpleNotificationService
  Uninstalling module AWS.Tools.SQS
  Uninstalling module AWS.Tools.Common
    Note

    The Install-AWSToolsModule cmdlet downloads all requested modules from the PSRepository named PSGallery (https://www.powershellgallery.com/) and considers the repository as a trusted source. Use the command Get-PSRepository -Name PSGallery for more information about this PSRepository.

    By default, this installs modules into the $home\Documents\PowerShell\Modules folder. To install the AWS.Tools module for all users of a computer, you must run the following command in a PowerShell session that you started as an administrator. This installs modules to the $env:ProgramFiles\PowerShell\Modules folder that is accessible by all users.

    PS > Install-AWSToolsModule -Name AWS.Tools.IdentityManagement -Scope AllUsers

Install AWSPowerShell.NetCore on Linux or macOS

To upgrade to a newer release of AWSPowerShell.NetCore, follow the instructions in Updating the Amazon Tools for PowerShell on Linux or macOS. Uninstall earlier versions of AWSPowerShell.NetCore first.

You can install AWSPowerShell.NetCore in one of two ways:

  • Downloading the module from AWSPowerShell.NetCore.zip and extracting it in one of the module directories. You can discover your module directories by printing the value of the $Env:PSModulePath variable.

  • Installing from the PowerShell Gallery using the Install-Module cmdlet as described in the following procedure.

To install AWSPowerShell.NetCore on Linux or macOS using the Install-Module cmdlet

Start a PowerShell Core session by running the following command.

$ pwsh
Note

We recommend that you don't start PowerShell by running sudo pwsh to run PowerShell with elevated, administrator rights. This is because of the potential security risk and is inconsistent with the principle of least privilege.

To install the AWSPowerShell.NetCore single-module package from the PowerShell Gallery, run the following command.

PS > Install-Module -Name AWSPowerShell.NetCore

Untrusted repository
You are installing the modules from an untrusted repository. If you trust this repository, change its InstallationPolicy value by running the Set-PSRepository cmdlet. Are you sure
 you want to install the modules from 'PSGallery'?
[Y] Yes  [A] Yes to All  [N] No  [L] No to All  [S] Suspend  [?] Help (default is "N"): y

If you are notified that the repository is "untrusted", you're asked if you want to install anyway. Enter y to allow PowerShell to install the module. To avoid the prompt without trusting the repository, you can run the following command.

PS > Install-Module -Name AWSPowerShell.NetCore -Force

You don't have to run this command as root, unless you want to install the Amazon Tools for PowerShell for all users of a computer. To do this, run the following command in a PowerShell session that you have started with sudo pwsh.

PS > Install-Module -Scope AllUsers -Name AWSPowerShell.NetCore -Force

Script Execution

The Set-ExecutionPolicy command isn't available on non-Windows systems. You can run Get-ExecutionPolicy, which shows that the default execution policy setting in PowerShell Core running on non-Windows systems is Unrestricted. For more information, see About Execution Policies on the Microsoft Technet website.

Because the PSModulePath includes the location of the Amazon module's directory, the Get-Module -ListAvailable cmdlet shows the module that you installed.

AWS.Tools

PS > Get-Module -ListAvailable

    Directory: /Users/username/.local/share/powershell/Modules

ModuleType Version    Name                                PSEdition ExportedCommands
---------- -------    ----                                --------- ----------------
Binary     3.3.563.1  AWS.Tools.Common                    Desk      {Clear-AWSHistory, Set-AWSHistoryConfiguration, Initialize-AWSDefaultConfiguration, Clear-AWSDefaultConfigurat…

AWSPowerShell.NetCore

PS > Get-Module -ListAvailable

Directory: /Users/username/.local/share/powershell/Modules

ModuleType Version    Name                                ExportedCommands
---------- -------    ----                                ----------------
Binary     3.3.563.1  AWSPowerShell.NetCore

Configure a PowerShell Console to Use the Amazon Tools for PowerShell Core (AWSPowerShell.NetCore Only)

PowerShell Core typically loads modules automatically whenever you run a cmdlet in the module. But this doesn't work for AWSPowerShell.NetCore because of its large size. To start running AWSPowerShell.NetCore cmdlets, you must first run the Import-Module AWSPowerShell.NetCore command. This isn't required for cmdlets in AWS.Tools modules.

Initialize Your PowerShell Session

When you start PowerShell on a Linux-based or macOS-based system after you have installed the Amazon Tools for PowerShell, you must run Initialize-AWSDefaultConfiguration to specify which Amazon access key to use. For more information about Initialize-AWSDefaultConfiguration, see Using Amazon Credentials.

Note

In earlier (before 3.3.96.0) releases of the Amazon Tools for PowerShell, this cmdlet was named Initialize-AWSDefaults.

Versioning

Amazon releases new versions of the Amazon Tools for PowerShell periodically to support new Amazon services and features. To determine the version of the Amazon Tools for PowerShell that you have installed, run the Get-AWSPowerShellVersion cmdlet.

PS > Get-AWSPowerShellVersion

Tools for PowerShell
Version 4.0.123.0
Copyright 2012-2019 Amazon.com, Inc. or its affiliates. All Rights Reserved.

Amazon Web Services SDK for .NET
Core Runtime Version 3.3.103.22
Copyright 2009-2015 Amazon.com, Inc. or its affiliates. All Rights Reserved.

Release notes: https://github.com/aws/aws-tools-for-powershell/blob/master/CHANGELOG.md

This software includes third party software subject to the following copyrights:
- Logging from log4net, Apache License
[http://logging.apache.org/log4net/license.html]

To see a list of the supported Amazon services in the current version of the tools, add the -ListServiceVersionInfo parameter to a Get-AWSPowerShellVersion cmdlet.

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

PS > $PSVersionTable
Name                           Value
----                           -----
PSVersion                      6.2.2
PSEdition                      Core
GitCommitId                    6.2.2
OS                             Darwin 18.7.0 Darwin Kernel Version 18.7.0: Tue Aug 20 16:57:14 PDT 2019; root:xnu-4903.271.2~2/RELEASE_X86_64
Platform                       Unix
PSCompatibleVersions           {1.0, 2.0, 3.0, 4.0…}
PSRemotingProtocolVersion      2.3
SerializationVersion           1.1.0.1
WSManStackVersion              3.0

Updating the Amazon Tools for PowerShell on Linux or macOS

Periodically, as updated versions of the Amazon Tools for PowerShell are released, you should update the version that you're running locally.

Update the Modularized AWS.Tools.*

To upgrade your AWS.Tools modules to the latest version, run the following command.

PS > Update-AWSToolsModule -CleanUp

This command updates all of the currently installed AWS.Tools modules and, for those modules that were successfully updated, removes the earlier versions.

Note

The Update-AWSToolsModule cmdlet downloads all modules from the PSRepository named PSGallery (https://www.powershellgallery.com/) and considers it a trusted source. Use the command Get-PSRepository -Name PSGallery for more information about this PSRepository.

Update the Tools for PowerShell Core

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 on the PowerShell Gallery website. We suggest you check every two to three weeks. Support for new commands and Amazon services is available only after you update to a version with that support.

Before you install a newer release of AWSPowerShell.NetCore, uninstall the existing module. Close any open PowerShell sessions before you uninstall the existing package. Run the following command to uninstall the package.

PS > Uninstall-Module -Name AWSPowerShell.NetCore -AllVersions

After the package is uninstalled, install the updated module by running the following command.

PS > Install-Module -Name AWSPowerShell.NetCore

After installation, run the command Import-Module AWSPowerShell.NetCore to load the updated cmdlets into your PowerShell session.

Related Information