AWS CLI v2 Python Wrapper

2.3.1 · active · verified Sun Apr 12

awscliv2 is a Python wrapper designed to provide a programmatic interface for interacting with the AWS CLI v2. It allows Python applications to execute AWS CLI commands, parse their output, and manage AWS resources without directly invoking shell commands. The library supports installing and updating the underlying AWS CLI v2 binaries or utilizing a Docker fallback. It is actively maintained, with the current version being 2.3.1.

Warnings

breaking Python 3.6 support was removed in version 2.0.0. Projects using older Python versions must upgrade to Python 3.7 or newer to use awscliv2 >= 2.0.0.
Fix: Upgrade your Python environment to 3.7 or a later compatible version.
gotcha This library is an unofficial wrapper for the AWS CLI v2, not an official AWS SDK or an official AWS-published PyPI package. Users should be aware of this distinction and verify its suitability for their security requirements.
Fix: Review the source code and ensure it meets your project's security and reliability standards.
gotcha By default, the library uses the `amazon/aws-cli` Docker image to run AWS CLI commands if the native AWS CLI v2 binary is not installed via `awsv2 --install`. Using Docker may involve running as a root user and could require manual permission adjustments for downloaded files.
Fix: For production or performance-critical environments, consider installing the native AWS CLI v2 binary using `awsv2 --install` and ensure Docker permissions are properly managed if relying on the Docker fallback.
gotcha In versions prior to 2.3.1, `AWSAPI.execute` would raise an exception on a non-zero status code, and specific issues existed with output handling on Windows and `AWSAPI.assume_role` parsing. While fixed in 2.3.1, users on older versions may encounter these issues.
Fix: Upgrade to awscliv2 version 2.3.1 or later to benefit from improved error handling and output parsing robustness, especially on Windows or when using `assume_role`.

Install

pip install awscliv2 Install awscliv2 Python package
awsv2 --install Install underlying AWS CLI v2 binary (optional, defaults to Docker)

Imports

AWSAPI
```
from awscliv2.api import AWSAPI
```
AWSCLIError
```
from awscliv2.exceptions import AWSCLIError
```
Import for handling specific exceptions raised by AWS CLI commands.

Quickstart

This quickstart demonstrates how to initialize the `AWSAPI` client and execute a basic AWS CLI command, such as listing S3 buckets. Ensure your AWS credentials are configured either via environment variables (`AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_REGION`) or by running `awsv2 --configure` previously. The `AWSCLIError` is recommended for catching CLI-specific issues.

import os
from awscliv2.api import AWSAPI
from awscliv2.exceptions import AWSCLIError

# AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY should be set as environment variables
# or configured via `awsv2 --configure` for the underlying AWS CLI to pick them up.
# Example: os.environ['AWS_ACCESS_KEY_ID'] = 'YOUR_ACCESS_KEY'
# Example: os.environ['AWS_SECRET_ACCESS_KEY'] = 'YOUR_SECRET_KEY'

aws_api = AWSAPI()
try:
    # List S3 buckets
    output = aws_api.execute(['s3', 'ls'])
    print('S3 Buckets:\n', output)

    # Describe EC2 instances (example, might require specific region/permissions)
    # output = aws_api.execute(['ec2', 'describe-instances'])
    # print('EC2 Instances:\n', output)

except AWSCLIError as e:
    print(f"AWS CLI Error: {e.return_code} - {e.stderr}")
except Exception as e:
    print(f"An unexpected error occurred: {e}")

view raw JSON →