aws/aws-cli: the Python source behind the AWS command line, and where its packaging trips people up

The develop branch builds a pip package while v2 ships as native installers

The repository's default branch is develop, and its setup.py builds a package named awscli with the description Universal Command Line Environment for AWS. It installs five scripts from bin/: aws, aws.cmd, aws_completer, aws_zsh_completer.sh and aws_bash_completer. That is the code path for anyone working from source.

Most users never touch it. AWS CLI v2 is distributed as a macOS pkg installer (AWSCLIV2.pkg), a Windows MSI (AWSCLIV2.msi), and Linux executable installers for x86-64 and arm64 (aarch64) as zip files on awscli.amazonaws.com. If you want the v2 development branch rather than an installer, the README points to a separate CLI Dev Version section. Choosing the installer gets you a self-contained aws command; choosing pip from this branch makes the CLI one more Python package competing with everything else in that environment.

Python 3.9 in the README, 3.10 in setup.py

The README lists supported Python versions as 3.9.x through 3.14.x. The setup.py on the same branch says python_requires=">= 3.10", and the ruff configuration in pyproject.toml sets target-version = "py310". Those do not agree.

The practical consequence: on a Python 3.9 interpreter, pip will refuse to install the package from this source, regardless of what the README table says. Trust setup.py here, because that is what pip enforces. Teams still pinned to 3.9 on build agents should use the v2 installers instead of a pip install from source.

Dependency ceilings that collide in a shared environment

The install_requires list in setup.py caps several common libraries: docutils>=0.18.1,<=0.19, PyYAML>=3.10,<6.1, colorama>=0.2.5,<0.4.7, rsa>=3.1.2,<4.8, jmespath>=0.7.1,<2.0.0, python-dateutil>=2.1,<3.0.0, and urllib3>=1.25.4,!=2.2.0,<3. The optional crt extra pins awscrt==0.36.0 exactly.

Upper bounds like docutils <=0.19 and rsa <4.8 are where trouble starts. If another tool in the same virtual environment needs a newer docutils or rsa, pip cannot satisfy both, and one of them will be downgraded or the install will fail. Install this package in its own environment, or use the v2 installers, rather than adding it to an application's dependency set.

Credentials resolve from four places, and the config file wants a profile prefix

aws-cli reads credentials from environment variables, the shared credentials file, the config file, or an IAM Role. The fastest start is aws configure, which prompts for the access key ID, secret key, default region and default output format. Environment variables work too:

$ export AWS_ACCESS_KEY_ID=<access_key>
$ export AWS_SECRET_ACCESS_KEY=<secret_key>

The shared credentials file lives at ~/.aws/credentials and the config file at ~/.aws/config, with %UserProfile% equivalents on Windows. AWS_SHARED_CREDENTIALS_FILE and AWS_CONFIG_FILE move them elsewhere. The trap is a formatting asymmetry: in the credentials file a profile section is [testing], but in the config file every profile except default must be written [profile testing]. Copy a section between the two files without changing the header and the CLI will not find that profile. Select profiles with --profile or AWS_PROFILE; without either, default is used. On EC2, an IAM Role is picked up automatically.

Tab completion is not installed for you

Command completion ships with the package but is not set up automatically. For bash, the built-in complete command registers it:

$ complete -C aws_completer aws

Alternatively, drop bin/aws_bash_completer into /etc/bash_completion.d, /usr/local/etc/bash_completion.d or another bash_completion.d directory. zsh needs bashcompinit and compinit loaded first:

$ autoload bashcompinit && bashcompinit
$ autoload -Uz compinit && compinit
$ complete -C '/usr/local/bin/aws_completer' aws

The path /usr/local/bin/aws_completer is an assumption; replace it with the output of which aws_completer if yours differs, which it will when the CLI lives in a virtual environment. None of this persists until you add it to ~/.zshrc or your shell startup files, so a new terminal without that step has no completion.

Releases are tracked in CHANGELOG.rst, not on GitHub Releases

The only entry on the repository's GitHub releases page is 2.0.0dev0, an AWS CLI 2.0.0dev preview published on 2018-11-26. Release notes instead live in CHANGELOG.rst on the v2 branch, and the repository also carries a .changes/ directory alongside CHANGELOG.rst at the top level. Anyone watching GitHub releases for update notifications will see nothing new; watch the changelog instead. The develop branch received its last push on 2026-11-02, so the code itself is moving even though the releases page is frozen.

macOS 10.15 lost support on 2024-11-13

Support for macOS 10.15 was dropped on 2024-11-13. Users on macOS 10.15 or earlier who want up-to-date AWS CLI v2 builds need to move to macOS 11 or later. A machine that cannot upgrade is stuck on whatever older CLI version it already has, which matters because the README also asks every user to monitor the Amazon Web Services Security Bulletins website for aws-cli issues. Fixes announced there will not reach an unsupported OS.

Editorial conclusion

Install AWS CLI v2 from the macOS pkg, Windows MSI or Linux zip installers if you just need the aws command; that path avoids the Python packaging questions entirely. Clone aws/aws-cli and build from setup.py only if you need to read or patch the source, and then use a dedicated virtual environment on Python 3.10 or later. Before relying on either, check the CHANGELOG.rst on the v2 branch and confirm your OS is still supported, since macOS 10.15 was dropped on 2024-11-13.

Frequently asked questions

Official sources

1. aws/aws-cli on GitHub
2. Issues
3. README
4. Releases