Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Using Amazon CLI v1-to-v2 Migration Tool to upgrade Amazon CLI version 1 to Amazon CLI version 2

This topic describes the Amazon CLI v1-to-v2 Migration Tool.

We recommend that users of Amazon CLI version 1 upgrade to Amazon CLI version 2 to access new features and enhanced performance. There are changes in behavior between Amazon CLI version 1 and Amazon CLI version 2 that might require you to update your scripts or commands to get the same behavior. The Amazon CLI v1-to-v2 Migration Tool analyzes bash scripts containing Amazon CLI version 1 commands and detects usage of features that have been updated with breaking changes in Amazon CLI version 2. Additionally, the tool can automatically modify your scripts to fix most issues that it detects. This tool improves the upgrade experience by automatically detecting and modifying Amazon CLI version 1 commands in bash scripts to prevent unexpected issues when upgrading to version 2.

Compared to Upgrade Debug Mode, the Amazon CLI v1-to-v2 Migration Tool is a standalone tool and does not require executing Amazon CLI commands. For a thorough comparison between the Upgrade Debug Mode and the Amazon CLI v1-to-v2 Migration Tool see Using Amazon CLI Migration Tools to Mitigate Breakage in Migration guide for the Amazon CLI version 2.

For more details, see Breaking changes between Amazon CLI version 1 and Amazon CLI version 2 in New features and changes in the Amazon CLI version 2.

How it Works

The Amazon CLI v1-to-v2 Migration Tool is a Python package capable of linting bash scripts that use Amazon CLI version 1. Being a static linter, it does not depend on the version of Amazon CLI version 1 that you may have installed on your machine. The linter is invoked through the command line, where the local file path to the bash script is supplied as a parameter.

The migration tool can also automatically produce a modified bash script that resolves most findings that it detects by modifying the Amazon CLI version 1 commands used in the script. The migration tool modifies commands so that they are compatible with Amazon version 2 and retains the behavior of version 1.

For some findings, the Amazon CLI v1-to-v2 Migration Tool can detect them but not offer an automatic fix. In these cases, the migration tool flags them as detections that require manual review.

See Limitations for an exhaustive list of breaking changes and automatic fixes that the Amazon CLI v1-to-v2 Migration Tool supports.

Prerequisites

Python

To use this tool, you must have Python 3.9 or later installed.

To verify that you have a correct Python version installed, run the following command in a terminal and confirm the output shows a Python version of at least 3.9.

$ python3 --version

If you have an older version of Python, or do not have Python installed, you can download a compatible version from the official Python download page.

pip

In addition to having a compatible version of Python installed, you must have pip installed.

To verify that pip is installed, run the following command:

$ python3 -m pip --version

If you have pip installed, you will see an output similar to the following:

pip 25.0.1 from ~/.local/lib/python3.13/site-packages (python 3.13)

If you do not have pip installed, see Install pip.

Installation

Install the Amazon CLI v1-to-v2 Migration Tool in a new virtual environment:

$ python3 -m venv .venv
$ source .venv/bin/activate
$ python3 -m pip install aws-cli-migrate

Usage

Dry-run Mode (default)

With dry-run mode, you can automatically detect Amazon CLI version 1 commands that are subject to breaking changes without modifying the input script:

$ migrate-aws-cli --script upload_s3_files.sh

Auto-fix Mode

With auto-fix mode, you can automatically detect and update Amazon CLI version 1 commands in the input script to mitigate breakage from changes introduced in Amazon CLI version 2, where possible:

$ migrate-aws-cli --script upload_s3_files.sh --fix

Optionally, you can supply an output path via the --output parameter to write the updated script, rather than updating the input script:

$ migrate-aws-cli --script upload_s3_files.sh --output upload_s3_files_v2.sh --fix

Interactive Mode

With interactive mode, you can automatically detect Amazon CLI version 1 commands that are subject to breaking changes. Most findings will show a suggested fix to mitigate breakage in Amazon CLI version 2. You can review the suggested fixes and decide whether to apply them. Optionally, supply an output path via the --output parameter to control where to write the updated script:

$ migrate-aws-cli --script upload_s3_files.sh --interactive \
--output upload_s3_files_v2.sh

The following output snippet is an example finding in interactive mode:

14 14│ 
15 15│ aws s3 ls s3://mybucket
16 16│ 
17   │-aws s3 cp s3://amzn-demo-bucket s3://amzn-demo-bucket2 --recursive
   17│+aws s3 cp s3://amzn-demo-bucket s3://amzn-demo-bucket2 --recursive --copy-props none
18 18│ 
19 19│ TEMPLATE_KEY="cloudformation/$(basename "$TEMPLATE_FILE")"
20 20│ 

examples/upload_s3_files.sh:17 [s3-copy] In AWS CLI v2, object properties will be copied 
from the source in multipart copies between S3 buckets. If a copy is or becomes multipart 
after upgrading to AWS CLI v2, extra API calls will be made. See 
https://docs.aws.amazon.com/cli/latest/userguide/cliv2-migration-changes.html#cliv2-migration-s3-copy-metadata.

Apply this fix? [y] yes, [n] no, [a] accept all of type, [r] reject all of type, [u] update all, 
[s] save and exit, [q] quit: 

The suggested fix is shown in a format similar to a Git diff. The migration tool suggests the removal of lines starting with a -, and suggests adding lines starting with a +. In the previous example, the suggestion can be interpreted as adding the --copy-props none parameter to the Amazon CLI version 1 command that executes an Amazon S3 copy.

For each suggested fix, you can enter any of the following controls:

Some findings may be flagged for manual review without a suggested fix. You should review these findings and verify whether you are impacted by the referenced breaking changes. If you are impacted by these findings, you should follow the guidance specified in the finding description to make the necessary changes to avoid or prepare for the breaking changes introduced in Amazon CLI version 2.

Limitations

The Amazon CLI v1-to-v2 Migration Tool does not currently support every breaking change introduced with Amazon CLI version 2, and has false positive cases where it outputs detections for commands even if no breaking changes would actually be faced.

We strongly recommend customers understand Breaking changes between Amazon CLI version 1 and Amazon CLI version 2 published in New features and changes in the Amazon CLI version 2.

Text-based Analysis

The migration tool analyzes your script without running it. This limits how it detects Amazon CLI commands for breaking changes. The migration tool can only examine the text of an Amazon CLI command. It cannot detect issues that arise at runtime, such as storing deprecated parameters in a variable instead of passing them directly to the Amazon CLI.

Unsupported Breaking Change Detection

The extent of support for breaking changes in the migration tool is summarized in the following table.