# 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](cliv2-migration.md#using-migration-tools) in [Migration guide for the Amazon CLI version 2](cliv2-migration.md).
For more details, see [Breaking changes between Amazon CLI version 1 and Amazon CLI version 2](cliv2-migration-changes.md#cliv2-migration-changes-breaking) in [New features and changes in the Amazon CLI version 2](cliv2-migration-changes.md).
## 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](#migration-tool-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](https://www.python.org/downloads/).
### 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](https://docs.amazonaws.cn/cli/v1/userguide/install-linux.html#install-linux-pip-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:
+ Enter `y` to accept the suggested fix.
+ Enter `n` to reject the current fix.
+ Enter `a` to accept all fixes with the same type.
+ Enter `r` to reject all fixes with the same type.
+ Enter `u` to accept all remaining fixes.
+ Enter `s` to save and exit.
+ Enter `q` to quit without saving.
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](cliv2-migration-changes.md#cliv2-migration-changes-breaking) published in [New features and changes in the Amazon CLI version 2](cliv2-migration-changes.md).
### 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.
| Breaking change | Detection supported | Auto-fix supported |
| --- | --- | --- |
| [Environment variable added to set text file encoding](cliv2-migration-changes.md#cliv2-migration-encodingenvvar) | No | No |
| [Binary parameters are passed as base64-encoded strings by default](cliv2-migration-changes.md#cliv2-migration-binaryparam) | Yes | Yes |
| [Improved Amazon S3 handling of file properties and tags for multipart copies](cliv2-migration-changes.md#cliv2-migration-s3-copy-metadata) | Yes | Yes |
| [No automatic retrieval of `http://` or `https://` URLs for parameters](cliv2-migration-changes.md#cliv2-migration-paramfile) | No | No |
| [Pager used for all output by default](cliv2-migration-changes.md#cliv2-migration-output-pager) | Yes | Yes |
| [Timestamp output values are standardized to ISO 8601 format](cliv2-migration-changes.md#cliv2-migration-timestamp) | No | No |
| [Improved handling of CloudFormation deployments that result in no changes](cliv2-migration-changes.md#cliv2-migration-cfn) | Yes | Yes |
| [Changed default behavior for Regional Amazon S3 endpoint for `us-east-1` Region](cliv2-migration-changes.md#cliv2-migration-s3-regional-endpoint) | No | No |
| [Changed default behavior for Regional Amazon STS endpoints](cliv2-migration-changes.md#cliv2-migration-sts-regional-endpoint) | No | No |
| [`ecr get-login` removed and replaced with `ecr get-login-password`](cliv2-migration-changes.md#cliv2-migration-ecr-get-login) | Yes | No |
| [Amazon CLI version 2 support for plugins is changing](cliv2-migration-changes.md#cliv2-migration-profile-plugins) | No | No |
| [Hidden alias support removed](cliv2-migration-changes.md#cliv2-migration-aliases) | Yes | Yes |
| [The `api_versions` configuration file setting is not supported](cliv2-migration-changes.md#cliv2-migration-api-versions) | No | No |
| [Amazon CLI version 2 uses only Signature v4 to authenticate Amazon S3 requests](cliv2-migration-changes.md#cliv2-migration-sigv4) | No | No |
| [Amazon CLI version 2 is more consistent with paging parameters](cliv2-migration-changes.md#cliv2-migration-skeleton-paging) | Yes | No |
| [Amazon CLI version 2 provides more consistent return codes across all commands](cliv2-migration-changes.md#cliv2-migration-return-codes) | No | No |