Why shouldn't I install AWS CLI v2 with pip?

The awscli package on PyPI is the legacy v1 branch. AWS only distributes v2 through their own download URL and select distro repositories. Installing via pip will give you an outdated v1 release missing SSO support and other v2 features.

How do I update AWS CLI v2 after installing it from the zip?

Re-download the zip and rerun the installer with the --update flag: sudo ./aws/install --update. On Arch, sudo pacman -Syu aws-cli-v2 handles updates normally.

Can I use AWS CLI v2 with instance roles on EC2 or ECS without any credentials file?

Yes. The CLI automatically queries the instance metadata service (IMDS) for temporary credentials when no other credentials are present. No ~/.aws/credentials file is needed on EC2, ECS, Lambda, or any service with an attached IAM role.

How do I stop the CLI from prompting my MFA code on every single command?

It should not prompt every time — temporary STS credentials are cached in ~/.aws/cli/cache/ for the role's session duration (default 1 hour). If it prompts repeatedly, check that the cache directory is writable and that your system clock is accurate, as clock skew invalidates cached tokens.

Is it safe to store credentials in ~/.aws/credentials on a shared machine?

The file is created with 0600 permissions (readable only by your user), but any process running as your user or as root can read it. On shared or high-risk systems, prefer short-lived credentials via IAM roles, SSO, or aws-vault rather than long-lived access keys in a flat file.

Install and Configure the AWS CLI

The AWS Command Line Interface (CLI) v2 is the standard way to manage AWS resources from a terminal. It handles authentication, multiple accounts via named profiles, SSO login flows, MFA prompts, and per-profile region defaults — all without opening a browser more than once. This guide covers a clean installation, credential setup, and the quality-of-life extras that make day-to-day AWS work faster.

Install AWS CLI v2

AWS CLI v2 ships as a self-contained binary and should not be installed via pip. The awscli package on PyPI is the legacy v1 branch; v2 is only distributed through AWS's own downloads or distro packages. Use the official installer to avoid version confusion.

Debian / Ubuntu

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

On ARM64 (Graviton, Raspberry Pi 5, Apple Silicon under a Linux VM) replace x86_64 with aarch64 in the URL.

Fedora / RHEL 9 / Rocky Linux

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

The installer is identical across distros; the commands above work on any systemd-based Linux. RHEL/Rocky users may need unzip: sudo dnf install -y unzip.

Arch Linux

sudo pacman -S aws-cli-v2

The Arch community package tracks upstream releases closely. Prefer it over the manual installer on Arch.

Verify the installation

aws --version

You should see output like aws-cli/2.x.x Python/3.x.x Linux/.... If you see aws-cli/1., an old pip-installed copy is winning the PATH race — remove it with pip uninstall awscli or adjust your PATH.

Configure Your First Profile

Run the interactive wizard for the default profile. You will need an IAM access key ID and secret (generate these under IAM → Users → Security credentials in the console).

aws configure

The wizard asks for four values:

AWS Access Key ID — the 20-character AKIA… string
AWS Secret Access Key — the 40-character secret
Default region name — e.g. us-east-1, eu-west-2
Default output format — json, yaml, table, or text; json is safest for scripting

Credentials are stored in ~/.aws/credentials; region and output go into ~/.aws/config. Both are plain INI files you can edit directly.

Named profiles for multiple accounts

Use --profile to create additional profiles without overwriting the default:

aws configure --profile production
aws configure --profile staging

Select a profile at runtime with --profile or by exporting the environment variable:

export AWS_PROFILE=production
aws s3 ls

Set Up AWS SSO (IAM Identity Center)

If your organisation uses AWS IAM Identity Center (formerly SSO), long-lived access keys are unnecessary. The SSO flow issues short-lived tokens automatically.

Register an SSO profile

aws configure sso

The wizard prompts for your SSO start URL (e.g. https://mycompany.awsapps.com/start), SSO region, and which account/role to associate with the profile. It opens your browser once to complete the OIDC device-auth flow, then writes the profile to ~/.aws/config. The resulting stanza looks like:

cat ~/.aws/config

A correctly configured SSO profile section will contain sso_start_url, sso_account_id, sso_role_name, and sso_region keys.

Log in and refresh tokens

aws sso login --profile my-sso-profile

Tokens are cached in ~/.aws/sso/cache/ and expire after the duration set in your Identity Center permission set (typically 8 hours). Add a shell alias like alias aws-login='aws sso login --profile my-sso-profile' to make re-authentication quick.

MFA with IAM Roles

When an IAM role requires MFA, add a mfa_serial and role_arn to your config profile. The CLI will prompt for the one-time token automatically.

# Add to ~/.aws/config manually or with a text editor
[profile mfa-role]
source_profile = default
role_arn = arn:aws:iam::123456789012:role/MyRole
mfa_serial = arn:aws:iam::111122223333:mfa/your-iam-username
region = us-east-1

The first command that calls AWS with this profile will prompt: Enter MFA code for arn:aws:iam::...:. The resulting temporary credentials are cached in ~/.aws/cli/cache/ for the session duration defined on the role (default 1 hour, max 12 hours).

Region and Output Defaults

You can override region and output at three levels, in ascending priority:

The ~/.aws/config profile default (set by aws configure)
Environment variables: AWS_DEFAULT_REGION, AWS_DEFAULT_OUTPUT
Per-command flags: --region eu-central-1 --output table

For shell sessions where you always work in one region:

export AWS_DEFAULT_REGION=ap-southeast-1

Add that to ~/.bashrc or ~/.zshrc to make it permanent for your user.

Shell Completions

Bash

echo 'complete -C "$(which aws_completer)" aws' >> ~/.bashrc
source ~/.bashrc

Zsh

echo 'autoload bashcompinit && bashcompinit' >> ~/.zshrc
echo 'complete -C "$(which aws_completer)" aws' >> ~/.zshrc
source ~/.zshrc

After sourcing, pressing Tab after aws s3 or any other subcommand will autocomplete service names, subcommands, and option flags. The aws_completer binary is included in the v2 installation at /usr/local/bin/aws_completer.

Verify Everything Works

aws sts get-caller-identity

A successful response returns your account ID, user/role ARN, and the resolved user ID. If this works, credentials are valid and the CLI can reach AWS endpoints.

aws sts get-caller-identity --profile production

Run the same check against each named profile to confirm they are all wired up correctly.

Troubleshooting

"Unable to locate credentials"

Either ~/.aws/credentials is missing the expected profile, or AWS_PROFILE points to a profile that does not exist. Run aws configure list-profiles to see what the CLI knows about.

"An error occurred (ExpiredTokenException)"

Temporary credentials from STS or SSO have expired. For SSO profiles run aws sso login --profile <name>. For MFA-backed role profiles, the cached token in ~/.aws/cli/cache/ has expired; your next API call will re-prompt for an MFA code automatically.

SSL or proxy errors

Set AWS_CA_BUNDLE to your custom CA cert path, or configure https_proxy / no_proxy environment variables. Corporate networks often intercept TLS; check with your network team for the correct CA bundle.

Wrong version still active after install

which aws
aws --version

If which aws returns a path under a Python virtualenv or ~/.local/bin, a pip-installed v1 is shadowing the system install. Remove it (pip uninstall awscli) or put /usr/local/bin earlier in your PATH.