Pip Install AWS CLI: Why You Get v1 and How to Install v2

The first version of this guide, written in 2018, installed the AWS CLI with pip on Ubuntu 16.04. That was the normal way to do it then. It is the wrong way now, and plenty of people still search for exactly that command, so this rewrite starts with why.

Install AWS CLI using pip: what you actually get

pip install awscli installs AWS CLI version 1. Always. The awscli package on PyPI is v1, and AWS ships version 2 only through its own installers, never through PyPI. That is why "install aws cli python" and "aws cli pip" searches land people on a version that is on its way out.

That used to be a style preference. It is not any more:

Pip install AWS CLI 2: there is no official package

You will also find a package called awscliv2 on PyPI. It is a third-party wrapper that downloads and runs the real v2 binary, not something AWS publishes. It works, but I would not put it on a production host when the official installer is a single command. The details of the v1 timeline are in the AWS CLI v1 maintenance mode announcement.

If pip already put v1 on the machine, remove it first so the two binaries don't fight over the aws command:

pip uninstall -y awscli
sudo apt remove -y awscli   # only if it came from apt
which -a aws                # should print nothing now

Install AWS CLI v2 on Ubuntu and Linux

AWS now ships an install script that downloads, verifies and installs the CLI in one step, for both x86 and ARM. Installing for all users on a server:

curl -fsSL https://awscli.amazonaws.com/v2/install.sh | sudo bash -s -- --system
aws --version

Without --system it installs for your user only, under ~/.local/share/aws-cli with the binary linked into ~/.local/bin. That is the better choice on a shared workstation.

If you want to pin a specific version, which matters in CI images, use the zip installer instead. It needs unzip, which a minimal Ubuntu 24.04 or 26.04 image does not have:

sudo apt install -y unzip curl
curl "https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip" -o awscliv2.zip
unzip awscliv2.zip
sudo ./aws/install
aws --version

On ARM machines such as Graviton instances or a Raspberry Pi running 64-bit Ubuntu, swap the file name for awscli-exe-linux-aarch64.zip. And if you would rather never think about updates, sudo snap install aws-cli --classic is an AWS-supported option that refreshes itself, at the cost of not being able to pin a minor version. The full list of methods is in the official AWS CLI install guide.

Install AWS CLI on Alpine Linux and containers

This catches a lot of Dockerfiles. The official AWS installer is built against glibc, and Alpine uses musl, so the zip installer fails on alpine base images with confusing "not found" errors even though the file is right there.

Use the Alpine aws-cli package, which is v2:

apk add --no-cache aws-cli
aws --version

It tracks AWS releases with some delay. At the time of writing the stable Alpine branch carried a 2.27 release while AWS was well into 2.3x. For most scripts that gap does not matter; if you need a very new service, use a Debian-based image with the official installer instead.

macOS and Windows

On macOS the same install script works, or you can download the AWSCLIV2.pkg installer:

curl -fsSL https://awscli.amazonaws.com/v2/install.sh | bash

On Windows, from PowerShell:

irm https://awscli.amazonaws.com/v2/install.ps1 | iex
aws --version

Or use the AWSCLIV2.msi installer if your organisation deploys software through MSI packages.

Configure credentials

The old way was to create an IAM user, copy its access key and secret, and run aws configure. That still works:

aws configure
# AWS Access Key ID: ...
# AWS Secret Access Key: ...
# Default region name: eu-central-1
# Default output format: json

For people, prefer short-lived credentials. If your organisation uses IAM Identity Center, sign in through the browser and let the CLI refresh tokens for you:

aws configure sso
aws sso login --profile my-profile

Long-lived access keys belong on the few machines that genuinely need them, and on EC2 you should not need them at all, because an instance role gives the CLI credentials automatically. Whatever you pick, confirm who the CLI thinks you are before running anything destructive:

aws sts get-caller-identity

Moving scripts off v1

Most scripts run unchanged on v2. The differences that break things are small and specific (AWS keeps the full list in its v1 to v2 migration guide):

• Binary parameters. v2 treats blob arguments as base64 by default. Scripts that pass raw file contents to commands such as aws lambda invoke --payload need --cli-binary-format raw-in-base64-out.
• The pager. v2 pipes long output through less, which hangs non-interactive jobs. Set AWS_PAGER="" in CI.
• Python-dependent tooling. Anything that imported awscli as a Python module stops working, because v2 is not a Python package. Use boto3 for that instead.

With the CLI working, the common next steps are moving data and machines around. Uploading large files to S3 covers multipart uploads and the settings that speed them up, AWS VM Import/Export covers turning a local virtual machine into an AMI, and raising your EC2 vCPU quota is worth doing before you launch anything large. If you run workflows on Lambda, Step Functions with Lambda is driven by the same CLI.

Related Articles

How to increase AWS vCPU quota - Developer Guide

Welcome to our comprehensive guide on maximizing your AWS experience by increasing quota limits. If you've ever felt the frustration of hitting service limits in your AWS account, you're alone. But why do these limits exist in the first place? They serve a crucial purpose: preventing inadvertent resource over-provisioning and safeguarding services from potential abuse by limiting API request rates.

By Hiruna Kumara • Meetrix.io

AWS Step Functions with Lambda: Scheduling and Passing Data

How to wire AWS Step Functions to Lambda: invoking functions, reading the Lambda return value, passing data between Lambdas, and scheduling work that fires hours later.

By Hiruna Kumara • Meetrix.io

Self-Hosting Open-Source Software on AWS Marketplace: A Practical Guide

Self hosted software on AWS explained: what it costs versus SaaS, which open source tools replace Zoom, Drive, Firebase and Auth0, and how to deploy them.

By Binuka Ranatunga • Meetrix.io