Complete Guide to Resolving "-bash: aws: command not found" Error on macOS

Problem Background and Error Analysis

On macOS Mojave (version 10.14.5) systems, users following the official AWS documentation to install AWS CLI encounter the -bash: aws: command not found error when executing aws --version in the terminal. This error indicates that the system cannot locate the aws executable in the PATH environment variable, typically caused by:

• Incorrect AWS CLI installation
• Missing Python or pip dependencies
• Improper PATH environment variable configuration
• Permission issues during installation

Core Solution: Python and pip Dependency Management

Based on the best answer analysis, the key to resolving this issue lies in ensuring the system has proper Python and pip environments. AWS CLI is a Python-based tool, and its installation depends on the pip package manager. Below are detailed resolution steps:

Step 1: Check Python Environment

First, verify if Python 3.x is installed on the system. Execute the following command in the terminal:

python3 --version

If version information is returned (e.g., Python 3.7.3), the Python environment is functional. If Python is not installed, install it via Homebrew or the official installer:

brew install python

Step 2: Verify pip Installation Status

pip is Python's package manager, and AWS CLI is installed via pip. Check if pip is available:

pip3 --version

If pip is not installed, install it using:

sudo easy_install pip

Or use Python's built-in ensurepip module:

python3 -m ensurepip --upgrade

Step 3: Install AWS CLI

After confirming the Python and pip environments, install AWS CLI using:

sudo pip3 install awscli --force-reinstall --upgrade

This command includes three critical parameters:

• --force-reinstall: Forces reinstallation to resolve potential installation corruption
• --upgrade: Upgrades to the latest version
• sudo: Uses administrator privileges to ensure sufficient system permissions

In-Depth Technical Analysis

PATH Environment Variable Mechanism

When a user types the aws command in the terminal, the system searches for the corresponding executable in directories specified by the PATH environment variable. AWS CLI is typically installed to /usr/local/bin/aws or ~/.local/bin/aws. Check PATH configuration with:

echo $PATH

If the AWS CLI installation directory is not in PATH, add it manually. Edit ~/.bash_profile or ~/.zshrc (depending on the shell used) and add:

export PATH="$PATH:/usr/local/bin"

Then reload the configuration file:

source ~/.bash_profile

Python Virtual Environment Considerations

If using Python virtual environments (virtualenv or conda), ensure AWS CLI is installed in the correct environment. First activate the virtual environment, then execute the installation command:

source venv/bin/activate
pip install awscli

Troubleshooting and Verification

Verify Successful Installation

After installation, verify AWS CLI functionality with:

aws --version

Correct output should display information like aws-cli/2.0.0 Python/3.7.3 Darwin/18.6.0 botocore/2.0.0.

Common Issue Diagnosis

If the problem persists, try these diagnostic steps:

1. Check installation logs: Examine detailed pip installation output for error messages
2. Manually locate executable: Use which aws or find / -name aws 2>/dev/null to find the aws file location
3. Permission check: Ensure /usr/local/bin directory has appropriate write permissions
4. Cache cleanup: Clear pip cache and reinstall: pip cache purge

Alternative Installation Methods

Besides pip installation, AWS CLI offers other installation approaches:

Installation via Homebrew

For macOS users, install AWS CLI via Homebrew:

brew install awscli

This method automatically handles dependencies and PATH configuration, often being simpler and more reliable.

Using Official Installer

Download the macOS-specific installer package (.pkg file) from the AWS website and install via the graphical interface. This method suits users unfamiliar with command-line operations.

Best Practice Recommendations

• Regularly update AWS CLI for latest features and security fixes: pip install --upgrade awscli
• Use IAM roles and credential files to manage access keys, avoiding hardcoded sensitive information in code
• Configure different profiles for different AWS accounts to facilitate multi-account management
• Utilize AWS CLI auto-completion features to improve productivity

Through these steps, users can systematically resolve the -bash: aws: command not found error and establish a stable AWS CLI development environment. Understanding underlying dependency relationships and system configuration mechanisms helps prevent recurrence of similar issues.