# Getting started with the AWS CLI This chapter provides steps to get started with version 2 of the AWS Command Line Interface (AWS CLI) and provides links to the relevant instructions. 1. **[Complete all prerequisites](getting-started-prereqs.md)** - To access AWS services with the AWS CLI, you need at minimum an AWS account and IAM credentials. To increase the security of your AWS account, we recommend that you do not use your root account credentials. You should create a user with least privilege to provide access credentials to the tasks you'll be running in AWS. 1. Install or gain access to the AWS CLI using one of the following methods: + **(Recommended)** [Installing or updating to the latest version of the AWS CLI](getting-started-install.md). + [Installing past releases of the AWS CLI version 2](getting-started-version.md). Installing a specific version is primarily used if your team aligns their tools to a specific version. + [Building and installing the AWS CLI from source](getting-started-source-install.md). Building the AWS CLI from GitHub source is a more in-depth method that is primarily used by customers who work on platforms that we do not directly support with our pre-built installers. + [Running the official Amazon ECR Public or Docker images for the AWS CLI](getting-started-docker.md). + Access the AWS CLI version 2 in the AWS console from your browser using AWS CloudShell. For more information, see the [AWS CloudShell User Guide](https://docs.aws.amazon.com/cloudshell/latest/userguide/). 1. [After you have access to the AWS CLI, configure your AWS CLI with your IAM credentials for first time use](getting-started-quickstart.md). **Troubleshooting installer or configure errors** If you have issues after installing, uninstalling, or configuring the AWS CLI, see [Troubleshooting errors for the AWS CLI](cli-chap-troubleshooting.md) for troubleshooting steps. **Topics** + [ # Prerequisites to use the AWS CLI version 2 ](getting-started-prereqs.md) + [ # Installing or updating to the latest version of the AWS CLI ](getting-started-install.md) + [ # Installing past releases of the AWS CLI version 2 ](getting-started-version.md) + [ # Building and installing the AWS CLI from source ](getting-started-source-install.md) + [ # Running the official Amazon ECR Public or Docker images for the AWS CLI ](getting-started-docker.md) + [ # Setting up the AWS CLI ](getting-started-quickstart.md) # Prerequisites to use the AWS CLI version 2 To access AWS services with the AWS CLI, you need an AWS account with IAM or IAM Identity Center credentials. When running AWS CLI commands, the AWS CLI needs to have access to those AWS credentials. To increase the security of your AWS account, we recommend that you only use short-lived credentials when using root or IAM users. You should create a user with least privilege to provide access credentials to the tasks you'll be running in AWS. For information about best practices, see [Security best practices](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html#bp-users-federation-idp) in the IAM User Guide. **Topics** + [ ## Create an IAM or IAM Identity Center administrative account ](#getting-started-prereqs-iam) + [ ## Next steps ](#getting-started-prereqs-next) ## Create an IAM or IAM Identity Center administrative account Before you can configure the AWS CLI, you need to create an IAM or IAM Identity Center account. **Account creation options** | Choose a way to manage your credentials | To | How to create an account | How to configure programmatic access to the account | | --- | --- | --- | --- | | AWS Management Console credentials | Use short-term credentials corresponding to the root user created during initial account set up, an IAM user, or a federated identity from your identity provider. | Open [https://portal.aws.amazon.com/billing/signup](https://portal.aws.amazon.com/billing/signup) and follow the online instructions. | No additional steps are necessary. To sign in to the AWS CLI with your AWS account, see [Login for AWS local development using console credentials](cli-configure-sign-in.md) | | IAM Identity Center | Use short-term credentials to access AWS services. | Following the instructions in Getting started in the AWS IAM Identity Center User Guide. | Configure programmatic access by Configuring the to use in the AWS IAM Identity Center User Guide. | | AWS Identity and Access Management(Not recommended) | Use long-term credentials to access AWS services. | Following the instructions in Create an for emergency access in the IAM User Guide. | Configure programmatic access by Manage access keys for users in the IAM User Guide. | ## Next steps After creating an AWS account and IAM credentials, to use the AWS CLI you can do one of the following: + [Install the latest release](getting-started-install.md) of the AWS CLI version 2 on your computer. + [Install a past release](getting-started-version.md) of the AWS CLI version 2 on your computer. + Access the AWS CLI version 2 from your computer [using a Docker image.](getting-started-docker.md) + Access the AWS CLI version 2 in the AWS console from your browser using AWS CloudShell. For more information see the [AWS CloudShell User Guide](https://docs.aws.amazon.com/cloudshell/latest/userguide/). # Installing or updating to the latest version of the AWS CLI This topic describes how to install or update the latest release of the AWS Command Line Interface (AWS CLI) on supported operating systems. For information on the latest releases of AWS CLI, see the [AWS CLI version 2 Changelog](https://raw.githubusercontent.com/aws/aws-cli/v2/CHANGELOG.rst) on GitHub. To install a past release of the AWS CLI, see [Installing past releases of the AWS CLI version 2](getting-started-version.md). For uninstall instructions, see [Uninstalling the AWS CLI version 2](uninstall.md). **Important** AWS CLI versions 1 and 2 use the same `aws` command name. If you previously installed AWS CLI version 1, see [Migration guide for the AWS CLI version 2](cliv2-migration.md). **Topics** + [ ## AWS CLI install and update instructions ](#getting-started-install-instructions) + [ ## Troubleshooting AWS CLI install and uninstall errors ](#install-tshoot) + [ ## Next steps ](#install-next-steps) ## AWS CLI install and update instructions For installation instructions, expand the section for your operating system. ### Linux #### Install and update requirements + You must be able to extract or "unzip" the downloaded package. If your operating system doesn't have the built-in `unzip` command, use an equivalent. + The AWS CLI uses `glibc`, `groff`, and `less`. These are included by default in most major distributions of Linux. + We support the AWS CLI on 64-bit versions of recent distributions of CentOS, Fedora, Ubuntu, Amazon Linux 1, Amazon Linux 2, Amazon Linux 2023, and Linux ARM. + Because AWS doesn't maintain third-party repositories other than `snap`, we can’t guarantee that they contain the latest version of the AWS CLI. #### Install or update the AWS CLI **Warning** If this is your first time updating on Amazon Linux, to install the latest version of the AWS CLI, you must uninstall the pre-installed `yum` version using the following command: ``` $ sudo yum remove awscli ``` After the `yum` installation of the AWS CLI is removed, follow the below Linux install instructions. You can install the AWS CLI by using one of the following methods: + **The command line installer** is good option for version control, as you can specify the version to install. This option does not auto-update and you must download a new installer each time you update to overwrite previous version. + **The officially supported `snap` package** is a good option to always have the latest version of the AWS CLI as snap packages automatically refresh. There is no built-in support for selecting minor versions of AWS CLI and therefore is not an optimal install method if your team needs to pin versions. ------ #### [ Command line installer - Linux x86 (64-bit) ] To update your current installation of AWS CLI, download a new installer each time you update to overwrite previous versions. Follow these steps from the command line to install the AWS CLI on Linux. The following are quick installation steps in a single copy and paste group that provide a basic installation. For guided instructions, see the steps that follow. **Note** **(Optional)** The following command block downloads and installs the AWS CLI without first verifying the integrity of your download. To verify the integrity of your download, use the below step by step instructions. **To install** the AWS CLI, run the following commands. ``` $ curl "https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip" -o "awscliv2.zip" unzip awscliv2.zip sudo ./aws/install ``` **To update your current installation** of the AWS CLI, add your existing symlink and installer information to construct the `install` command using the `--bin-dir`, `--install-dir`, and `--update` parameters. The following command block uses an example symlink of */usr/local/bin* and example installer location of */usr/local/aws-cli* to install the AWS CLI locally for the current user. ``` $ curl "https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip" -o "awscliv2.zip" unzip awscliv2.zip sudo ./aws/install --bin-dir /usr/local/bin --install-dir /usr/local/aws-cli --update ``` **Guided installation steps** 1. Download the installation file in one of the following ways: + **Use the `curl` command** – The `-o` option specifies the file name that the downloaded package is written to. The options on the following example command write the downloaded file to the current directory with the local name `awscliv2.zip`. ``` $ curl "https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip" -o "awscliv2.zip" ``` + **Downloading from the URL** – To download the installer with your browser, use the following URL: [https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip](https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip) 1. **(Optional) Verifying the integrity of your downloaded zip file** If you chose to manually download the AWS CLI installer package `.zip` in the above steps, you can use the following steps to verify the signatures by using the `GnuPG` tool. The AWS CLI installer package `.zip` files are cryptographically signed using PGP signatures. If there is any damage or alteration of the files, this verification fails and you should not proceed with installation. 1. Download and install the `gpg` command using your package manager. For more information about `GnuPG`, see the [GnuPG website](https://www.gnupg.org/). 1. To create the public key file, create a text file and paste in the following text. ``` -----BEGIN PGP PUBLIC KEY BLOCK----- mQINBF2Cr7UBEADJZHcgusOJl7ENSyumXh85z0TRV0xJorM2B/JL0kHOyigQluUG ZMLhENaG0bYatdrKP+3H91lvK050pXwnO/R7fB/FSTouki4ciIx5OuLlnJZIxSzx PqGl0mkxImLNbGWoi6Lto0LYxqHN2iQtzlwTVmq9733zd3XfcXrZ3+LblHAgEt5G TfNxEKJ8soPLyWmwDH6HWCnjZ/aIQRBTIQ05uVeEoYxSh6wOai7ss/KveoSNBbYz gbdzoqI2Y8cgH2nbfgp3DSasaLZEdCSsIsK1u05CinE7k2qZ7KgKAUIcT/cR/grk C6VwsnDU0OUCideXcQ8WeHutqvgZH1JgKDbznoIzeQHJD238GEu+eKhRHcz8/jeG 94zkcgJOz3KbZGYMiTh277Fvj9zzvZsbMBCedV1BTg3TqgvdX4bdkhf5cH+7NtWO lrFj6UwAsGukBTAOxC0l/dnSmZhJ7Z1KmEWilro/gOrjtOxqRQutlIqG22TaqoPG fYVN+en3Zwbt97kcgZDwqbuykNt64oZWc4XKCa3mprEGC3IbJTBFqglXmZ7l9ywG EEUJYOlb2XrSuPWml39beWdKM8kzr1OjnlOm6+lpTRCBfo0wa9F8YZRhHPAkwKkX XDeOGpWRj4ohOx0d2GWkyV5xyN14p2tQOCdOODmz80yUTgRpPVQUtOEhXQARAQAB tCFBV1MgQ0xJIFRlYW0gPGF3cy1jbGlAYW1hem9uLmNvbT6JAlQEEwEIAD4CGwMF CwkIBwIGFQoJCAsCBBYCAwECHgECF4AWIQT7Xbd/1cEYuAURraimMQrMRnJHXAUC aGveYQUJDMpiLAAKCRCmMQrMRnJHXKBYD/9Ab0qQdGiO5hObchG8xh8Rpb4Mjyf6 0JrVo6m8GNjNj6BHkSc8fuTQJ/FaEhaQxj3pjZ3GXPrXjIIVChmICLlFuRXYzrXc Pw0lniybypsZEVai5kO0tCNBCCFuMN9RsmmRG8mf7lC4FSTbUDmxG/QlYK+0IV/l uJkzxWa+rySkdpm0JdqumjegNRgObdXHAQDWlubWQHWyZyIQ2B4U7AxqSpcdJp6I S4Zds4wVLd1WE5pquYQ8vS2cNlDm4QNg8wTj58e3lKN47hXHMIb6CHxRnb947oJa pg189LLPR5koh+EorNkA1wu5mAJtJvy5YMsppy2y/kIjp3lyY6AmPT1posgGk70Z CmToEZ5rbd7ARExtlh76A0cabMDFlEHDIK8RNUOSRr7L64+KxOUegKBfQHb9dADY qqiKqpCbKgvtWlds909Ms74JBgr2KwZCSY1HaOxnIr4CY43QRqAq5YHOay/mU+6w hhmdF18vpyK0vfkvvGresWtSXbag7Hkt3XjaEw76BzxQH21EBDqU8WJVjHgU6ru+ DJTs+SxgJbaT3hb/vyjlw0lK+hFfhWKRwgOXH8vqducF95NRSUxtS4fpqxWVaw3Q V2OWSjbne99A5EPEySzryFTKbMGwaTlAwMCwYevt4YT6eb7NmFhTx0Fis4TalUs+ j+c7Kg92pDx2uQ== =OBAt -----END PGP PUBLIC KEY BLOCK----- ``` For reference, the following are the details of the public key. ``` Key ID: A6310ACC4672475C Type: RSA Size: 4096/4096 Created: 2019-09-18 Expires: 2026-07-07 User ID: AWS CLI Team Key fingerprint: FB5D B77F D5C1 18B8 0511 ADA8 A631 0ACC 4672 475C ``` 1. Import the AWS CLI public key with the following command, substituting *public-key-file-name* with the file name of the public key you created. ``` $ gpg --import public-key-file-name gpg: /home/username/.gnupg/trustdb.gpg: trustdb created gpg: key A6310ACC4672475C: public key "AWS CLI Team " imported gpg: Total number processed: 1 gpg: imported: 1 ``` 1. Download the AWS CLI signature file for the package you downloaded. It has the same path and name as the `.zip` file it corresponds to, but has the extension `.sig`. In the following examples, we save it to the current directory as a file named `awscliv2.sig`. **For the latest version of the AWS CLI,** use the following command block: ``` $ curl -o awscliv2.sig https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip.sig ``` 1. Verify the signature, passing both the downloaded `.sig` and `.zip` file names as parameters to the `gpg` command. ``` $ gpg --verify awscliv2.sig awscliv2.zip ``` The output should look similar to the following. ``` gpg: Signature made Mon Nov 4 19:00:01 2019 PST gpg: using RSA key FB5D B77F D5C1 18B8 0511 ADA8 A631 0ACC 4672 475C gpg: Good signature from "AWS CLI Team " [unknown] gpg: WARNING: This key is not certified with a trusted signature! gpg: There is no indication that the signature belongs to the owner. Primary key fingerprint: FB5D B77F D5C1 18B8 0511 ADA8 A631 0ACC 4672 475C ``` **Important** The warning in the output is expected and doesn't indicate a problem. It occurs because there isn't a chain of trust between your personal PGP key (if you have one) and the AWS CLI PGP key. For more information, see [Web of trust](https://en.wikipedia.org/wiki/Web_of_trust). 1. Unzip the installer. If your Linux distribution doesn't have a built-in `unzip` command, use an equivalent to unzip it. The following example command unzips the package and creates a directory named `aws` under the current directory. ``` $ unzip awscliv2.zip ``` **Note** When updating from a previous version, the `unzip` command prompts to overwrite existing files. To skip these prompts, such as with script automation, use the `-u` update flag for `unzip`. This flag automatically updates existing files and creates new ones as needed. ``` $ unzip -u awscliv2.zip ``` 1. Run the install program. The installation command uses a file named `install` in the newly unzipped `aws` directory. By default, the files are all installed to `/usr/local/aws-cli`, and a symbolic link is created in `/usr/local/bin`. The command includes `sudo` to grant write permissions to those directories. ``` $ sudo ./aws/install ``` You can install without `sudo` if you specify directories that you already have write permissions to. Use the following instructions for the `install` command to specify the installation location: + Ensure that the paths you provide to the `-i` and `-b` parameters contain no volume name or directory names that contain any space characters or other white space characters. If there is a space, the installation fails. + `--install-dir` or `-i` – This option specifies the directory to copy all of the files to. The default value is `/usr/local/aws-cli`. + `--bin-dir` or `-b` – This option specifies that the main `aws` program in the install directory is symbolically linked to the file `aws` in the specified path. You must have write permissions to the specified directory. Creating a symlink to a directory that is already in your path eliminates the need to add the install directory to the user's `$PATH` variable. The default value is `/usr/local/bin`. ``` $ ./aws/install -i /usr/local/aws-cli -b /usr/local/bin ``` **Note** To update your current installation of the AWS CLI, add your existing symlink and installer information to construct the `install` command with the `--update` parameter. ``` $ sudo ./aws/install --bin-dir /usr/local/bin --install-dir /usr/local/aws-cli --update ``` To locate the existing symlink and installation directory, use the following steps: Use the `which` command to find your symlink. This gives you the path to use with the `--bin-dir` parameter. ``` $ which aws /usr/local/bin/aws ``` Use the `ls` command to find the directory that your symlink points to. This gives you the path to use with the `--install-dir` parameter. ``` $ ls -l /usr/local/bin/aws lrwxrwxrwx 1 ec2-user ec2-user 49 Oct 22 09:49 /usr/local/bin/aws -> /usr/local/aws-cli/v2/current/bin/aws ``` 1. Confirm the installation with the following command. ``` $ aws --version aws-cli/2.27.41 Python/3.11.6 Linux/5.10.205-195.807.amzn2.x86_64 ``` If the `aws` command cannot be found, you might need to restart your terminal or follow the troubleshooting in [Troubleshooting errors for the AWS CLI](cli-chap-troubleshooting.md). ------ #### [ Command line - Linux ARM ] To update your current installation of AWS CLI, download a new installer each time you update to overwrite previous versions. Follow these steps from the command line to install the AWS CLI on Linux. The following are quick installation steps in a single copy and paste group that provide a basic installation. For guided instructions, see the steps that follow. **Note** **(Optional)** The following command block downloads and installs the AWS CLI without first verifying the integrity of your download. To verify the integrity of your download, use the below step by step instructions. **To install** the AWS CLI, run the following commands. ``` $ curl "https://awscli.amazonaws.com/awscli-exe-linux-aarch64.zip" -o "awscliv2.zip" unzip awscliv2.zip sudo ./aws/install ``` **To update your current installation** of the AWS CLI, add your existing symlink and installer information to construct the `install` command using the `--bin-dir`, `--install-dir`, and `--update` parameters. The following command block uses an example symlink of */usr/local/bin* and example installer location of */usr/local/aws-cli*. ``` $ curl "https://awscli.amazonaws.com/awscli-exe-linux-aarch64.zip" -o "awscliv2.zip" unzip awscliv2.zip sudo ./aws/install --bin-dir /usr/local/bin --install-dir /usr/local/aws-cli --update ``` **Guided installation steps** 1. Download the installation file in one of the following ways: + **Use the `curl` command** – The `-o` option specifies the file name that the downloaded package is written to. The options on the following example command write the downloaded file to the current directory with the local name `awscliv2.zip`. ``` $ curl "https://awscli.amazonaws.com/awscli-exe-linux-aarch64.zip" -o "awscliv2.zip" ``` + **Downloading from the URL** – To download the installer with your browser, use the following URL: [https://awscli.amazonaws.com/awscli-exe-linux-aarch64.zip](https://awscli.amazonaws.com/awscli-exe-linux-aarch64.zip) 1. **(Optional) Verifying the integrity of your downloaded zip file** If you chose to manually download the AWS CLI installer package `.zip` in the above steps, you can use the following steps to verify the signatures by using the `GnuPG` tool. The AWS CLI installer package `.zip` files are cryptographically signed using PGP signatures. If there is any damage or alteration of the files, this verification fails and you should not proceed with installation. 1. Download and install the `gpg` command using your package manager. For more information about `GnuPG`, see the [GnuPG website](https://www.gnupg.org/). 1. To create the public key file, create a text file and paste in the following text. ``` -----BEGIN PGP PUBLIC KEY BLOCK----- mQINBF2Cr7UBEADJZHcgusOJl7ENSyumXh85z0TRV0xJorM2B/JL0kHOyigQluUG ZMLhENaG0bYatdrKP+3H91lvK050pXwnO/R7fB/FSTouki4ciIx5OuLlnJZIxSzx PqGl0mkxImLNbGWoi6Lto0LYxqHN2iQtzlwTVmq9733zd3XfcXrZ3+LblHAgEt5G TfNxEKJ8soPLyWmwDH6HWCnjZ/aIQRBTIQ05uVeEoYxSh6wOai7ss/KveoSNBbYz gbdzoqI2Y8cgH2nbfgp3DSasaLZEdCSsIsK1u05CinE7k2qZ7KgKAUIcT/cR/grk C6VwsnDU0OUCideXcQ8WeHutqvgZH1JgKDbznoIzeQHJD238GEu+eKhRHcz8/jeG 94zkcgJOz3KbZGYMiTh277Fvj9zzvZsbMBCedV1BTg3TqgvdX4bdkhf5cH+7NtWO lrFj6UwAsGukBTAOxC0l/dnSmZhJ7Z1KmEWilro/gOrjtOxqRQutlIqG22TaqoPG fYVN+en3Zwbt97kcgZDwqbuykNt64oZWc4XKCa3mprEGC3IbJTBFqglXmZ7l9ywG EEUJYOlb2XrSuPWml39beWdKM8kzr1OjnlOm6+lpTRCBfo0wa9F8YZRhHPAkwKkX XDeOGpWRj4ohOx0d2GWkyV5xyN14p2tQOCdOODmz80yUTgRpPVQUtOEhXQARAQAB tCFBV1MgQ0xJIFRlYW0gPGF3cy1jbGlAYW1hem9uLmNvbT6JAlQEEwEIAD4CGwMF CwkIBwIGFQoJCAsCBBYCAwECHgECF4AWIQT7Xbd/1cEYuAURraimMQrMRnJHXAUC aGveYQUJDMpiLAAKCRCmMQrMRnJHXKBYD/9Ab0qQdGiO5hObchG8xh8Rpb4Mjyf6 0JrVo6m8GNjNj6BHkSc8fuTQJ/FaEhaQxj3pjZ3GXPrXjIIVChmICLlFuRXYzrXc Pw0lniybypsZEVai5kO0tCNBCCFuMN9RsmmRG8mf7lC4FSTbUDmxG/QlYK+0IV/l uJkzxWa+rySkdpm0JdqumjegNRgObdXHAQDWlubWQHWyZyIQ2B4U7AxqSpcdJp6I S4Zds4wVLd1WE5pquYQ8vS2cNlDm4QNg8wTj58e3lKN47hXHMIb6CHxRnb947oJa pg189LLPR5koh+EorNkA1wu5mAJtJvy5YMsppy2y/kIjp3lyY6AmPT1posgGk70Z CmToEZ5rbd7ARExtlh76A0cabMDFlEHDIK8RNUOSRr7L64+KxOUegKBfQHb9dADY qqiKqpCbKgvtWlds909Ms74JBgr2KwZCSY1HaOxnIr4CY43QRqAq5YHOay/mU+6w hhmdF18vpyK0vfkvvGresWtSXbag7Hkt3XjaEw76BzxQH21EBDqU8WJVjHgU6ru+ DJTs+SxgJbaT3hb/vyjlw0lK+hFfhWKRwgOXH8vqducF95NRSUxtS4fpqxWVaw3Q V2OWSjbne99A5EPEySzryFTKbMGwaTlAwMCwYevt4YT6eb7NmFhTx0Fis4TalUs+ j+c7Kg92pDx2uQ== =OBAt -----END PGP PUBLIC KEY BLOCK----- ``` For reference, the following are the details of the public key. ``` Key ID: A6310ACC4672475C Type: RSA Size: 4096/4096 Created: 2019-09-18 Expires: 2026-07-07 User ID: AWS CLI Team Key fingerprint: FB5D B77F D5C1 18B8 0511 ADA8 A631 0ACC 4672 475C ``` 1. Import the AWS CLI public key with the following command, substituting *public-key-file-name* with the file name of the public key you created. ``` $ gpg --import public-key-file-name gpg: /home/username/.gnupg/trustdb.gpg: trustdb created gpg: key A6310ACC4672475C: public key "AWS CLI Team " imported gpg: Total number processed: 1 gpg: imported: 1 ``` 1. Download the AWS CLI signature file for the package you downloaded. It has the same path and name as the `.zip` file it corresponds to, but has the extension `.sig`. In the following examples, we save it to the current directory as a file named `awscliv2.sig`. **For the latest version of the AWS CLI, **use the following command block: ``` $ curl -o awscliv2.sig https://awscli.amazonaws.com/awscli-exe-linux-aarch64.zip.sig ``` 1. Verify the signature, passing both the downloaded `.sig` and `.zip` file names as parameters to the `gpg` command. ``` $ gpg --verify awscliv2.sig awscliv2.zip ``` The output should look similar to the following. ``` gpg: Signature made Mon Nov 4 19:00:01 2019 PST gpg: using RSA key FB5D B77F D5C1 18B8 0511 ADA8 A631 0ACC 4672 475C gpg: Good signature from "AWS CLI Team " [unknown] gpg: WARNING: This key is not certified with a trusted signature! gpg: There is no indication that the signature belongs to the owner. Primary key fingerprint: FB5D B77F D5C1 18B8 0511 ADA8 A631 0ACC 4672 475C ``` **Important** The warning in the output is expected and doesn't indicate a problem. It occurs because there isn't a chain of trust between your personal PGP key (if you have one) and the AWS CLI PGP key. For more information, see [Web of trust](https://en.wikipedia.org/wiki/Web_of_trust). 1. Unzip the installer. If your Linux distribution doesn't have a built-in `unzip` command, use an equivalent to unzip it. The following example command unzips the package and creates a directory named `aws` under the current directory. ``` $ unzip awscliv2.zip ``` **Note** When updating from a previous version, the `unzip` command prompts to overwrite existing files. To skip these prompts, such as with script automation, use the `-u` update flag for `unzip`. This flag automatically updates existing files and creates new ones as needed. ``` $ unzip -u awscliv2.zip ``` 1. Run the install program. The installation command uses a file named `install` in the newly unzipped `aws` directory. By default, the files are all installed to `/usr/local/aws-cli`, and a symbolic link is created in `/usr/local/bin`. The command includes `sudo` to grant write permissions to those directories. ``` $ sudo ./aws/install ``` You can install without `sudo` if you specify directories that you already have write permissions to. Use the following instructions for the `install` command to specify the installation location: + Ensure that the paths you provide to the `-i` and `-b` parameters contain no volume name or directory names that contain any space characters or other white space characters. If there is a space, the installation fails. + `--install-dir` or `-i` – This option specifies the directory to copy all of the files to. The default value is `/usr/local/aws-cli`. + `--bin-dir` or `-b` – This option specifies that the main `aws` program in the install directory is symbolically linked to the file `aws` in the specified path. You must have write permissions to the specified directory. Creating a symlink to a directory that is already in your path eliminates the need to add the install directory to the user's `$PATH` variable. The default value is `/usr/local/bin`. ``` $ ./aws/install -i /usr/local/aws-cli -b /usr/local/bin ``` **Note** To update your current installation of the AWS CLI, add your existing symlink and installer information to construct the `install` command with the `--update` parameter. ``` $ sudo ./aws/install --bin-dir /usr/local/bin --install-dir /usr/local/aws-cli --update ``` To locate the existing symlink and installation directory, use the following steps: Use the `which` command to find your symlink. This gives you the path to use with the `--bin-dir` parameter. ``` $ which aws /usr/local/bin/aws ``` Use the `ls` command to find the directory that your symlink points to. This gives you the path to use with the `--install-dir` parameter. ``` $ ls -l /usr/local/bin/aws lrwxrwxrwx 1 ec2-user ec2-user 49 Oct 22 09:49 /usr/local/bin/aws -> /usr/local/aws-cli/v2/current/bin/aws ``` 1. Confirm the installation with the following command. ``` $ aws --version aws-cli/2.27.41 Python/3.11.6 Linux/5.10.205-195.807.amzn2.x86_64 ``` If the `aws` command cannot be found, you might need to restart your terminal or follow the troubleshooting in [Troubleshooting errors for the AWS CLI](cli-chap-troubleshooting.md). ------ #### [ Snap package ] We provide an official AWS supported version of the AWS CLI on `snap`. If you want to always have the latest version of the AWS CLI installed on your system, a snap package provides this for you as it auto-updates. There is no built-in support for selecting minor versions of AWS CLI and therefore it is not an optimal install method if your team needs to pin versions. If you want to install a specific minor version of the AWS CLI, we suggest you use the command line installer. 1. If your Linux platform does not already have `snap` installed, install `snap` on your platform. 1. For information on installing `snap`, see [Installing the daemon](https://snapcraft.io/docs/installing-snapd) in the *Snap documentation*. 1. You may need to restart your system so that your `PATH` variables are updated correctly. If you are having installation issues, follow steps in [Fix common issues](https://snapcraft.io/docs/fix-common-issues) in the *Snap documentation*. 1. To verify that `snap` is installed correctly, run the following command. ``` $ snap version ``` 1. Run the following `snap install` command for the AWS CLI. ``` $ snap install aws-cli --classic ``` Depending on your permissions, you may need to add `sudo` to the command. ``` $ sudo snap install aws-cli --classic ``` **Note** To view the snap repository for the AWS CLI, including additional `snap` instructions, see the [https://snapcraft.io/aws-cli](https://snapcraft.io/aws-cli) page in the *Canonical Snapcraft website*. 1. Verify that the AWS CLI installed correctly. ``` $ aws --version aws-cli/2.27.41 Python/3.11.6 Linux/5.10.205-195.807.amzn2.x86_64 ``` If you get an error, see [Troubleshooting errors for the AWS CLI](cli-chap-troubleshooting.md). ------ ### macOS #### Install and update requirements + We support the AWS CLI on macOS versions 11 and later. For more information, see [macOS support policy updates for the AWS CLI v2](https://aws.amazon.com/blogs/developer/macos-support-policy-updates-for-the-aws-cli-v2/) on the *AWS Developer Tools Blog*. + Because AWS doesn't maintain third-party repositories, we can’t guarantee that they contain the latest version of the AWS CLI. **macOS version support matrix** | AWS CLI version | Supported macOS version | | --- | --- | | 2.21.0 – current | 11\$1 | | 2.17.0 –2.20.0 | 10.15\$1 | | 2.0.0 – 2.16.12 | 10.14 and below | #### Install or update the AWS CLI If you are updating to the latest version, use the same installation method that you used in your current version. You can install the AWS CLI on macOS in the following ways. ------ #### [ GUI installer ] The following steps show how to install the latest version of the AWS CLI by using the standard macOS user interface and your browser. 1. In your browser, download the macOS `pkg` file: [https://awscli.amazonaws.com/AWSCLIV2.pkg](https://awscli.amazonaws.com/AWSCLIV2.pkg) 1. Run your downloaded file and follow the on-screen instructions. You can choose to install the AWS CLI in the following ways: + **For all users on the computer (requires `sudo`)** + You can install to any folder, or choose the recommended default folder of `/usr/local/aws-cli`. + The installer automatically creates a symlink at `/usr/local/bin/aws` that links to the main program in the installation folder you chose. + **For only the current user (doesn't require `sudo`)** + You can install to any folder to which you have write permission. + Due to standard user permissions, after the installer finishes, you must manually create a symlink file in your `$PATH` that points to the `aws` and `aws_completer` programs by using the following commands at the command prompt. The default location for a symlink is `/usr/local/bin/`: ``` $ ln -s /folder/installed/aws-cli/aws /usr/local/bin/aws $ ln -s /folder/installed/aws-cli/aws_completer /usr/local/bin/aws_completer ``` If you don't have write permissions to the folder, you may need to use `sudo` in your command. The following example uses `sudo` with the default location for a symlink in `/usr/local/bin/`: ``` $ sudo ln -s /folder/installed/aws-cli/aws /usr/local/bin/aws $ sudo ln -s /folder/installed/aws-cli/aws_completer /usr/local/bin/aws_completer ``` **Note** You can view debug logs for the installation by pressing **Cmd\$1L** anywhere in the installer. This opens a log pane that enables you to filter and save the log. The log file is also automatically saved to `/var/log/install.log`. 1. To verify that the shell can find and run the `aws` command in your `$PATH`, use the following commands. ``` $ which aws /usr/local/bin/aws $ aws --version aws-cli/2.27.41 Python/3.11.6 Darwin/23.3.0 ``` If the `aws` command cannot be found, you might need to restart your terminal or follow the troubleshooting in [Troubleshooting errors for the AWS CLI](cli-chap-troubleshooting.md). ------ #### [ Command line installer - All users ] If you have `sudo` permissions, you can install the AWS CLI for all users on the computer. We provide the steps in one easy to copy and paste group. See the descriptions of each line in the following steps. ``` $ curl "https://awscli.amazonaws.com/AWSCLIV2.pkg" -o "AWSCLIV2.pkg" $ sudo installer -pkg AWSCLIV2.pkg -target / ``` **Guided installation instructions** 1. Download the file using the `curl` command. The `-o` option specifies the file name that the downloaded package is written to. In this example, the file is written to `AWSCLIV2.pkg` in the current folder. ``` $ curl "https://awscli.amazonaws.com/AWSCLIV2.pkg" -o "AWSCLIV2.pkg" ``` 1. Run the standard macOS `installer` program, specifying the downloaded `.pkg` file as the source. Use the `-pkg` parameter to specify the name of the package to install, and the `-target /` parameter for which drive to install the package to. The files are installed to `/usr/local/aws-cli`, and a symlink is automatically created in `/usr/local/bin`. You must include `sudo` on the command to grant write permissions to those folders. ``` $ sudo installer -pkg ./AWSCLIV2.pkg -target / ``` After installation is complete, debug logs are written to `/var/log/install.log`. 1. To verify that the shell can find and run the `aws` command in your `$PATH`, use the following commands. ``` $ which aws /usr/local/bin/aws $ aws --version aws-cli/2.27.41 Python/3.11.6 Darwin/23.3.0 ``` If the `aws` command cannot be found, you might need to restart your terminal or follow the troubleshooting in [Troubleshooting errors for the AWS CLI](cli-chap-troubleshooting.md). ------ #### [ Command line - Current user ] 1. To specify which folder the AWS CLI is installed to, you must create an XML file with any file name. This file is an XML-formatted file that looks like the following example. Leave all values as shown, except you must replace the path */Users/myusername* in line 9 with the path to the folder you want the AWS CLI installed to. *The folder must already exist, or the command fails.* The following XML example, named *choices.xml*, specifies the installer to install the AWS CLI in the folder `/Users/myusername`, where it creates a folder named `aws-cli`. ``` choiceAttribute customLocation attributeSetting /Users/myusername choiceIdentifier default ``` 1. Download the `pkg` installer using the `curl` command. The `-o` option specifies the file name that the downloaded package is written to. In this example, the file is written to `AWSCLIV2.pkg` in the current folder. ``` $ curl "https://awscli.amazonaws.com/AWSCLIV2.pkg" -o "AWSCLIV2.pkg" ``` 1. Run the standard macOS `installer` program with the following options: + Specify the name of the package to install by using the `-pkg` parameter. + Specify installing to a *current user only* by setting the `-target` parameter to `CurrentUserHomeDirectory`. + Specify the path (relative to the current folder) and name of the XML file that you created in the `-applyChoiceChangesXML` parameter. The following example installs the AWS CLI in the folder `/Users/myusername/aws-cli`. ``` $ installer -pkg AWSCLIV2.pkg \ -target CurrentUserHomeDirectory \ -applyChoiceChangesXML choices.xml ``` 1. Because standard user permissions typically don't allow writing to folders in your `$PATH`, the installer in this mode doesn't try to add the symlinks to the `aws` and `aws_completer` programs. For the AWS CLI to run correctly, you must manually create the symlinks after the installer finishes. If your `$PATH` includes a folder you can write to and you specify the folder as the target's path, you can run the following command without `sudo`. If you don't have a writable folder in your `$PATH`, you must use `sudo` for permissions to write to the specified target folder. The default location for a symlink is `/usr/local/bin/`. Replace `folder/installed` with the path to your AWS CLI installation. ``` $ sudo ln -s /folder/installed/aws-cli/aws /usr/local/bin/aws $ sudo ln -s /folder/installed/aws-cli/aws_completer /usr/local/bin/aws_completer ``` After installation is complete, debug logs are written to `/var/log/install.log`. 1. To verify that the shell can find and run the `aws` command in your `$PATH`, use the following commands. ``` $ which aws /usr/local/bin/aws $ aws --version aws-cli/2.27.41 Python/3.11.6 Darwin/23.3.0 ``` If the `aws` command cannot be found, you might need to restart your terminal or follow the troubleshooting in [Troubleshooting errors for the AWS CLI](cli-chap-troubleshooting.md). ------ ### Windows #### Install and update requirements + We support the AWS CLI on Microsoft-supported versions of 64-bit Windows. + Admin rights to install software #### Install or update the AWS CLI To update your current installation of AWS CLI on Windows, download a new installer each time you update to overwrite previous versions. AWS CLI is updated regularly. To see when the latest version was released, see the [AWS CLI version 2 Changelog](https://raw.githubusercontent.com/aws/aws-cli/v2/CHANGELOG.rst) on *GitHub*. 1. Download and run the AWS CLI MSI installer for Windows (64-bit): [https://awscli.amazonaws.com/AWSCLIV2.msi](https://awscli.amazonaws.com/AWSCLIV2.msi) Alternatively, you can run the `msiexec` command to run the MSI installer. ``` C:\> msiexec.exe /i https://awscli.amazonaws.com/AWSCLIV2.msi ``` For various parameters that can be used with `msiexec`, see [msiexec](https://docs.microsoft.com/en-us/windows-server/administration/windows-commands/msiexec) on the *Microsoft Docs* website. For example, you can use the `/qn` flag for a silent installation. ``` C:\> msiexec.exe /i https://awscli.amazonaws.com/AWSCLIV2.msi /qn ``` 1. To confirm the installation, open the **Start** menu, search for `cmd` to open a command prompt window, and at the command prompt use the `aws --version` command. ``` C:\> aws --version aws-cli/2.27.41 Python/3.11.6 Windows/10 exe/AMD64 prompt/off ``` If Windows is unable to find the program, you might need to close and reopen the command prompt window to refresh the path, or follow the troubleshooting in [Troubleshooting errors for the AWS CLI](cli-chap-troubleshooting.md). ## Troubleshooting AWS CLI install and uninstall errors If you come across issues after installing or uninstalling the AWS CLI, see [Troubleshooting errors for the AWS CLI](cli-chap-troubleshooting.md) for troubleshooting steps. For the most relevant troubleshooting steps, see [Command not found errors](cli-chap-troubleshooting.md#tshoot-install-not-found), [The "`aws --version`" command returns a different version than you installed](cli-chap-troubleshooting.md#tshoot-install-wrong-version), and [The "`aws --version`" command returns a version after uninstalling the AWS CLI](cli-chap-troubleshooting.md#tshoot-uninstall-1). ## Next steps After you successfully install the AWS CLI, you can safely delete your downloaded installer files. After completing the steps in [Prerequisites to use the AWS CLI version 2](getting-started-prereqs.md) and installing the AWS CLI, you should perform a [Setting up the AWS CLI](getting-started-quickstart.md). # Installing past releases of the AWS CLI version 2 This topic describes how to install the past releases of the AWS Command Line Interface version 2 (AWS CLI) on supported operating systems. For information on the AWS CLI version 2 releases, see the [AWS CLI version 2 Changelog](https://raw.githubusercontent.com/aws/aws-cli/v2/CHANGELOG.rst) on GitHub. AWS CLI version 2 installation instructions: ## Linux ### Installation requirements + You know which release of the AWS CLI version 2 you'd like to install. For a list of versions, see the [AWS CLI version 2 Changelog](https://raw.githubusercontent.com/aws/aws-cli/v2/CHANGELOG.rst) on *GitHub*. + You must be able to extract or "unzip" the downloaded package. If your operating system doesn't have the built-in `unzip` command, use an equivalent. + The AWS CLI version 2 uses `glibc`, `groff`, and `less`. These are included by default in most major distributions of Linux. + We support the AWS CLI version 2 on 64-bit versions of recent distributions of CentOS, Fedora, Ubuntu, Amazon Linux 1, Amazon Linux 2 and Linux ARM. + Because AWS doesn't maintain third-party repositories, we can’t guarantee that they contain the latest version of the AWS CLI. ### Installation instructions Follow these steps from the command line to install the AWS CLI on Linux. We provide the steps in one easy to copy and paste group based on whether you use 64-bit Linux or Linux ARM. See the descriptions of each line in the steps that follow. ------ #### [ Linux x86 (64-bit) ] **Note** **(Optional)** The following command block downloads and installs the AWS CLI without first verifying the integrity of your download. To verify the integrity of your download, use the below step by step instructions. For a list of versions, see the [AWS CLI version 2 Changelog](https://raw.githubusercontent.com/aws/aws-cli/v2/CHANGELOG.rst) on *GitHub*. **To install** the AWS CLI, run the following commands. To specify a version, append a hyphen and the version number to the filename. For this example the filename for version *2.0.30* would be `awscli-exe-linux-x86_64-2.0.30.zip` resulting in the following command: ``` $ curl "https://awscli.amazonaws.com/awscli-exe-linux-x86_64-2.0.30.zip" -o "awscliv2.zip" unzip awscliv2.zip sudo ./aws/install ``` **To update your current installation** of the AWS CLI, add your existing symlink and installer information to construct the `install` command using the `--bin-dir`, `--install-dir`, and `--update` parameters. The following command block uses an example symlink of */usr/local/bin* and example installer location of */usr/local/aws-cli*. ``` $ curl "https://awscli.amazonaws.com/awscli-exe-linux-x86_64-2.0.30.zip" -o "awscliv2.zip" unzip awscliv2.zip sudo ./aws/install --bin-dir /usr/local/bin --install-dir /usr/local/aws-cli --update ``` ------ #### [ Linux ARM ] **Note** **(Optional)** The following command block downloads and installs the AWS CLI without first verifying the integrity of your download. To verify the integrity of your download, use the below step by step instructions. For a list of versions, see the [AWS CLI version 2 Changelog](https://raw.githubusercontent.com/aws/aws-cli/v2/CHANGELOG.rst) on *GitHub*. **To install** the AWS CLI, run the following commands. To specify a version, append a hyphen and the version number to the filename. For this example the filename for version *2.0.30* would be `awscli-exe-linux-aarch64-2.0.30.zip` resulting in the following command: ``` $ curl "https://awscli.amazonaws.com/awscli-exe-linux-aarch64-2.0.30.zip" -o "awscliv2.zip" unzip awscliv2.zip sudo ./aws/install ``` **To update your current installation** of the AWS CLI, add your existing symlink and installer information to construct the `install` command using the `--bin-dir`, `--install-dir`, and `--update` parameters. The following command block uses an example symlink of */usr/local/bin* and example installer location of */usr/local/aws-cli*. ``` $ curl "https://awscli.amazonaws.com/awscli-exe-linux-aarch64-2.0.30.zip" -o "awscliv2.zip" unzip awscliv2.zip sudo ./aws/install --bin-dir /usr/local/bin --install-dir /usr/local/aws-cli --update ``` ------ 1. Download the installation file in one of the following ways: ------ #### [ Linux x86 (64-bit) ] + **Use the `curl` command** – The `-o` option specifies the file name that the downloaded package is written to. The options on the following example command write the downloaded file to the current directory with the local name `awscliv2.zip`. To specify a version, append a hyphen and the version number to the filename. For this example the filename for version *2.0.30* would be `awscli-exe-linux-x86_64-2.0.30.zip` resulting in the following command: ``` $ curl "https://awscli.amazonaws.com/awscli-exe-linux-x86_64-2.0.30.zip" -o "awscliv2.zip" ``` For a list of versions, see the [AWS CLI version 2 Changelog](https://raw.githubusercontent.com/aws/aws-cli/v2/CHANGELOG.rst) on *GitHub*. + **Downloading from the URL** – In your browser, download your specific version of the AWS CLI by appending a hyphen and the version number to the filename. ``` https://awscli.amazonaws.com/awscli-exe-linux-x86_64-version.number.zip ``` For this example the filename for version *2.0.30* would be awscli-exe-linux-x86\$164-2.0.30.zip resulting in the following link: [https://awscli.amazonaws.com/awscli-exe-linux-x86_64-2.0.30.zip](https://awscli.amazonaws.com/awscli-exe-linux-x86_64-2.0.30.zip) ------ #### [ Linux ARM ] + **Use the `curl` command** – The `-o` option specifies the file name that the downloaded package is written to. The options on the following example command write the downloaded file to the current directory with the local name `awscliv2.zip`. To specify a version, append a hyphen and the version number to the filename. For this example the filename for version *2.0.30* would be `awscli-exe-linux-aarch64-2.0.30.zip` resulting in the following command: ``` $ curl "https://awscli.amazonaws.com/awscli-exe-linux-aarch64-2.0.30.zip" -o "awscliv2.zip" unzip awscliv2.zip sudo ./aws/install ``` + **Downloading from the URL** – In your browser, download your specific version of the AWS CLI by appending a hyphen and the version number to the filename. ``` https://awscli.amazonaws.com/awscli-exe-linux-aarch64-version.number.zip ``` For this example the filename for version *2.0.30* would be `awscli-exe-linux-aarch64-2.0.30.zip` resulting in the following link: [https://awscli.amazonaws.com/awscli-exe-linux-aarch64-2.0.30.zip](https://awscli.amazonaws.com/awscli-exe-linux-aarch64-2.0.30.zip) ------ 1. **(Optional) Verifying the integrity of your downloaded zip file** If you chose to manually download the AWS CLI installer package `.zip` in the above steps, you can use the following steps to verify the signatures by using the `GnuPG` tool. The AWS CLI installer package `.zip` files are cryptographically signed using PGP signatures. If there is any damage or alteration of the files, this verification fails and you should not proceed with installation. 1. Download and install the `gpg` command using your package manager. For more information about `GnuPG`, see the [GnuPG website](https://www.gnupg.org/). 1. To create the public key file, create a text file and paste in the following text. ``` -----BEGIN PGP PUBLIC KEY BLOCK----- mQINBF2Cr7UBEADJZHcgusOJl7ENSyumXh85z0TRV0xJorM2B/JL0kHOyigQluUG ZMLhENaG0bYatdrKP+3H91lvK050pXwnO/R7fB/FSTouki4ciIx5OuLlnJZIxSzx PqGl0mkxImLNbGWoi6Lto0LYxqHN2iQtzlwTVmq9733zd3XfcXrZ3+LblHAgEt5G TfNxEKJ8soPLyWmwDH6HWCnjZ/aIQRBTIQ05uVeEoYxSh6wOai7ss/KveoSNBbYz gbdzoqI2Y8cgH2nbfgp3DSasaLZEdCSsIsK1u05CinE7k2qZ7KgKAUIcT/cR/grk C6VwsnDU0OUCideXcQ8WeHutqvgZH1JgKDbznoIzeQHJD238GEu+eKhRHcz8/jeG 94zkcgJOz3KbZGYMiTh277Fvj9zzvZsbMBCedV1BTg3TqgvdX4bdkhf5cH+7NtWO lrFj6UwAsGukBTAOxC0l/dnSmZhJ7Z1KmEWilro/gOrjtOxqRQutlIqG22TaqoPG fYVN+en3Zwbt97kcgZDwqbuykNt64oZWc4XKCa3mprEGC3IbJTBFqglXmZ7l9ywG EEUJYOlb2XrSuPWml39beWdKM8kzr1OjnlOm6+lpTRCBfo0wa9F8YZRhHPAkwKkX XDeOGpWRj4ohOx0d2GWkyV5xyN14p2tQOCdOODmz80yUTgRpPVQUtOEhXQARAQAB tCFBV1MgQ0xJIFRlYW0gPGF3cy1jbGlAYW1hem9uLmNvbT6JAlQEEwEIAD4CGwMF CwkIBwIGFQoJCAsCBBYCAwECHgECF4AWIQT7Xbd/1cEYuAURraimMQrMRnJHXAUC aGveYQUJDMpiLAAKCRCmMQrMRnJHXKBYD/9Ab0qQdGiO5hObchG8xh8Rpb4Mjyf6 0JrVo6m8GNjNj6BHkSc8fuTQJ/FaEhaQxj3pjZ3GXPrXjIIVChmICLlFuRXYzrXc Pw0lniybypsZEVai5kO0tCNBCCFuMN9RsmmRG8mf7lC4FSTbUDmxG/QlYK+0IV/l uJkzxWa+rySkdpm0JdqumjegNRgObdXHAQDWlubWQHWyZyIQ2B4U7AxqSpcdJp6I S4Zds4wVLd1WE5pquYQ8vS2cNlDm4QNg8wTj58e3lKN47hXHMIb6CHxRnb947oJa pg189LLPR5koh+EorNkA1wu5mAJtJvy5YMsppy2y/kIjp3lyY6AmPT1posgGk70Z CmToEZ5rbd7ARExtlh76A0cabMDFlEHDIK8RNUOSRr7L64+KxOUegKBfQHb9dADY qqiKqpCbKgvtWlds909Ms74JBgr2KwZCSY1HaOxnIr4CY43QRqAq5YHOay/mU+6w hhmdF18vpyK0vfkvvGresWtSXbag7Hkt3XjaEw76BzxQH21EBDqU8WJVjHgU6ru+ DJTs+SxgJbaT3hb/vyjlw0lK+hFfhWKRwgOXH8vqducF95NRSUxtS4fpqxWVaw3Q V2OWSjbne99A5EPEySzryFTKbMGwaTlAwMCwYevt4YT6eb7NmFhTx0Fis4TalUs+ j+c7Kg92pDx2uQ== =OBAt -----END PGP PUBLIC KEY BLOCK----- ``` For reference, the following are the details of the public key. ``` Key ID: A6310ACC4672 Type: RSA Size: 4096/4096 Created: 2019-09-18 Expires: 2026-07-07 User ID: AWS CLI Team Key fingerprint: FB5D B77F D5C1 18B8 0511 ADA8 A631 0ACC 4672 475C ``` 1. Import the AWS CLI public key with the following command, substituting *public-key-file-name* with the file name of the public key you created. ``` $ gpg --import public-key-file-name gpg: /home/username/.gnupg/trustdb.gpg: trustdb created gpg: key A6310ACC4672475C: public key "AWS CLI Team " imported gpg: Total number processed: 1 gpg: imported: 1 ``` 1. Download the AWS CLI signature file for the package you downloaded. It has the same path and name as the `.zip` file it corresponds to, but has the extension `.sig`. In the following examples, we save it to the current directory as a file named `awscliv2.sig`. ------ #### [ Linux x86 (64-bit) ] **For the latest version of the AWS CLI,** use the following command block: ``` $ curl -o awscliv2.sig https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip.sig ``` **For a specific version of the AWS CLI,** append a hyphen and the version number to the filename. For this example the filename for version *2.0.30* would be `awscli-exe-linux-x86_64-2.0.30.zip.sig` resulting in the following command: ``` $ curl -o awscliv2.sig https://awscli.amazonaws.com/awscli-exe-linux-x86_64-2.0.30.zip.sig ``` For a list of versions, see the [AWS CLI version 2 Changelog](https://raw.githubusercontent.com/aws/aws-cli/v2/CHANGELOG.rst) on *GitHub*. ------ #### [ Linux ARM ] **For the latest version of the AWS CLI, **use the following command block: ``` $ curl -o awscliv2.sig https://awscli.amazonaws.com/awscli-exe-linux-aarch64.zip.sig ``` **For a specific version of the AWS CLI, **append a hyphen and the version number to the filename. For this example the filename for version *2.0.30* would be `awscli-exe-linux-aarch64-2.0.30.zip.sig` resulting in the following command: ``` $ curl -o awscliv2.sig https://awscli.amazonaws.com/awscli-exe-linux-aarch64-2.0.30.zip.sig ``` For a list of versions, see the [AWS CLI version 2 Changelog](https://github.com/aws/aws-cli/blob/v2/CHANGELOG.rst?plain=1) on *GitHub*. ------ 1. Verify the signature, passing both the downloaded `.sig` and `.zip` file names as parameters to the `gpg` command. ``` $ gpg --verify awscliv2.sig awscliv2.zip ``` The output should look similar to the following. ``` gpg: Signature made Mon Nov 4 19:00:01 2019 PST gpg: using RSA key FB5D B77F D5C1 18B8 0511 ADA8 A631 0ACC 4672 475C gpg: Good signature from "AWS CLI Team " [unknown] gpg: WARNING: This key is not certified with a trusted signature! gpg: There is no indication that the signature belongs to the owner. Primary key fingerprint: FB5D B77F D5C1 18B8 0511 ADA8 A631 0ACC 4672 475C ``` **Important** The warning in the output is expected and doesn't indicate a problem. It occurs because there isn't a chain of trust between your personal PGP key (if you have one) and the AWS CLI PGP key. For more information, see [Web of trust](https://en.wikipedia.org/wiki/Web_of_trust). 1. Unzip the installer. If your Linux distribution doesn't have a built-in `unzip` command, use an equivalent to unzip it. The following example command unzips the package and creates a directory named `aws` under the current directory. ``` $ unzip awscliv2.zip ``` 1. Run the install program. The installation command uses a file named `install` in the newly unzipped `aws` directory. By default, the files are all installed to `/usr/local/aws-cli`, and a symbolic link is created in `/usr/local/bin`. The command includes `sudo` to grant write permissions to those directories. ``` $ sudo ./aws/install ``` You can install without `sudo` if you specify directories that you already have write permissions to. Use the following instructions for the `install` command to specify the installation location: + Ensure that the paths you provide to the `-i` and `-b` parameters contain no volume name or directory names that contain any space characters or other white space characters. If there is a space, the installation fails. + `--install-dir` or `-i` – This option specifies the directory to copy all of the files to. The default value is `/usr/local/aws-cli`. + `--bin-dir` or `-b` – This option specifies that the main `aws` program in the install directory is symbolically linked to the file `aws` in the specified path. You must have write permissions to the specified directory. Creating a symlink to a directory that is already in your path eliminates the need to add the install directory to the user's `$PATH` variable. The default value is `/usr/local/bin`. ``` $ ./aws/install -i /usr/local/aws-cli -b /usr/local/bin ``` **Note** To update your current installation of the AWS CLI version 2 to a newer version, add your existing symlink and installer information to construct the `install` command with the `--update` parameter. ``` $ sudo ./aws/install --bin-dir /usr/local/bin --install-dir /usr/local/aws-cli --update ``` To locate the existing symlink and installation directory, use the following steps: Use the `which` command to find your symlink. This gives you the path to use with the `--bin-dir` parameter. ``` $ which aws /usr/local/bin/aws ``` Use the `ls` command to find the directory that your symlink points to. This gives you the path to use with the `--install-dir` parameter. ``` $ ls -l /usr/local/bin/aws lrwxrwxrwx 1 ec2-user ec2-user 49 Oct 22 09:49 /usr/local/bin/aws -> /usr/local/aws-cli/v2/current/bin/aws ``` 1. Confirm the installation with the following command. ``` $ aws --version aws-cli/2.27.41 Python/3.11.6 Linux/5.10.205-195.807.amzn2.x86_64 ``` If the `aws` command cannot be found, you might need to restart your terminal or follow the troubleshooting in [Troubleshooting errors for the AWS CLI](cli-chap-troubleshooting.md). ## macOS ### Installation requirements + You know which release of the AWS CLI version 2 you'd like to install. For a list of versions, see the [AWS CLI version 2 Changelog](https://github.com/aws/aws-cli/blob/v2/CHANGELOG.rst?plain=1) on *GitHub*. + We support the AWS CLI version 2 on Apple-supported versions of 64-bit macOS. + Because AWS doesn't maintain third-party repositories, we can’t guarantee that they contain the latest version of the AWS CLI. ### Installation instructions You can install the AWS CLI version 2 on macOS in the following ways. ------ #### [ GUI installer ] The following steps show how to install or update to the latest version of the AWS CLI version 2 by using the standard macOS user interface and your browser. If you are updating to the latest version, use the same installation method that you used for your current version. 1. In your browser, download your specific version of the AWS CLI by appending a hyphen and the version number to the filename. ``` https://awscli.amazonaws.com/AWSCLIV2-version.number.pkg ``` For this example, the filename for version *2.0.30* would be `AWSCLIV2-2.0.30.pkg` resulting in the following link: [https://awscli.amazonaws.com/AWSCLIV2-2.0.30.pkg](https://awscli.amazonaws.com/AWSCLIV2-2.0.30.pkg). 1. Run your downloaded file and follow the on-screen instructions. You can choose to install the AWS CLI version 2 in the following ways: + **For all users on the computer (requires `sudo`)** + You can install to any folder, or choose the recommended default folder of `/usr/local/aws-cli`. + The installer automatically creates a symlink at `/usr/local/bin/aws` that links to the main program in the installation folder you chose. + **For only the current user (doesn't require `sudo`)** + You can install to any folder to which you have write permission. + Due to standard user permissions, after the installer finishes, you must manually create a symlink file in your `$PATH` that points to the `aws` and `aws_completer` programs by using the following commands at the command prompt. If your `$PATH` includes a folder you can write to, you can run the following command without `sudo` if you specify that folder as the target's path. If you don't have a writable folder in your `$PATH`, you must use `sudo` in the commands to get permissions to write to the specified target folder. The default location for a symlink is `/usr/local/bin/`. ``` $ sudo ln -s /folder/installed/aws-cli/aws /usr/local/bin/aws $ sudo ln -s /folder/installed/aws-cli/aws_completer /usr/local/bin/aws_completer ``` **Note** You can view debug logs for the installation by pressing **Cmd\$1L** anywhere in the installer. This opens a log pane that enables you to filter and save the log. The log file is also automatically saved to `/var/log/install.log`. 1. To verify that the shell can find and run the `aws` command in your `$PATH`, use the following commands. ``` $ which aws /usr/local/bin/aws $ aws --version aws-cli/2.27.41 Python/3.11.6 Darwin/23.3.0 ``` If the `aws` command cannot be found, you might need to restart your terminal or follow the troubleshooting in [Troubleshooting errors for the AWS CLI](cli-chap-troubleshooting.md). ------ #### [ Command line installer - All users ] If you have `sudo` permissions, you can install the AWS CLI version 2 for all users on the computer. We provide the steps in one easy to copy and paste group. See the descriptions of each line in the following steps. For a specific version of the AWS CLI, append a hyphen and the version number to the filename. For this example the filename for version *2.0.30* would be `AWSCLIV2-2.0.30.pkg` resulting in the following command: ``` $ curl "https://awscli.amazonaws.com/AWSCLIV2-2.0.30.pkg" -o "AWSCLIV2.pkg" $ sudo installer -pkg AWSCLIV2.pkg -target / ``` 1. Download the file using the `curl` command. The `-o` option specifies the file name that the downloaded package is written to. In this example, the file is written to `AWSCLIV2.pkg` in the current folder. For a specific version of the AWS CLI, append a hyphen and the version number to the filename. For this example the filename for version *2.0.30* would be `AWSCLIV2-2.0.30.pkg` resulting in the following command: ``` $ curl "https://awscli.amazonaws.com/AWSCLIV2-2.0.30.pkg" -o "AWSCLIV2.pkg" ``` For a list of versions, see the [AWS CLI version 2 Changelog](https://raw.githubusercontent.com/aws/aws-cli/v2/CHANGELOG.rst) on *GitHub*. 1. Run the standard macOS `installer` program, specifying the downloaded `.pkg` file as the source. Use the `-pkg` parameter to specify the name of the package to install, and the `-target /` parameter for which drive to install the package to. The files are installed to `/usr/local/aws-cli`, and a symlink is automatically created in `/usr/local/bin`. You must include `sudo` on the command to grant write permissions to those folders. ``` $ sudo installer -pkg ./AWSCLIV2.pkg -target / ``` After installation is complete, debug logs are written to `/var/log/install.log`. 1. To verify that the shell can find and run the `aws` command in your `$PATH`, use the following commands. ``` $ which aws /usr/local/bin/aws $ aws --version aws-cli/2.27.41 Python/3.11.6 Darwin/23.3.0 ``` If the `aws` command cannot be found, you might need to restart your terminal or follow the troubleshooting in [Troubleshooting errors for the AWS CLI](cli-chap-troubleshooting.md). ------ #### [ Command line - Current user ] 1. To specify which folder the AWS CLI is installed to, you must create an XML file. This file is an XML-formatted file that looks like the following example. Leave all values as shown, except you must replace the path */Users/myusername* in line 9 with the path to the folder you want the AWS CLI version 2 installed to. *The folder must already exist, or the command fails.* This XML example specifies that the installer installs the AWS CLI in the folder `/Users/myusername`, where it creates a folder named `aws-cli`. ``` choiceAttribute customLocation attributeSetting /Users/myusername choiceIdentifier default ``` 1. Download the `pkg` installer using the `curl` command. The `-o` option specifies the file name that the downloaded package is written to. In this example, the file is written to `AWSCLIV2.pkg` in the current folder. For the specific version of the AWS CLI, append a hyphen and the version number to the filename. For this example the filename for version *2.0.30* would be `AWSCLIV2-2.0.30.pkg` resulting in the following command: ``` $ curl "https://awscli.amazonaws.com/AWSCLIV2-2.0.30.pkg" -o "AWSCLIV2.pkg" ``` For a list of versions, see the [AWS CLI version 2 Changelog](https://raw.githubusercontent.com/aws/aws-cli/v2/CHANGELOG.rst) on *GitHub*. 1. Run the standard macOS `installer` program with the following options: + Specify the name of the package to install by using the `-pkg` parameter. + Specify installing to a *current user only* by setting the `-target` parameter to `CurrentUserHomeDirectory`. + Specify the path (relative to the current folder) and name of the XML file that you created in the `-applyChoiceChangesXML` parameter. The following example installs the AWS CLI in the folder `/Users/myusername/aws-cli`. ``` $ installer -pkg AWSCLIV2.pkg \ -target CurrentUserHomeDirectory \ -applyChoiceChangesXML choices.xml ``` 1. Because standard user permissions typically don't allow writing to folders in your `$PATH`, the installer in this mode doesn't try to add the symlinks to the `aws` and `aws_completer` programs. For the AWS CLI to run correctly, you must manually create the symlinks after the installer finishes. If your `$PATH` includes a folder you can write to and you specify the folder as the target's path, you can run the following command without `sudo`. If you don't have a writable folder in your `$PATH`, you must use `sudo` for permissions to write to the specified target folder. The default location for a symlink is `/usr/local/bin/`. ``` $ sudo ln -s /folder/installed/aws-cli/aws /usr/local/bin/aws $ sudo ln -s /folder/installed/aws-cli/aws_completer /usr/local/bin/aws_completer ``` After installation is complete, debug logs are written to `/var/log/install.log`. 1. To verify that the shell can find and run the `aws` command in your `$PATH`, use the following commands. ``` $ which aws /usr/local/bin/aws $ aws --version aws-cli/2.27.41 Python/3.11.6 Darwin/23.3.0 ``` If the `aws` command cannot be found, you might need to restart your terminal or follow the troubleshooting in [Troubleshooting errors for the AWS CLI](cli-chap-troubleshooting.md). ------ ## Windows ### Installation requirements + You know which release of the AWS CLI version 2 you'd like to install. For a list of versions, see the [AWS CLI version 2 Changelog](https://raw.githubusercontent.com/aws/aws-cli/v2/CHANGELOG.rst) on *GitHub*. + We support the AWS CLI on Microsoft-supported versions of 64-bit Windows. + Admin rights to install software ### Installation instructions To update your current installation of AWS CLI version 2 on Windows, download a new installer each time you update to overwrite previous versions. AWS CLI is updated regularly. To see when the latest version was released, see the [AWS CLI version 2 Changelog](https://raw.githubusercontent.com/aws/aws-cli/v2/CHANGELOG.rst) on *GitHub*. 1. Download and run the AWS CLI MSI installer for Windows (64-bit) in one of the following ways: + **Downloading and running the MSI installer:** To create your download link for a specific version of the AWS CLI, append a hyphen and the version number to the filename. ``` https://awscli.amazonaws.com/AWSCLIV2-version.number.msi ``` For this example the filename for version *2.0.30* would be `AWSCLIV2-2.0.30.msi` resulting in the following link: [https://awscli.amazonaws.com/AWSCLIV2-2.0.30.msi](https://awscli.amazonaws.com/AWSCLIV2-2.0.30.msi). + **Using the msiexec command:** Alternatively, you can use the MSI installer by adding the link to the `msiexec` command. For a specific version of the AWS CLI, append a hyphen and the version number to the filename. ``` C:\> msiexec.exe /i https://awscli.amazonaws.com/AWSCLIV2-version.number.msi ``` For this example the filename for version *2.0.30* would be `AWSCLIV2-2.0.30.msi` resulting in the following link [https://awscli.amazonaws.com/AWSCLIV2-2.0.30.msi](https://awscli.amazonaws.com/AWSCLIV2-2.0.30.msi). ``` C:\> msiexec.exe /i https://awscli.amazonaws.com/AWSCLIV2-2.0.30.msi ``` For various parameters that can be used with `msiexec`, see [msiexec](https://docs.microsoft.com/en-us/windows-server/administration/windows-commands/msiexec) on the *Microsoft Docs* website. For a list of versions, see the [AWS CLI version 2 Changelog](https://raw.githubusercontent.com/aws/aws-cli/v2/CHANGELOG.rst) on *GitHub*. 1. To confirm the installation, open the **Start** menu, search for `cmd` to open a command prompt window, and at the command prompt use the `aws --version` command. ``` C:\> aws --version aws-cli/2.27.41 Python/3.11.6 Windows/10 exe/AMD64 prompt/off ``` If Windows is unable to find the program, you might need to close and reopen the command prompt window to refresh the path, or follow the troubleshooting in [Troubleshooting errors for the AWS CLI](cli-chap-troubleshooting.md). ## Troubleshooting AWS CLI install and uninstall errors If you come across issues after installing or uninstalling the AWS CLI, see [Troubleshooting errors for the AWS CLI](cli-chap-troubleshooting.md) for troubleshooting steps. For the most relevant troubleshooting steps, see [Command not found errors](cli-chap-troubleshooting.md#tshoot-install-not-found), [The "`aws --version`" command returns a different version than you installed](cli-chap-troubleshooting.md#tshoot-install-wrong-version), and [The "`aws --version`" command returns a version after uninstalling the AWS CLI](cli-chap-troubleshooting.md#tshoot-uninstall-1). ## Next steps After completing the steps in [Prerequisites to use the AWS CLI version 2](getting-started-prereqs.md) and installing the AWS CLI, you should perform a [Setting up the AWS CLI](getting-started-quickstart.md). # Building and installing the AWS CLI from source This topic describes how to install or update from source to the latest release of the AWS Command Line Interface (AWS CLI) on supported operating systems. For information on the latest releases of AWS CLI, see the [AWS CLI version 2 Changelog](https://raw.githubusercontent.com/aws/aws-cli/v2/CHANGELOG.rst) on GitHub. **Important** AWS CLI versions 1 and 2 use the same `aws` command name. If you previously installed AWS CLI version 1, see [Migration guide for the AWS CLI version 2](cliv2-migration.md). **Topics** + [ ## Why build from source? ](#source-getting-started-install-why) + [ ## Quicksteps ](#source-getting-started-install-quicksteps) + [ ## Step 1: Setup all requirements ](#source-getting-started-install-reqs) + [ ## Step 2: Configuring the AWS CLI source installation ](#source-getting-started-install-config) + [ ## Step 3: Building the AWS CLI ](#source-getting-started-install-build) + [ ## Step 4: Installing the AWS CLI ](#source-getting-started-install-instructions) + [ ## Step 5: Verifying the AWS CLI installation ](#source-getting-started-install-verify) + [ ## Workflow examples ](#source-getting-started-install-workflows) + [ ## Troubleshooting AWS CLI install and uninstall errors ](#source-install-tshoot) + [ ## Next steps ](#source-install-next-steps) ## Why build from source? The AWS CLI is [available as pre-built installers](getting-started-install.md) for most platforms and environments as well as a Docker image. Generally, these installers provide coverage for most use-cases. The instructions for installing from source are to help with the use-cases our installers do not cover. Some of these use-cases include the following: + The pre-built installers do not support your environment. For example, ARM 32-bit is not supported by the pre-built installers. + The pre-built installers have dependencies your environment lacks. For example, Alpine Linux uses [https://musl.libc.org/](https://musl.libc.org/), but the current installers require `glibc` causing the pre-built installers to not immediately work. + The pre-built installers require resources your environment restricts access to. For example, security hardened systems might not give permissions to shared memory. This is needed for the frozen `aws` installer. + The pre-built installers are often blockers for maintainers in package managers, as full control over the building process for code and packages is preferred. Building from source enables distribution maintainers a more streamlined process to keep the AWS CLI updated. Enabling maintainers provides customers more up-to-date versions of the AWS CLI when installing from a 3rd party package manager such as`brew`, `yum`, and `apt`. + Customers that patch AWS CLI functionality require building and installing the AWS CLI from source. This is especially important for community members that want to test changes they've made to the source prior to contributing the change to the AWS CLI GitHub repository. ## Quicksteps **Note** All code examples are assumed to run from the root of the source directory. To build and install the AWS CLI from source, follow the steps in this section. The AWS CLI leverages [GNU Autotools](https://www.gnu.org/software/automake/faq/autotools-faq.html) to install from source. In the simplest case, the AWS CLI can be installed from source by running the default example commands from the root of the AWS CLI GitHub repository. 1. [Setup all requirements for your environment.](#source-getting-started-install-reqs) This includes being able to run [GNU Autotools](https://www.gnu.org/software/automake/faq/autotools-faq.html) generated files and Python 3.8 or later is installed. 1. In your terminal, navigate to the top level of the AWS CLI source folder and run the `./configure` command. This command checks the system for all required dependencies and generates a `Makefile` for building and installing the AWS CLI based on detected and specified configurations. ------ #### [ Linux and macOS ] The following `./configure` command example sets the build configuration for the AWS CLI using default settings. ``` $ ./configure ``` ------ #### [ Windows PowerShell ] Before running any commands calling MSYS2, you must preserve your current working directory: ``` PS C:\> $env:CHERE_INVOKING = 'yes' ``` Then use the following `./configure` command example to set the build configuration for the AWS CLI using your local path to your Python executable, installing to C:\$1Program Files\$1AWSCLI, and downloading all dependencies. ``` PS C:\> C:\msys64\usr\bin\bash -lc " PYTHON='C:\path\to\python.exe' ./configure --prefix='C:\Program Files\AWSCLI' --with-download-deps " ``` ------ For details, available configuration options, and default setting information, see the [Step 2: Configuring the AWS CLI source installation](#source-getting-started-install-config) section. 1. Run the `make` command. This command builds the AWS CLI according to your configuration settings. The following `make` command example builds with default options using your existing `./configure` settings. ------ #### [ Linux and macOS ] ``` $ make ``` ------ #### [ Windows PowerShell ] ``` PS C:\> C:\msys64\usr\bin\bash -lc "make" ``` ------ For details and available build options, see the [Step 3: Building the AWS CLI](#source-getting-started-install-build) section. 1. Run the `make install` command. This command installs your built AWS CLI to the configured location on your system. The following `make install` command example installs your built AWS CLI and creates symlinks in your configured locations using default command settings. ------ #### [ Linux and macOS ] ``` $ make install ``` ------ #### [ Windows PowerShell ] ``` PS C:\> C:\msys64\usr\bin\bash -lc "make install" ``` After installing, add the path to the AWS CLI using the following: ``` PS C:\> $Env:PATH +=";C:\Program Files\AWSCLI\bin\" ``` ------ For details and available install options, see the [Step 4: Installing the AWS CLI](#source-getting-started-install-instructions) section. 1. Confirm the AWS CLI successfully installed using the following command: ``` $ aws --version aws-cli/2.27.41 Python/3.11.6 Windows/10 exe/AMD64 prompt/off ``` For troubleshooting steps for install errors see the [Troubleshooting AWS CLI install and uninstall errors](#source-install-tshoot) section. ## Step 1: Setup all requirements To build the AWS CLI from source you need the following completed beforehand: **Note** All code examples are assumed to run from the root of the source directory. 1. Download the AWS CLI source by either forking the AWS CLI GitHub repository or downloading the source tarball. The instructions is one of the following: + Fork and clone the [AWS CLI repository](https://github.com/aws/aws-cli) from *GitHub*. For more information, see [Fork a repo](https://docs.github.com/en/get-started/quickstart/fork-a-repo) in the *GitHub Docs*. + Download the latest source tarball at [https://awscli.amazonaws.com/awscli.tar.gz](https://awscli.amazonaws.com/awscli.tar.gz) extract the contents using the following commands: ``` $ curl "https://awscli.amazonaws.com/awscli.tar.gz" -o "awscli.tar.gz" $ tar -xzf awscli.tar.gz ``` **Note** To download a specific version, use the following link format: [https://awscli.amazonaws.com/awscli-*versionnumber*.tar.gz](https://awscli.amazonaws.com/awscli.tar.gz) For example, for version 2.10.0 the link is the following: [https://awscli.amazonaws.com/awscli-*2.10.0*.tar.gz](https://awscli.amazonaws.com/awscli.tar.gz) Source versions are available starting with version **2.10.0** of the AWS CLI. **(Optional) Verifying the integrity of your downloaded zip file by completing the following steps:** 1. You can use the following steps to verify the signatures by using the `GnuPG` tool. The AWS CLI installer package `.zip` files are cryptographically signed using PGP signatures. If there is any damage or alteration of the files, this verification fails and you should not proceed with installation. 1. Download and install the `gpg` command using your package manager. For more information about `GnuPG`, see the [GnuPG website](https://www.gnupg.org/). 1. To create the public key file, create a text file and paste in the following text. ``` -----BEGIN PGP PUBLIC KEY BLOCK----- mQINBF2Cr7UBEADJZHcgusOJl7ENSyumXh85z0TRV0xJorM2B/JL0kHOyigQluUG ZMLhENaG0bYatdrKP+3H91lvK050pXwnO/R7fB/FSTouki4ciIx5OuLlnJZIxSzx PqGl0mkxImLNbGWoi6Lto0LYxqHN2iQtzlwTVmq9733zd3XfcXrZ3+LblHAgEt5G TfNxEKJ8soPLyWmwDH6HWCnjZ/aIQRBTIQ05uVeEoYxSh6wOai7ss/KveoSNBbYz gbdzoqI2Y8cgH2nbfgp3DSasaLZEdCSsIsK1u05CinE7k2qZ7KgKAUIcT/cR/grk C6VwsnDU0OUCideXcQ8WeHutqvgZH1JgKDbznoIzeQHJD238GEu+eKhRHcz8/jeG 94zkcgJOz3KbZGYMiTh277Fvj9zzvZsbMBCedV1BTg3TqgvdX4bdkhf5cH+7NtWO lrFj6UwAsGukBTAOxC0l/dnSmZhJ7Z1KmEWilro/gOrjtOxqRQutlIqG22TaqoPG fYVN+en3Zwbt97kcgZDwqbuykNt64oZWc4XKCa3mprEGC3IbJTBFqglXmZ7l9ywG EEUJYOlb2XrSuPWml39beWdKM8kzr1OjnlOm6+lpTRCBfo0wa9F8YZRhHPAkwKkX XDeOGpWRj4ohOx0d2GWkyV5xyN14p2tQOCdOODmz80yUTgRpPVQUtOEhXQARAQAB tCFBV1MgQ0xJIFRlYW0gPGF3cy1jbGlAYW1hem9uLmNvbT6JAlQEEwEIAD4CGwMF CwkIBwIGFQoJCAsCBBYCAwECHgECF4AWIQT7Xbd/1cEYuAURraimMQrMRnJHXAUC aGveYQUJDMpiLAAKCRCmMQrMRnJHXKBYD/9Ab0qQdGiO5hObchG8xh8Rpb4Mjyf6 0JrVo6m8GNjNj6BHkSc8fuTQJ/FaEhaQxj3pjZ3GXPrXjIIVChmICLlFuRXYzrXc Pw0lniybypsZEVai5kO0tCNBCCFuMN9RsmmRG8mf7lC4FSTbUDmxG/QlYK+0IV/l uJkzxWa+rySkdpm0JdqumjegNRgObdXHAQDWlubWQHWyZyIQ2B4U7AxqSpcdJp6I S4Zds4wVLd1WE5pquYQ8vS2cNlDm4QNg8wTj58e3lKN47hXHMIb6CHxRnb947oJa pg189LLPR5koh+EorNkA1wu5mAJtJvy5YMsppy2y/kIjp3lyY6AmPT1posgGk70Z CmToEZ5rbd7ARExtlh76A0cabMDFlEHDIK8RNUOSRr7L64+KxOUegKBfQHb9dADY qqiKqpCbKgvtWlds909Ms74JBgr2KwZCSY1HaOxnIr4CY43QRqAq5YHOay/mU+6w hhmdF18vpyK0vfkvvGresWtSXbag7Hkt3XjaEw76BzxQH21EBDqU8WJVjHgU6ru+ DJTs+SxgJbaT3hb/vyjlw0lK+hFfhWKRwgOXH8vqducF95NRSUxtS4fpqxWVaw3Q V2OWSjbne99A5EPEySzryFTKbMGwaTlAwMCwYevt4YT6eb7NmFhTx0Fis4TalUs+ j+c7Kg92pDx2uQ== =OBAt -----END PGP PUBLIC KEY BLOCK----- ``` For reference, the following are the details of the public key. ``` Key ID: A6310ACC4672 Type: RSA Size: 4096/4096 Created: 2019-09-18 Expires: 2026-07-07 User ID: AWS CLI Team Key fingerprint: FB5D B77F D5C1 18B8 0511 ADA8 A631 0ACC 4672 475C ``` 1. Import the AWS CLI public key with the following command, substituting *public-key-file-name* with the file name of the public key you created. ``` $ gpg --import public-key-file-name gpg: /home/username/.gnupg/trustdb.gpg: trustdb created gpg: key A6310ACC4672475C: public key "AWS CLI Team " imported gpg: Total number processed: 1 gpg: imported: 1 ``` 1. Download the AWS CLI signature file for the package you downloaded at [https://awscli.amazonaws.com/awscli.tar.gz.sig](https://awscli.amazonaws.com/awscli.tar.gz.sig). It has the same path and name as the tarball file it corresponds to, but has the extension `.sig`. Save it in the same path as the tarball file. Or use the following command block: ``` $ curl awscliv2.sig https://awscli.amazonaws.com/ -o awscli.tar.gz.sig ``` 1. Verify the signature, passing both the downloaded `.sig` and `.zip` file names as parameters to the `gpg` command. ``` $ gpg --verify awscliv2.sig awscli.tar.gz ``` The output should look similar to the following. ``` gpg: Signature made Mon Nov 4 19:00:01 2019 PST gpg: using RSA key FB5D B77F D5C1 18B8 0511 ADA8 A631 0ACC 4672 475C gpg: Good signature from "AWS CLI Team " [unknown] gpg: WARNING: This key is not certified with a trusted signature! gpg: There is no indication that the signature belongs to the owner. Primary key fingerprint: FB5D B77F D5C1 18B8 0511 ADA8 A631 0ACC 4672 475C ``` **Important** The warning in the output is expected and doesn't indicate a problem. It occurs because there isn't a chain of trust between your personal PGP key (if you have one) and the AWS CLI PGP key. For more information, see [Web of trust](https://wikipedia.org/wiki/Web_of_trust). 1. You have an environment that can run [GNU Autotools](https://www.gnu.org/software/automake/faq/autotools-faq.html) generated files such as `configure` and `Makefile`. These files are widely portable across POSIX platforms. ------ #### [ Linux and macOS ] If Autotools is not already installed in your environment or you need to update them, then follow the installation instructions found in [How do I install the Autotools (as user)?](https://www.gnu.org/software/automake/faq/autotools-faq.html#How-do-I-install-the-Autotools-_0028as-user_0029_003f) or [Basic Installation](https://www.gnu.org/savannah-checkouts/gnu/automake/manual/automake.html#Basic-Installation) in the *GNU documentation*. ------ #### [ Windows PowerShell ] **Warning** We suggest if you are in a Windows environment, you use the pre-built installers. For install instructions on the pre-built installers, see [Installing or updating to the latest version of the AWS CLI](getting-started-install.md) Since Windows does not come with a POSIX-compliant shell, you need to install additional software to install the AWS CLI from source. [MSYS2](https://www.msys2.org/) provides a collection of tools and libraries to help build and install Windows software, especially for the POSIX-based scripting that Autotools uses. 1. Install MSYS2. For information on installing and using MSYS2, see the [install and usage instructions](https://www.msys2.org/) in the *MSYS2 Documentation*. 1. Open the MSYS2 terminal and install autotools using the following command. ``` $ pacman -S autotools ``` **Note** When using the configure, build, and install code examples in this guide for Windows, the default MSYS2 install path of `C:\msys64\usr\bin\bash` is assumed. When calling MSYS2 inside of PowerShell you'll be using the following format, with the bash command in quotes: ``` PS C:\> C:\msys64\usr\bin\bash -lc "command example" ``` The following command example calls the `./configure` command. ``` PS C:\> C:\msys64\usr\bin\bash -lc "./configure" ``` ------ 1. A Python 3.8 or later interpreter is installed. The minimum Python version required follows the same timelines as the official[ Python support policy for AWS SDKs and Tools](https://aws.amazon.com/blogs/developer/python-support-policy-updates-for-aws-sdks-and-tools/). An interpreter is only supported 6 months after its end-of-support date. 1. **(Optional)** Install all build and runtime Python library dependencies of the AWS CLI. The `./configure` command informs you if you are missing any dependencies and how to install them. You can automatically install and use these dependencies through configuration, see [Downloading dependencies](#source-getting-started-install-config-dependencies) for more information. ## Step 2: Configuring the AWS CLI source installation Configuration for building and installing the AWS CLI is specified using the `configure` script. For the documentation of all configuration options, run the `configure` script with the `--help` option: ------ #### [ Linux and macOS ] ``` $ ./configure --help ``` ------ #### [ Windows PowerShell ] ``` PS C:\> C:\msys64\usr\bin\bash -lc "./configure --help" ``` ------ **Topics** + [ ### Install location ](#source-getting-started-install-config-location) + [ ### Python interpreter ](#source-getting-started-install-config-interpreter) + [ ### Downloading dependencies ](#source-getting-started-install-config-dependencies) + [ ### Install type ](#source-getting-started-install-config-type) ### Install location The source installation of the AWS CLI uses two configurable directories to install the AWS CLI: + `libdir` - Parent directory where the AWS CLI will be installed. The path to the AWS CLI installation is `/aws-cli`. The default `libdir` value for Linux and macOS is `/usr/local/lib` making the default installation directory `/usr/local/lib/aws-cli` + `bindir` - Directory where the AWS CLI executables are installed. The default location is `/usr/local/bin`. The following `configure` options control the directories used: + `--prefix` - Sets the directory prefix to use for the installation. The default value for Linux and macOS is `/usr/local`. + `--libdir` - Sets the `libdir` to use for installing the AWS CLI. The default value is `/lib`. If both `--libdir` and `--prefix` are not specified, the default for Linux and macOS is `/usr/local/lib/`. + `--bindir` - Sets the `bindir` to use for installing the AWS CLI `aws` and `aws_completer` executables. The default value is `/bin`. If both `bindir` and `--prefix` are not specified, the default for Linux and macOS is `/usr/local/bin/`. ------ #### [ Linux and macOS ] The following command example uses the `--prefix` option to do a local user install of the AWS CLI. This command installs the AWS CLI in `$HOME/.local/lib/aws-cli` and the executables in `$HOME/.local/bin`: ``` $ ./configure --prefix=$HOME/.local ``` The following command example uses the `--libdir` option to install the AWS CLI as an add-on application in the `/opt` directory. This command installs the AWS CLI at `/opt/aws-cli` and the executables at their default location of `/usr/local/bin`. ``` $ ./configure --libdir=/opt ``` ------ #### [ Windows PowerShell ] The following command example uses the `--prefix` option to do a local user install of the AWS CLI. This command installs the AWS CLI in `$HOME/.local/lib/aws-cli` and the executables in `$HOME/.local/bin`: ``` $ C:\msys64\usr\bin\bash -lc "./configure --prefix='C:\Program Files\AWSCLI'" ``` The following command example uses the `--libdir` option to install the AWS CLI as an add-on application in the `/opt` directory. This command installs the AWS CLI at `C:\Program Files\AWSCLI\opt\aws-cli`. ------ ### Python interpreter **Note** It is highly recommended to specify the Python interpreter when installing for Windows. The `./configure` script automatically selects an installed Python 3.8 or later interpreter to use in building and running the AWS CLI using the [https://www.gnu.org/software/automake/manual/html_node/Python.html](https://www.gnu.org/software/automake/manual/html_node/Python.html) Autoconf macro. The Python interpreter to use can be explicitly set using the `PYTHON` environment variable when running the `configure` script: ------ #### [ Linux and macOS ] ``` $ PYTHON=/path/to/python ./configure ``` ------ #### [ Windows PowerShell ] ``` PS C:\> C:\msys64\usr\bin\bash -lc "PYTHON='C:\path\to\python' ./configure" ``` ------ ### Downloading dependencies By default, it is required that all build and runtime dependencies of the AWS CLI are already installed on the system. This includes any Python library dependencies. All dependencies are checked when the `configure` script is run, and if the system is missing any Python dependencies, the `configure` script errors out. The following code example errors out when your system is missing dependencies: ------ #### [ Linux and macOS ] ``` $ ./configure checking for a Python interpreter with version >= 3.8... python checking for python... /Users/username/.envs/env3.11/bin/python checking for python version... 3.11 checking for python platform... darwin checking for GNU default python prefix... ${prefix} checking for GNU default python exec_prefix... ${exec_prefix} checking for python script directory (pythondir)... ${PYTHON_PREFIX}/lib/python3.11/site-packages checking for python extension module directory (pyexecdir)... ${PYTHON_EXEC_PREFIX}/lib/python3.11/site-packages checking for --with-install-type... system-sandbox checking for --with-download-deps... Traceback (most recent call last): File "", line 198, in _run_module_as_main File "", line 88, in _run_code File "/Users/username/aws-code/aws-cli/./backends/build_system/__main__.py", line 125, in main() File "/Users/username/aws-code/aws-cli/./backends/build_system/__main__.py", line 121, in main parsed_args.func(parsed_args) File "/Users/username/aws-code/aws-cli/./backends/build_system/__main__.py", line 49, in validate validate_env(parsed_args.artifact) File "/Users/username/aws-code/aws-cli/./backends/build_system/validate_env.py", line 68, in validate_env raise UnmetDependenciesException(unmet_deps, in_venv) validate_env.UnmetDependenciesException: Environment requires following Python dependencies: awscrt (required: ('>=0.12.4', '<0.17.0')) (version installed: None) We recommend using --with-download-deps flag to automatically create a virtualenv and download the dependencies. If you want to manage the dependencies yourself instead, run the following pip command: /Users/username/.envs/env3.11/bin/python -m pip install --prefer-binary 'awscrt>=0.12.4,<0.17.0' configure: error: "Python dependencies not met." ``` ------ #### [ Windows PowerShell ] ``` PS C:\> C:\msys64\usr\bin\bash -lc "./configure" checking for a Python interpreter with version >= 3.8... python checking for python... /Users/username/.envs/env3.11/bin/python checking for python version... 3.11 checking for python platform... darwin checking for GNU default python prefix... ${prefix} checking for GNU default python exec_prefix... ${exec_prefix} checking for python script directory (pythondir)... ${PYTHON_PREFIX}/lib/python3.11/site-packages checking for python extension module directory (pyexecdir)... ${PYTHON_EXEC_PREFIX}/lib/python3.11/site-packages checking for --with-install-type... system-sandbox checking for --with-download-deps... Traceback (most recent call last): File "", line 198, in _run_module_as_main File "", line 88, in _run_code File "/Users/username/aws-code/aws-cli/./backends/build_system/__main__.py", line 125, in main() File "/Users/username/aws-code/aws-cli/./backends/build_system/__main__.py", line 121, in main parsed_args.func(parsed_args) File "/Users/username/aws-code/aws-cli/./backends/build_system/__main__.py", line 49, in validate validate_env(parsed_args.artifact) File "/Users/username/aws-code/aws-cli/./backends/build_system/validate_env.py", line 68, in validate_env raise UnmetDependenciesException(unmet_deps, in_venv) validate_env.UnmetDependenciesException: Environment requires following Python dependencies: awscrt (required: ('>=0.12.4', '<0.17.0')) (version installed: None) We recommend using --with-download-deps flag to automatically create a virtualenv and download the dependencies. If you want to manage the dependencies yourself instead, run the following pip command: /Users/username/.envs/env3.11/bin/python -m pip install --prefer-binary 'awscrt>=0.12.4,<0.17.0' configure: error: "Python dependencies not met." ``` ------ To automatically install the required Python dependencies, use the `--with-download-deps` option. When using this flag, the build process does the following: + Skips the Python library dependencies check. + Configures the settings to download all required Python dependencies and use **only** the downloaded dependencies to build the AWS CLI during the `make` build. The following configure command example uses the `--with-download-deps` option to download and use the Python dependencies: ------ #### [ Linux and macOS ] ``` $ ./configure --with-download-deps ``` ------ #### [ Windows PowerShell ] ``` PS C:\> C:\msys64\usr\bin\bash -lc "./configure --with-download-deps" ``` ------ ### Install type The source install process supports the following installation types: + `system-sandbox` - **(Default)** Creates an isolated Python virtual environment, installs the AWS CLI into the virtual environment, and symlinks to the `aws` and `aws_completer` executable in the virtual environment. This install of the AWS CLI depends directly on the selected Python interpreter for its runtime. This is a lightweight install mechanism to get the AWS CLI installed on a system and follows best Python practices by sandboxing the installation in a virtual environment. This installation is intended for customers that want to install the AWS CLI from source in the most frictionless way possible with the installation coupled to your installation of Python. + `portable-exe` - Freezes the AWS CLI into a standalone executable that can be distributed to environments of similar architectures. This is the same process used to generate the official pre-built executables of the AWS CLI. The `portable-exe` freezes in a copy of the Python interpreter chosen in the `configure` step to use for the runtime of the AWS CLI. This allows it to be moved to other machines that may not have a Python interpreter. This type of builds is useful because you can ensure your AWS CLI installation isn't coupled to the environment's installed Python version and you can distribute a build to other system that may not already have Python installed. This enables you to control the dependencies and security on the AWS CLI executables you use. To configure the installation type, use the `--with-install-type` option and specify a value of `portable-exe` or `system-sandbox`. The following `./configure` command example specifies a value of `portable-exe`: ------ #### [ Linux and macOS ] ``` $ ./configure --with-install-type=portable-exe ``` ------ #### [ Windows PowerShell ] ``` PS C:\> C:\msys64\usr\bin\bash -lc "./configure --with-install-type=portable-exe" ``` ------ ## Step 3: Building the AWS CLI Use the `make` command to build the AWS CLI using your configuration settings: ------ #### [ Linux and macOS ] ``` $ make ``` ------ #### [ Windows PowerShell ] ``` PS C:\> C:\msys64\usr\bin\bash -lc "make" ``` ------ **Note** A virtual environment is created in the build directory using the Python [https://docs.python.org/3/library/venv.html](https://docs.python.org/3/library/venv.html) module. The virtual environment is bootstraped with a [version of pip that is vendored in the Python standard library](https://docs.python.org/3/library/ensurepip.html). Copies Python library dependencies. Depending on if the `--with-download-deps` flag is specified in the `configure` command, this step does one of the following: The `--with-download-deps` **is** specified. Python dependencies are pip installed. This includes `wheel`, `setuptools`, and all AWS CLI runtime dependencies. If you are building the `portable-exe`, `pyinstaller` is installed. These requirements are all specified in lock files generated from [https://github.com/jazzband/pip-tools](https://github.com/jazzband/pip-tools). The `--with-download-deps` **is not** specified. Python libraries from the Python interpreter's site package plus any scripts (e.g. `pyinstaller`) are copied into the virtual environment being used for the build. Runs `pip install` directly on the AWS CLI codebase to do an offline, in-tree build and install of the AWS CLI into the build virtual environment. This install uses the pip flags [--no-build-isolation ](https://pip.pypa.io/en/stable/cli/pip_install/#cmdoption-no-build-isolation), [--use-feature=in-tree-build ](https://pip.pypa.io/en/stable/cli/pip_install/#local-project-installs), [--no-cache-dir ](https://pip.pypa.io/en/stable/cli/pip_install/#caching), and [https://pip.pypa.io/en/stable/cli/pip_install/#cmdoption-no-index](https://pip.pypa.io/en/stable/cli/pip_install/#cmdoption-no-index). **(Optional)** If the `--install-type` is set to `portable-exe` in the `configure` command, builds a standalone executable using [https://www.pyinstaller.org/](https://www.pyinstaller.org/). ## Step 4: Installing the AWS CLI The `make install` command installs your built AWS CLI to the configured location on the system. ------ #### [ Linux and macOS ] The following command example installs the AWS CLI using your configuration and build settings: ``` $ make install ``` ------ #### [ Windows PowerShell ] The following command example installs the AWS CLI using your configuration and build settings, then adds an environment variable with the path for the AWS CLI: ``` PS C:\> C:\msys64\usr\bin\bash -lc " make install " PS C:\> $Env:PATH +=";C:\Program Files\AWSCLI\bin\" ``` ------ The `make install` rule supports the [https://www.gnu.org/software/make/manual/html_node/DESTDIR.html#DESTDIR](https://www.gnu.org/software/make/manual/html_node/DESTDIR.html#DESTDIR) variable. When specified, this variable prefixes the specified path to the already configured installation path when installing the AWS CLI. By default, no value is set for this variable. ------ #### [ Linux and macOS ] The following code example uses a `--prefix=/usr/local` flag for configuring an install location, and then alters that destination using `DESTDIR=/tmp/stage` for the `make install` command. These commands result in the AWS CLI being installed at `/tmp/stage/usr/local/lib/aws-cli` and its executables located in `/tmp/stage/usr/local/bin`. ``` $ ./configure --prefix=/usr/local $ make $ make DESTDIR=/tmp/stage install ``` ------ #### [ Windows PowerShell ] The following code example uses a `--prefix=\awscli` flag for configuring an install location, and then alters that destination using `DESTDIR=C:\Program Files` for the `make install` command. These commands result in the AWS CLI being installed at `C:\Program Files\awscli`. ``` $ ./configure --prefix=\awscli $ make $ make DESTDIR='C:\Program Files' install ``` ------ **Note** Moves one of the following to the configured install directory: If the install type is `system-sandbox`, moves your built virtual environment. If the install type is a `portable-exe`, moves your built standalone executable. Creates symlinks for both the `aws` and `aws_completer` executables in your configured bin directory. ## Step 5: Verifying the AWS CLI installation Confirm the AWS CLI successfully installed by using the following command: ``` $ aws --version aws-cli/2.27.41 Python/3.11.6 Windows/10 exe/AMD64 prompt/off ``` If the `aws` command is not recognized, you may need to restart your terminal for new symlinks to update. If you come across additional issues after installing or uninstalling the AWS CLI, see [Troubleshooting errors for the AWS CLI](cli-chap-troubleshooting.md) for common troubleshooting steps ## Workflow examples This section provides some basic workflow examples for installing from source. ### Basic Linux and macOS install The following example is a basic installation workflow where the AWS CLI is installed in the default location of `/usr/local/lib/aws-cli`. ``` $ cd path/to/cli/respository/ $ ./configure $ make $ make install ``` ### Automated Windows install **Note** You must run PowerShell as an Administrator to use this workflow. MSYS2 can be used in an automated fashion in a CI setting, see [Using MSYS2 in CI](https://www.msys2.org/docs/ci/) in the *MSYS2 Documentation*. ------ #### [ Downloaded Tarball ] Download the `awscli.tar.gz` file, extract, and install the AWS CLI. When using the following commands, replace the following paths: + `C:\msys64\usr\bin\bash` with the location of your MSYS2 path. + `.\awscli-2.x.x\` with the extracted `awscli.tar.gz` folder name. + `PYTHON='C:\path\to\python.exe'` with your local Python path. The following code example automates building and installing the AWS CLI from PowerShell using MSYS2, and specifies which local install of Python to use: ``` PS C:\> curl "https://awscli.amazonaws.com/awscli.tar.gz" -o "awscliv2.zip" # Download the awscli.tar.gz file in the current working directory PS C:\> tar -xvzf .\awscli.tar.gz # Extract awscli.tar.gz file PS C:\> cd .\awscli-2.x.x\ # Navigate to the root of the extracted files PS C:\> $env:CHERE_INVOKING = 'yes' # Preserve the current working directory PS C:\> C:\msys64\usr\bin\bash -lc " PYTHON='C:\path\to\python.exe' ./configure --prefix='C:\Program Files\AWSCLI' --with-download-deps " PS C:\> C:\msys64\usr\bin\bash -lc "make" PS C:\> C:\msys64\usr\bin\bash -lc "make install" PS C:\> $Env:PATH +=";C:\Program Files\AWSCLI\bin\" PS C:\> aws --version aws-cli/2.27.41 Python/3.11.6 Windows/10 source-sandbox/AMD64 ``` ------ #### [ GitHub Repository ] Download the `awscli.tar.gz` file, extract, and install the AWS CLI. When using the following commands, replace the following paths: + `C:\msys64\usr\bin\bash` with the location of your MSYS2 path. + `C:path\to\cli\repository\` with the path to your cloned [AWS CLI repository](https://github.com/aws/aws-cli) from *GitHub*. For more information, see [Fork a repo](https://docs.github.com/en/get-started/quickstart/fork-a-repo) in the *GitHub Docs* + `PYTHON='C:\path\to\python.exe'` with your local Python path. The following code example automates building and installing the AWS CLI from PowerShell using MSYS2, and specifies which local install of Python to use: ``` PS C:\> cd C:path\to\cli\repository\ PS C:\> $env:CHERE_INVOKING = 'yes' # Preserve the current working directory PS C:\> C:\msys64\usr\bin\bash -lc " PYTHON='C:\path\to\python.exe' ./configure --prefix='C:\Program Files\AWSCLI' --with-download-deps " PS C:\> C:\msys64\usr\bin\bash -lc "make" PS C:\> C:\msys64\usr\bin\bash -lc "make install" PS C:\> $Env:PATH +=";C:\Program Files\AWSCLI\bin\" PS C:\> aws --version ``` ------ ### Alpine Linux container Below is an example Dockerfile that can be used to get a working installation of the AWS CLI in an Alpine Linux container as an [alternative to pre-built binaries for Alpine](https://github.com/aws/aws-cli/issues/4685). When using this example, replace *AWSCLI\$1VERSION* with you desired AWS CLI version number: ``` 1. FROM python:3.8-alpine AS builder 2. 3. ENV AWSCLI_VERSION=2.10.1 4. 5. RUN apk add --no-cache \ 6. curl \ 7. make \ 8. cmake \ 9. gcc \ 10. g++ \ 11. libc-dev \ 12. libffi-dev \ 13. openssl-dev \ 14. && curl https://awscli.amazonaws.com/awscli-${AWSCLI_VERSION}.tar.gz | tar -xz \ 15. && cd awscli-${AWSCLI_VERSION} \ 16. && ./configure --prefix=/opt/aws-cli/ --with-download-deps \ 17. && make \ 18. && make install 19. 20. FROM python:3.8-alpine 21. 22. RUN apk --no-cache add groff 23. 24. COPY --from=builder /opt/aws-cli/ /opt/aws-cli/ 25. 26. ENTRYPOINT ["/opt/aws-cli/bin/aws"] ``` This image is built and the AWS CLI invoked from a container similar to the one that is built on Amazon Linux 2: ``` $ docker build --tag awscli-alpine . $ docker run --rm -it awscli-alpine --version aws-cli/2.2.1 Python/3.8.11 Linux/5.10.25-linuxkit source-sandbox/x86_64.alpine.3 prompt/off ``` The final size of this image is smaller than the size of the official AWS CLI Docker image. For information on the official Docker image, see [Running the official Amazon ECR Public or Docker images for the AWS CLI](getting-started-docker.md). ## Troubleshooting AWS CLI install and uninstall errors For troubleshooting steps for install errors, see [Troubleshooting errors for the AWS CLI](cli-chap-troubleshooting.md) for common troubleshooting steps. For the most relevant troubleshooting steps, see [Command not found errors](cli-chap-troubleshooting.md#tshoot-install-not-found), [The "`aws --version`" command returns a different version than you installed](cli-chap-troubleshooting.md#tshoot-install-wrong-version), and [The "`aws --version`" command returns a version after uninstalling the AWS CLI](cli-chap-troubleshooting.md#tshoot-uninstall-1). For any issues not covered in the troubleshooting guides, search the issues with the `source-distribution` label in the [AWS CLI Repository](https://github.com/aws/aws-cli/labels/source-distribution) on *GitHub*. If no existing issues cover your errors, [create a new issue](https://github.com/aws/aws-cli/issues/new?assignees=&labels=source-distribution%2Cneeds-triage&template=source-distribution.yml&title=%28short+issue+description%29) to receive help from the AWS CLI maintainers. ## Next steps After installing the AWS CLI, you should perform a [Setting up the AWS CLI](getting-started-quickstart.md). # Running the official Amazon ECR Public or Docker images for the AWS CLI This topic describes how to run, version control, and configure the AWS CLI version 2 on Docker using either the official Amazon Elastic Container Registry Public (Amazon ECR Public) or Docker Hub image. For more information on how to use Docker, see [Docker's documentation](https://docs.docker.com/). Official images provide isolation, portability, and security that AWS directly supports and maintains. This enables you to use the AWS CLI version 2 in a container-based environment without having to manage the installation yourself. **Topics** + [ ## Prerequisites ](#cliv2-docker-prereq) + [ ## Deciding between Amazon ECR Public and Docker Hub ](#cliv2-docker-versus) + [ ## Run the official AWS CLI version 2 images ](#cliv2-docker-install) + [ ## Notes on interfaces and backwards compatibility of the official images ](#cliv2-docker-install-notes) + [ ## Use specific versions and tags ](#cliv2-docker-upgrade) + [ ## Update to the latest official image ](#cliv2-docker-update) + [ ## Share host files, credentials, environment variables, and configuration ](#cliv2-docker-share-files) + [ ## Shorten the docker run command ](#cliv2-docker-aliases) ## Prerequisites You must have Docker installed. For installation instructions, see the [Docker website](https://docs.docker.com/install/). To verify your installation of Docker, run the following command and confirm there is an output. ``` $ docker --version Docker version 19.03.1 ``` ## Deciding between Amazon ECR Public and Docker Hub We recommend using Amazon ECR Public over Docker Hub for AWS CLI images. Docker Hub has stricter rate limiting for public consumers which can cause throttling issues. In addition, Amazon ECR Public replicates images in more than one region to provide strong availability and handle region outage issues. For more information on Docker Hub rate limiting see [Understanding Docker Hub Rate Limiting](https://www.docker.com/increase-rate-limits/) on the *Docker* website. ## Run the official AWS CLI version 2 images The first time you use the `docker run` command, the latest image is downloaded to your computer. Each subsequent use of the `docker run` command runs from your local copy. To run the AWS CLI version 2 Docker images, use the `docker run` command. ------ #### [ Amazon ECR Public ] The official AWS CLI version 2 Amazon ECR Public image is hosted on Amazon ECR Public in the [`aws-cli/aws-cli` repository](https://gallery.ecr.aws/aws-cli/aws-cli). ``` $ docker run --rm -it public.ecr.aws/aws-cli/aws-cli command ``` ------ #### [ Docker Hub ] The official AWS CLI version 2 Docker image is hosted on Docker Hub in the `amazon/aws-cli` repository. ``` $ docker run --rm -it amazon/aws-cli command ``` ------ This is how the command functions: + `docker run --rm -it repository/name` – The equivalent of the `aws` executable. Each time you run this command, Docker spins up a container of your downloaded image, and executes your `aws` command. By default, the image uses the latest version of the AWS CLI version 2. For example, to call the `aws --version` command in Docker, you run the following. ------ #### [ Amazon ECR Public ] ``` $ docker run --rm -it public.ecr.aws/aws-cli/aws-cli --version aws-cli/2.27.41 Python/3.7.3 Linux/4.9.184-linuxkit botocore/2.4.5dev10 ``` ------ #### [ Docker Hub ] ``` $ docker run --rm -it amazon/aws-cli --version aws-cli/2.27.41 Python/3.7.3 Linux/4.9.184-linuxkit botocore/2.4.5dev10 ``` ------ + `--rm` – Specifies to clean up the container after the command exits. + `-it` – Specifies to open a pseudo-TTY with `stdin`. This enables you to provide input to the AWS CLI version 2 while it's running in a container, for example, by using the `aws configure` and `aws help` commands. When choosing whether to omit `-it`, consider the following: + If you are running scripts, `-it` is not needed. + If you are experiencing errors with your scripts, omitting `-it` from your Docker call might fix the issue. + If you are trying to pipe output, `-it` might cause errors and omitting `-it` from your Docker call might resolve this issue. If you'd like to keep the `-it` flag, but still would like to pipe output, disabling the [client-side pager](cli-usage-pagination.md#cli-usage-pagination-clientside) the AWS CLI uses by default should resolve the issue. For more information about the `docker run` command, see the [Docker reference guide](https://docs.docker.com/engine/reference/run/). ## Notes on interfaces and backwards compatibility of the official images + The only tool supported on the image is the AWS CLI. Only the `aws` executable should ever be directly run. For example, even though `less` and `groff` are explicitly installed on the image, they should not be executed directly outside of an AWS CLI command. + The `/aws` working directory is user controlled. The image will not write to this directory, unless instructed by the user in running an AWS CLI command. + There are no backwards compatibility guarantees in relying on the latest tag. To guarantee backwards compatibility, you must pin to a specific `` tag as those tags are immutable; they will only ever be pushed to once. ## Use specific versions and tags The official AWS CLI version 2 image has multiple versions you can use, starting with version `2.0.6`. To run a specific version of the AWS CLI version 2, append the appropriate tag to your `docker run` command. The first time you use the `docker run` command with a tag, the latest image for that tag is downloaded to your computer. Each subsequent use of the `docker run` command with that tag runs from your local copy. You can use two types of tags: + `latest` – Defines the latest version of the AWS CLI version 2 for the image. We recommend you use the `latest` tag when you want the latest version of the AWS CLI version 2. However, there are no backward-compatibility guarantees when relying on this tag. The `latest` tag is used by default in the `docker run` command. To explicitly use the `latest` tag, append the tag to the container image name. ------ #### [ Amazon ECR Public ] ``` $ docker run --rm -it public.ecr.aws/aws-cli/aws-cli:latest command ``` ------ #### [ Docker Hub ] ``` $ docker run --rm -it amazon/aws-cli:latest command ``` ------ + `` – Defines a specific version of the AWS CLI version 2 for the image. If you plan to use an official image in production, we recommend you use a specific version of the AWS CLI version 2 to ensure backward compatibility. For example, to run version `2.0.6`, append the version to the container image name. ------ #### [ Amazon ECR Public ] ``` $ docker run --rm -it public.ecr.aws/aws-cli/aws-cli:2.0.6 command ``` ------ #### [ Docker Hub ] ``` $ docker run --rm -it amazon/aws-cli:2.0.6 command ``` ------ ## Update to the latest official image Because the latest image is downloaded to your computer only the first time you use the `docker run` command, you need to manually pull an updated image. To manually update to the latest version, we recommend you pull the `latest` tagged image. Pulling the image downloads the latest version to your computer. ------ #### [ Amazon ECR Public ] ``` $ docker pull public.ecr.aws/aws-cli/aws-cli:latest ``` ------ #### [ Docker Hub ] ``` $ docker pull amazon/aws-cli:latest ``` ------ ## Share host files, credentials, environment variables, and configuration Because the AWS CLI version 2 is run in a container, by default the CLI can't access the host file system, which includes configuration and credentials. To share the host file system, credentials, and configuration to the container, mount the host system’s `~/.aws` directory to the container at `/root/.aws` with the `-v` flag to the `docker run` command. This allows the AWS CLI version 2 running in the container to locate host file information. ------ #### [ Amazon ECR Public ] **Linux and macOS** ``` $ docker run --rm -it -v ~/.aws:/root/.aws public.ecr.aws/aws-cli/aws-cli command ``` **Windows Command Prompt** ``` $ docker run --rm -it -v %userprofile%\.aws:/root/.aws public.ecr.aws/aws-cli/aws-cli command ``` **Windows PowerShell** ``` C:\> docker run --rm -it -v $env:userprofile\.aws:/root/.aws public.ecr.aws/aws-cli/aws-cli command ``` ------ #### [ Docker Hub ] **Linux and macOS** ``` $ docker run --rm -it -v ~/.aws:/root/.aws amazon/aws-cli command ``` **Windows Command Prompt** ``` $ docker run --rm -it -v %userprofile%\.aws:/root/.aws amazon/aws-cli command ``` **Windows PowerShell** ``` C:\> docker run --rm -it -v $env:userprofile\.aws:/root/.aws amazon/aws-cli command ``` ------ For more information about the `-v` flag and mounting, see the [Docker reference guide](https://docs.docker.com/storage/volumes/). **Note** For information on `config` and `credentials` files, see [Configuration and credential file settings in the AWS CLI](cli-configure-files.md). ### Example 1: Providing credentials and configuration In this example, we're providing host credentials and configuration when running the `s3 ls` command to list your buckets in Amazon Simple Storage Service (Amazon S3). The below examples use the default location for AWS CLI credentials and configuration files, to use a different location, change the file path. ------ #### [ Amazon ECR Public ] **Linux and macOS** ``` $ docker run --rm -it -v ~/.aws:/root/.aws public.ecr.aws/aws-cli/aws-cli s3 ls 2020-03-25 00:30:48 aws-cli-docker-demo ``` **Windows Command Prompt** ``` $ docker run --rm -it -v %userprofile%\.aws:/root/.aws public.ecr.aws/aws-cli/aws-cli s3 ls 2020-03-25 00:30:48 aws-cli-docker-demo ``` **Windows PowerShell** ``` C:\> docker run --rm -it -v $env:userprofile\.aws:/root/.aws public.ecr.aws/aws-cli/aws-cli s3 ls ``` ------ #### [ Docker Hub ] **Linux and macOS** ``` $ docker run --rm -it -v ~/.aws:/root/.aws amazon/aws-cli s3 ls 2020-03-25 00:30:48 aws-cli-docker-demo ``` **Windows Command Prompt** ``` $ docker run --rm -it -v %userprofile%\.aws:/root/.aws amazon/aws-cli s3 ls 2020-03-25 00:30:48 aws-cli-docker-demo ``` **Windows PowerShell** ``` C:\> docker run --rm -it -v $env:userprofile\.aws:/root/.aws amazon/aws-cli s3 ls ``` ------ You can call specific system's environment variables using the `-e` flag. To use an environment variable, call it by name. ------ #### [ Amazon ECR Public ] **Linux and macOS** ``` $ docker run --rm -it -v ~/.aws:/root/.aws -e ENVVAR_NAME public.ecr.aws/aws-cli/aws-cli s3 ls 2020-03-25 00:30:48 aws-cli-docker-demo ``` **Windows Command Prompt** ``` $ docker run --rm -it -v %userprofile%\.aws:/root/.aws -e ENVVAR_NAME public.ecr.aws/aws-cli/aws-cli s3 ls 2020-03-25 00:30:48 aws-cli-docker-demo ``` **Windows PowerShell** ``` C:\> docker run --rm -it -v $env:userprofile\.aws:/root/.aws -e ENVVAR_NAME public.ecr.aws/aws-cli/aws-cli s3 ls ``` ------ #### [ Docker Hub ] **Linux and macOS** ``` $ docker run --rm -it -v ~/.aws:/root/.aws -e ENVVAR_NAME amazon/aws-cli s3 ls 2020-03-25 00:30:48 aws-cli-docker-demo ``` **Windows Command Prompt** ``` $ docker run --rm -it -v %userprofile%\.aws:/root/.aws -e ENVVAR_NAME amazon/aws-cli s3 ls 2020-03-25 00:30:48 aws-cli-docker-demo ``` **Windows PowerShell** ``` C:\> docker run --rm -it -v $env:userprofile\.aws:/root/.aws -e ENVVAR_NAME amazon/aws-cli s3 ls ``` ------ ### Example 2: Downloading an Amazon S3 file to your host system For some AWS CLI version 2 commands, you can read files from the host system in the container or write files from the container to the host system. In this example, we download the `S3` object `s3://aws-cli-docker-demo/hello` to your local file system by mounting the current working directory to the container's `/aws` directory. By downloading the `hello` object to the container's `/aws` directory, the file is saved to the host system’s current working directory also. ------ #### [ Amazon ECR Public ] **Linux and macOS** ``` $ docker run --rm -it -v ~/.aws:/root/.aws -v $(pwd):/aws public.ecr.aws/aws-cli/aws-cli s3 cp s3://aws-cli-docker-demo/hello . download: s3://aws-cli-docker-demo/hello to ./hello ``` **Windows Command Prompt** ``` $ docker run --rm -it -v %userprofile%\.aws:/root/.aws -v %cd%:/aws public.ecr.aws/aws-cli/aws-cli s3 cp s3://aws-cli-docker-demo/hello . download: s3://aws-cli-docker-demo/hello to ./hello ``` **Windows PowerShell** ``` C:\> docker run --rm -it -v $env:userprofile\.aws:/root/.aws -v $pwd\aws:/aws public.ecr.aws/aws-cli/aws-cli s3 cp s3://aws-cli-docker-demo/hello . ``` ------ #### [ Docker Hub ] **Linux and macOS** ``` $ docker run --rm -it -v ~/.aws:/root/.aws -v $(pwd):/aws amazon/aws-cli s3 cp s3://aws-cli-docker-demo/hello . download: s3://aws-cli-docker-demo/hello to ./hello ``` **Windows Command Prompt** ``` $ docker run --rm -it -v %userprofile%\.aws:/root/.aws -v %cd%:/aws amazon/aws-cli s3 cp s3://aws-cli-docker-demo/hello . download: s3://aws-cli-docker-demo/hello to ./hello ``` **Windows PowerShell** ``` C:\> docker run --rm -it -v $env:userprofile\.aws:/root/.aws -v $pwd\aws:/aws amazon/aws-cli s3 cp s3://aws-cli-docker-demo/hello . ``` ------ To confirm the downloaded file exists in the local file system, run the following. **Linux and macOS** ``` $ cat hello Hello from Docker! ``` **Windows PowerShell** ``` $ type hello Hello from Docker! ``` ### Example 3: Using your AWS\$1PROFILE environment variable You can call specific system's environment variables using the `-e` flag. Call each environment variable you'd like to use. In this example, we're providing host credentials, configuration, and the *AWS\$1PROFILE* environment variable when running the `s3 ls` command to list your buckets in Amazon Simple Storage Service (Amazon S3). ------ #### [ Amazon ECR Public ] **Linux and macOS** ``` $ docker run --rm -it -v ~/.aws:/root/.aws -e AWS_PROFILE public.ecr.aws/aws-cli/aws-cli s3 ls 2020-03-25 00:30:48 aws-cli-docker-demo ``` **Windows Command Prompt** ``` $ docker run --rm -it -v %userprofile%\.aws:/root/.aws -e AWS_PROFILE public.ecr.aws/aws-cli/aws-cli s3 ls 2020-03-25 00:30:48 aws-cli-docker-demo ``` **Windows PowerShell** ``` C:\> docker run --rm -it -v $env:userprofile\.aws:/root/.aws -e AWS_PROFILE public.ecr.aws/aws-cli/aws-cli s3 ls ``` ------ #### [ Docker Hub ] **Linux and macOS** ``` $ docker run --rm -it -v ~/.aws:/root/.aws -e AWS_PROFILE amazon/aws-cli s3 ls 2020-03-25 00:30:48 aws-cli-docker-demo ``` **Windows Command Prompt** ``` $ docker run --rm -it -v %userprofile%\.aws:/root/.aws -e AWS_PROFILE amazon/aws-cli s3 ls 2020-03-25 00:30:48 aws-cli-docker-demo ``` **Windows PowerShell** ``` C:\> docker run --rm -it -v $env:userprofile\.aws:/root/.aws -e AWS_PROFILE amazon/aws-cli s3 ls ``` ------ ## Shorten the docker run command To shorten the `docker run` command, we suggest you use your operating system's ability to create a [https://www.linux.com/topic/desktop/understanding-linux-links/](https://www.linux.com/topic/desktop/understanding-linux-links/) (symlink) or [https://www.linux.com/topic/desktop/aliases-diy-shell-commands/](https://www.linux.com/topic/desktop/aliases-diy-shell-commands/) in Linux and macOS, or [https://learn.microsoft.com/en-us/windows-server/administration/windows-commands/doskey](https://learn.microsoft.com/en-us/windows-server/administration/windows-commands/doskey) in Windows. To set the `aws` alias, you can run one of the following commands. + For basic access to `aws` commands, run the following. ------ #### [ Amazon ECR Public ] **Linux and macOS** ``` $ alias aws='docker run --rm -it public.ecr.aws/aws-cli/aws-cli' ``` **Windows Command Prompt** ``` C:\> doskey aws=docker run --rm -it public.ecr.aws/aws-cli/aws-cli $* ``` **Windows PowerShell** ``` C:\> Function AWSCLI {docker run --rm -it public.ecr.aws/aws-cli/aws-cli $args} Set-Alias -Name aws -Value AWSCLI ``` ------ #### [ Docker Hub ] **Linux and macOS** ``` $ alias aws='docker run --rm -it amazon/aws-cli' ``` **Windows Command Prompt** ``` C:\> doskey aws=docker run --rm -it amazon/aws-cli $* ``` **Windows PowerShell** ``` C:\> Function AWSCLI {docker run --rm -it amazon/aws-cli $args} Set-Alias -Name aws -Value AWSCLI ``` ------ + For access to the host file system and configuration settings when using `aws` commands, run the following. ------ #### [ Amazon ECR Public ] **Linux and macOS** ``` $ alias aws='docker run --rm -it -v ~/.aws:/root/.aws -v $(pwd):/aws public.ecr.aws/aws-cli/aws-cli' ``` **Windows Command Prompt** ``` C:\> doskey aws=docker run --rm -it -v %userprofile%\.aws:/root/.aws -v %cd%:/aws public.ecr.aws/aws-cli/aws-cli $* ``` **Windows PowerShell** ``` C:\> Function AWSCLI {docker run --rm -it -v $env:userprofile\.aws:/root/.aws -v $pwd\aws:/aws public.ecr.aws/aws-cli/aws-cli $args} Set-Alias -Name aws -Value AWSCLI ``` ------ #### [ Docker Hub ] **Linux and macOS** ``` $ alias aws='docker run --rm -it -v ~/.aws:/root/.aws -v $(pwd):/aws amazon/aws-cli' ``` **Windows Command Prompt** ``` C:\> doskey aws=docker run --rm -it -v %userprofile%\.aws:/root/.aws -v %cd%:/aws amazon/aws-cli $* ``` **Windows PowerShell** ``` C:\> Function AWSCLI {docker run --rm -it -v $env:userprofile\.aws:/root/.aws -v $pwd\aws:/aws amazon/aws-cli $args} Set-Alias -Name aws -Value AWSCLI ``` ------ + To assign a specific version to use in your `aws` alias, append your version tag. ------ #### [ Amazon ECR Public ] **Linux and macOS** ``` $ alias aws='docker run --rm -it -v ~/.aws:/root/.aws -v $(pwd):/aws public.ecr.aws/aws-cli/aws-cli:2.0.6' ``` **Windows Command Prompt** ``` C:\> doskey aws=docker run --rm -it -v %userprofile%\.aws:/root/.aws -v %cd%:/aws public.ecr.aws/aws-cli/aws-cli:2.0.6 $* ``` **Windows PowerShell** ``` C:\> Function AWSCLI {docker run --rm -it -v $env:userprofile\.aws:/root/.aws -v $pwd\aws:/aws public.ecr.aws/aws-cli/aws-cli:2.0.6 $args} Set-Alias -Name aws -Value AWSCLI ``` ------ #### [ Docker Hub ] **Linux and macOS** ``` $ alias aws='docker run --rm -it -v ~/.aws:/root/.aws -v $(pwd):/aws amazon/aws-cli:2.0.6' ``` **Windows Command Prompt** ``` C:\> doskey aws=docker run --rm -it -v %userprofile%\.aws:/root/.aws -v %cd%:/aws amazon/aws-cli:2.0.6 $* ``` **Windows PowerShell** ``` C:\> Function AWSCLI {docker run --rm -it -v $env:userprofile\.aws:/root/.aws -v $pwd\aws:/aws amazon/aws-cli:2.0.6 $args} Set-Alias -Name aws -Value AWSCLI ``` ------ After setting your alias, you can run the AWS CLI version 2 from within a container as if it's installed on your host system. ``` $ aws --version aws-cli/2.27.41 Python/3.7.3 Linux/4.9.184-linuxkit botocore/2.4.5dev10 ``` # Setting up the AWS CLI This topic explains how to quickly configure basic settings that the AWS Command Line Interface (AWS CLI) uses to interact with AWS. These include your security credentials, the default output format, and the default AWS Region. **Topics** + [ ## Gather your credential information for programmatic access ](#getting-started-prereqs-keys) + [ ## Setting up new configuration and credentials ](#getting-started-quickstart-new) + [ ## Using existing configuration and credentials files ](#getting-started-quickstart-existing) ## Gather your credential information for programmatic access You'll need programmatic access if you want to interact with AWS outside of the AWS Management Console. For authentication and credential instructions, choose one of the following options: **** | Authentication type | Purpose | Instructions | | --- | --- | --- | | AWS Management Console credentials | **(Recommended)**Use short-term credentials by logging into the AWS CLI with your console credentials. Recommended if you use root, IAM users, or federation with IAM for AWS account access | [Login for AWS local development using console credentials](cli-configure-sign-in.md) | | IAM Identity Center workforce users short-term credentials | Use short-term credentials for an IAM Identity Center workforce user.Security best practice is to use AWS Organizations with IAM Identity Center. It combines short-term credentials with a user directory, such as the built-in IAM Identity Center directory or Active Directory. | [Configuring IAM Identity Center authentication with the AWS CLI](cli-configure-sso.md) | | IAM user short-term credentials | Use IAM user short-term credentials, which are more secure than long-term credentials. If your credentials are compromised, there is a limited time they can be used before they expire. | [Authenticating with short-term credentials for the AWS CLI](cli-authentication-short-term.md) | | IAM or IAM Identity Center users on an Amazon EC2 instance. | Use Amazon EC2 instance metadata to query for temporary credentials using the role assigned to the Amazon EC2 instance. | [Using Amazon EC2 instance metadata as credentials in the AWS CLI](cli-configure-metadata.md) | | Assume roles for permissions | Pair another credential method and assume a role for temporary access to AWS services your user might not have access to. | [Using an IAM role in the AWS CLI](cli-configure-role.md) | | IAM user long-term credentials | (Not recommended) Use long-term credentials, which have no expiration. | [Authenticating using IAM user credentials for the AWS CLI](cli-authentication-user.md) | | External storage of IAM or IAM Identity Center workforce users | (Not recommended) Pair another credential method but store credential values in a location outside of the AWS CLI. This method is only as secure as the external location the credentials are stored. | [Sourcing credentials with an external process in the AWS CLI](cli-configure-sourcing-external.md) | ## Setting up new configuration and credentials The AWS CLI stores your configuration and credential information in a *profile* (a collection of settings) in the `credentials` and `config` files. **Topics** + [ ### Configuring using AWS CLI commands ](#getting-started-quickstart-new-command) + [ ### Manually editing the credentials and config files ](#getting-started-quickstart-new-file) The following examples use sample values for each of the authentication methods. Replace sample values with your own. ### Configuring using AWS CLI commands For general use, the `aws configure` or `aws configure sso` commands in your preferred terminal are the fastest way to set up your AWS CLI installation. Based on the credential method you prefer, the AWS CLI prompts you for the relevant information. By default, the information in this profile is used when you run an AWS CLI command that doesn't explicitly specify a profile to use. For more information on the `credentials` and `config` files, see [Configuration and credential file settings in the AWS CLI](cli-configure-files.md). ------ #### [ Console sessions as short-term credentials ] This example lets you use your existing console credentials with the `aws login` command. This sign in method can be used with root credentials created during initial account set up, an IAM user, or a federated identity from your identity provider. For more information, see [Login for AWS local development using console credentials](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-sign-in.html). ``` $ aws login No AWS region has been configured. The AWS region is the geographic location of your AWS resources. If you've used AWS before and already have resources in your account, tell us which region they were created in. If you haven't created resources in your account before, you can pick the region closest to you: https://docs.aws.amazon.com/global-infrastructure/latest/regions/aws-regions.html. You are able to change the region in the CLI at any time with the command `aws configure set region NEW_REGION`. AWS Region [us-east-1]: us-east-1 Attempting to open the login page for `us-east-1` in your default browser. If the browser does not open, use the following URL to complete your login: https://us-east-1.signin.aws.amazon.com/v1/authorize If you cannot connect to this URL, make sure that you have specified a valid region. Waiting for login... Logged in with role `arn:aws:sts::012345678910:user/iam-user`, and configured profile `default` to use `us-east-1`. This session will expire on October 14, 2025 at 2:04 PST. After this time, you can renew your session with `aws login`. ``` ------ #### [ IAM Identity Center (SSO) ] This example is for AWS IAM Identity Center using the `aws configure sso` wizard. For more information, see [Configuring IAM Identity Center authentication with the AWS CLI](cli-configure-sso.md). ``` $ aws configure sso SSO session name (Recommended): my-sso SSO start URL [None]: https://my-sso-portal.awsapps.com/start SSO region [None]:us-east-1 Attempting to automatically open the SSO authorization page in your default browser. There are 2 AWS accounts available to you. > DeveloperAccount, developer-account-admin@example.com (111122223333) ProductionAccount, production-account-admin@example.com (444455556666) Using the account ID 111122223333 There are 2 roles available to you. > ReadOnly FullAccess Using the role name "ReadOnly" CLI default client Region [None]: us-west-2 CLI default output format [None]: json CLI profile name [123456789011_ReadOnly]: user1 ``` ------ #### [ IAM Identity Center (Legacy SSO) ] This example is for the legacy method of AWS IAM Identity Center using the `aws configure sso` wizard. To use the legacy SSO, leave the session name blank. For more information, see [Configuring IAM Identity Center authentication with the AWS CLI](cli-configure-sso.md). ``` $ aws configure sso SSO session name (Recommended): SSO start URL [None]: https://my-sso-portal.awsapps.com/start SSO region [None]:us-east-1 SSO authorization page has automatically been opened in your default browser. Follow the instructions in the browser to complete this authorization request. There are 2 AWS accounts available to you. > DeveloperAccount, developer-account-admin@example.com (111122223333) ProductionAccount, production-account-admin@example.com (444455556666) Using the account ID 111122223333 There are 2 roles available to you. > ReadOnly FullAccess Using the role name "ReadOnly" CLI default client Region [None]: us-west-2 CLI default output format [None]: json CLI profile name [123456789011_ReadOnly]: user1 ``` ------ #### [ Short-term credentials ] This example is for the short-term credentials from AWS Identity and Access Management. The aws configure wizard is used to set initial values and then the `aws configure set` command assigns the last value needed. For more information, see [Authenticating with short-term credentials for the AWS CLI](cli-authentication-short-term.md). ``` $ aws configure AWS Access Key ID [None]: AKIAIOSFODNN7EXAMPLE AWS Secret Access Key [None]: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY Default region name [None]: us-west-2 Default output format [None]: json $ aws configure set aws_session_token fcZib3JpZ2luX2IQoJb3JpZ2luX2IQoJb3JpZ2luX2IQoJb3JpZ2luX2IQoJb3JpZVERYLONGSTRINGEXAMPLE ``` ------ #### [ IAM role ] This example is for assuming an IAM role. Profiles that use IAM roles pull credentials from another profile, and then apply IAM role permissions. In the following examples, `default` is the source profile for credentials and `user1` borrows the same credentials then assumes a new role. There is no wizard for this process, therefore each value is set using the `aws configure set` command. For more information, see [Using an IAM role in the AWS CLI](cli-configure-role.md). ``` $ aws configure set role_arn arn:aws:iam::123456789012:role/defaultrole $ aws configure set source_profile default $ aws configure set role_session_name session_user1 $ aws configure set region us-west-2 $ aws configure set output json ``` ------ #### [ Amazon EC2 instance metadata credentials ] This example is for the credentials obtained from the hosting Amazon EC2 instance metadata. There is no wizard for this process, therefore each value is set using the `aws configure set` command. For more information, see [Using Amazon EC2 instance metadata as credentials in the AWS CLI](cli-configure-metadata.md). ``` $ aws configure set role_arn arn:aws:iam::123456789012:role/defaultrole $ aws configure set credential_source Ec2InstanceMetadata $ aws configure set region us-west-2 $ aws configure set output json ``` ------ #### [ Long-term credentials ] **Warning** To avoid security risks, don't use IAM users for authentication when developing purpose-built software or working with real data. Instead, use federation with an identity provider such as [AWS IAM Identity Center](https://docs.aws.amazon.com/singlesignon/latest/userguide/what-is.html). This example is for the long-term credentials from AWS Identity and Access Management. For more information, see [Authenticating using IAM user credentials for the AWS CLI](cli-authentication-user.md). ``` $ aws configure AWS Access Key ID [None]: AKIAIOSFODNN7EXAMPLE AWS Secret Access Key [None]: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY Default region name [None]: us-west-2 Default output format [None]: json ``` ------ For more detailed information on authentication and credential methods see [Authentication and access credentials for the AWS CLI](cli-chap-authentication.md). ### Manually editing the credentials and config files When copy and pasting information, we suggest manually editing the `config` and `credentials` file. Based on the credential method you prefer, the files are setup in a different way. The files are stored in your home directory under the `.aws` folder. Where you find your home directory location varies based on the operating system, but is referred to using the environment variables `%UserProfile%` in Windows and `$HOME` or `~` (tilde) in Unix-based systems. For more information on where these settings are stored, see [Where are configuration settings stored?](cli-configure-files.md#cli-configure-files-where). The following examples show a `default` profile and a profile named `user1` and use sample values. Replace sample values with your own. For more information on the `credentials` and `config` files, see [Configuration and credential file settings in the AWS CLI](cli-configure-files.md). ------ #### [ IAM Identity Center (SSO) ] This example is for AWS IAM Identity Center. For more information, see [Configuring IAM Identity Center authentication with the AWS CLI](cli-configure-sso.md). **Credentials file** The `credentials` file is not used for this authentication method. **Config file** ``` [default] sso_session = my-sso sso_account_id = 111122223333 sso_role_name = readOnly region = us-west-2 output = text [profile user1] sso_session = my-sso sso_account_id = 444455556666 sso_role_name = readOnly region = us-east-1 output = json [sso-session my-sso] sso_region = us-east-1 sso_start_url = https://my-sso-portal.awsapps.com/start sso_registration_scopes = sso:account:access ``` ------ #### [ IAM Identity Center (Legacy SSO) ] This example is for the legacy method of AWS IAM Identity Center. For more information, see [Configuring IAM Identity Center authentication with the AWS CLI](cli-configure-sso.md). **Credentials file** The `credentials` file is not used for this authentication method. **Config file** ``` [default] sso_start_url = https://my-sso-portal.awsapps.com/start sso_region = us-east-1 sso_account_id = 111122223333 sso_role_name = readOnly region = us-west-2 output = text [profile user1] sso_start_url = https://my-sso-portal.awsapps.com/start sso_region = us-east-1 sso_account_id = 444455556666 sso_role_name = readOnly region = us-east-1 output = json ``` ------ #### [ Short-term credentials ] This example is for the short-term credentials from AWS Identity and Access Management. For more information, see [Authenticating with short-term credentials for the AWS CLI](cli-authentication-short-term.md). **Credentials file** ``` [default] aws_access_key_id=ASIAIOSFODNN7EXAMPLE aws_secret_access_key=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY aws_session_token = IQoJb3JpZ2luX2IQoJb3JpZ2luX2IQoJb3JpZ2luX2IQoJb3JpZ2luX2IQoJb3JpZVERYLONGSTRINGEXAMPLE [user1] aws_access_key_id=ASIAI44QH8DHBEXAMPLE aws_secret_access_key=je7MtGbClwBF/2Zp9Utk/h3yCo8nvbEXAMPLEKEY aws_session_token = fcZib3JpZ2luX2IQoJb3JpZ2luX2IQoJb3JpZ2luX2IQoJb3JpZ2luX2IQoJb3JpZVERYLONGSTRINGEXAMPLE ``` **Config file** ``` [default] region=us-west-2 output=json [profile user1] region=us-east-1 output=text ``` ------ #### [ IAM role ] This example is for assuming an IAM role. Profiles that use IAM roles pull credentials from another profile, and then apply IAM role permissions. In the following examples, `default` is the source profile for credentials and `user1` borrows the same credentials then assumes a new role. For more information, see [Using an IAM role in the AWS CLI](cli-configure-role.md). **Credentials file** The `credentials` file depends on what authentication your source profile uses. For the following example, the source profile uses short-term credentials. ``` [default] aws_access_key_id=ASIAIOSFODNN7EXAMPLE aws_secret_access_key=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY aws_session_token = IQoJb3JpZ2luX2IQoJb3JpZ2luX2IQoJb3JpZ2luX2IQoJb3JpZ2luX2IQoJb3JpZVERYLONGSTRINGEXAMPLE ``` **Config file** ``` [default] region=us-west-2 output=json [profile user1] role_arn=arn:aws:iam::777788889999:role/user1role source_profile=default role_session_name=session_user1 region=us-east-1 output=text ``` ------ #### [ Amazon EC2 instance metadata credentials ] This example is for the credentials obtained from the hosting Amazon EC2 instance metadata. For more information, see [Using Amazon EC2 instance metadata as credentials in the AWS CLI](cli-configure-metadata.md). **Credentials file** The `credentials` file is not used for this authentication method. **Config file** ``` [default] role_arn=arn:aws:iam::123456789012:role/defaultrole credential_source=Ec2InstanceMetadata region=us-west-2 output=json [profile user1] role_arn=arn:aws:iam::777788889999:role/user1role credential_source=Ec2InstanceMetadata region=us-east-1 output=text ``` ------ #### [ Long-term credentials ] **Warning** To avoid security risks, don't use IAM users for authentication when developing purpose-built software or working with real data. Instead, use federation with an identity provider such as [AWS IAM Identity Center](https://docs.aws.amazon.com/singlesignon/latest/userguide/what-is.html). This example is for the long-term credentials from AWS Identity and Access Management. For more information, see [Authenticating using IAM user credentials for the AWS CLI](cli-authentication-user.md). **Credentials file** ``` [default] aws_access_key_id=AKIAIOSFODNN7EXAMPLE aws_secret_access_key=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY [user1] aws_access_key_id=AKIAI44QH8DHBEXAMPLE aws_secret_access_key=je7MtGbClwBF/2Zp9Utk/h3yCo8nvbEXAMPLEKEY ``` **Config file** ``` [default] region=us-west-2 output=json [profile user1] region=us-east-1 output=text ``` ------ For more detailed information on authentication and credential methods see [Authentication and access credentials for the AWS CLI](cli-chap-authentication.md). ## Using existing configuration and credentials files If you have existing configuration and credentials files, these can be used for the AWS CLI. To use the `config` and `credentials` files, move them to the folder named `.aws` in your home directory. Where you find your home directory location varies based on the operating system, but is referred to using the environment variables `%UserProfile%` in Windows and `$HOME` or `~` (tilde) in Unix-based systems. You can specify a non-default location for the `config` and `credentials` files by setting the `AWS_CONFIG_FILE` and `AWS_SHARED_CREDENTIALS_FILE` environment variables to another local path. See [Configuring environment variables for the AWS CLI](cli-configure-envvars.md) for details. For more detailed information on configuration and credentials files, see [Configuration and credential file settings in the AWS CLI](cli-configure-files.md).