Skip to main content

Boto3 Python AWS SDK: Quick Start Guide

Boto3 is the official Amazon Web Services (AWS) SDK for Python, enabling you to write Python code that interacts with AWS services via REST APIs without manually constructing HTTP requests. A single boto3.client('s3').list_buckets() call retrieves all S3 buckets; behind the scenes, Boto3 handles authentication, request signing, retries, and response parsing. Installing Boto3 takes 30 seconds; making your first API call takes 10 minutes once credentials are configured.

Installing Boto3​

Boto3 is available on PyPI (Python Package Index) and installs via pip like any Python dependency.

pip install boto3

Verify the installation by checking the version:

python -c "import boto3; print(boto3.__version__)"

This prints something like 1.26.137 (the version changes frequently; any version from 2025 onward is suitable for modern AWS).

For development, install within a virtual environment to avoid conflicts:

python -m venv env
source env/bin/activate  # On Windows: env\Scripts\activate
pip install boto3

Configuring AWS Credentials​

Boto3 needs AWS credentials (Access Key ID and Secret Access Key) to sign requests. Four credential sources are checked in this order:

  1. Environment variables (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY)
  2. Credential file (~/.aws/credentials)
  3. IAM role (if running on an EC2 instance or ECS container)
  4. STS (Secure Token Service) temporary credentials from assume-role calls

For local development, the credential file is simplest. Generate credentials in the AWS Console (IAM > Users > Security credentials > Create access key) and write them to ~/.aws/credentials:

[default]
aws_access_key_id = AKIAIOSFODNN7EXAMPLE
aws_secret_access_key = wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY

Then set your default region in ~/.aws/config:

[default]
region = us-east-1

Boto3 reads both files automatically when you create a client. You can also configure credentials via environment variables:

export AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
export AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
export AWS_DEFAULT_REGION=us-east-1

For production systems running on AWS (EC2, ECS, Lambda), use IAM roles instead. Boto3 automatically reads credentials from the instance metadata service; no credentials file needed.

Your First Boto3 Client​

Boto3 provides two main interfaces: clients (low-level, matches AWS API exactly) and resources (high-level, object-oriented). Start with clients; they're more explicit about what API call is being made.

Create an S3 client and list buckets:

import boto3

# Create an S3 client (uses credentials from ~/.aws/credentials or env vars)
s3_client = boto3.client('s3', region_name='us-east-1')

# List all S3 buckets in the account
response = s3_client.list_buckets()
print(response)

The response is a dictionary (inherited from the JSON returned by AWS):

{
    'Buckets': [
        {'Name': 'my-app-bucket', 'CreationDate': datetime.datetime(2024, 3, 15, ...)},
        {'Name': 'logs-bucket', 'CreationDate': datetime.datetime(2024, 1, 20, ...)}
    ],
    'Owner': {'DisplayName': 'root', 'ID': '...'},
    'ResponseMetadata': {'RequestId': '...', 'HTTPStatusCode': 200, ...}
}

Pretty-print the bucket names:

for bucket in response['Buckets']:
    print(f"Bucket: {bucket['Name']}")

Common AWS Services with Boto3​

Boto3 supports 200+ AWS services. Here's a quick reference for the most common:

ServiceClient NameCommon Method
EC2ec2describe_instances(), run_instances(), terminate_instances()
S3s3list_buckets(), put_object(), get_object()
DynamoDBdynamodbget_item(), put_item(), query(), scan()
Lambdalambdainvoke(), create_function(), update_function_code()
RDSrdsdescribe_db_instances(), create_db_instance()
SNSsnspublish(), create_topic(), subscribe()
SQSsqssend_message(), receive_message(), delete_message()
CloudWatchcloudwatchput_metric_data(), get_metric_statistics()
IAMiamcreate_user(), attach_user_policy(), create_access_key()

Example: describe running EC2 instances:

import boto3

ec2 = boto3.client('ec2', region_name='us-east-1')
response = ec2.describe_instances()

for reservation in response['Reservations']:
    for instance in reservation['Instances']:
        print(f"Instance ID: {instance['InstanceId']}, State: {instance['State']['Name']}")

Error Handling and Exceptions​

Boto3 raises botocore.exceptions.ClientError when AWS rejects a request. Always wrap API calls in try-except to handle transient failures, permission errors, and resource-not-found scenarios:

import boto3
from botocore.exceptions import ClientError

s3 = boto3.client('s3')

try:
    s3.head_bucket(Bucket='my-bucket')
    print("Bucket exists")
except ClientError as e:
    error_code = e.response['Error']['Code']
    if error_code == '404':
        print("Bucket does not exist")
    elif error_code == 'AccessDenied':
        print("Permission denied")
    else:
        print(f"Unexpected error: {error_code}")

Key Takeaways​

  • Boto3 is the official AWS SDK for Python, installed via pip install boto3.
  • Credentials are read from credential files (~/.aws/credentials), environment variables, or IAM roles; never hardcode credentials in code.
  • Create a client with boto3.client('service_name'), then call methods matching the AWS API (e.g., list_buckets(), describe_instances()).
  • Responses are dictionaries; always wrap calls in try-except blocks to handle ClientError exceptions gracefully.
  • Boto3 supports 200+ AWS services with low-level client APIs and high-level resource abstractions.

Frequently Asked Questions​

What's the difference between a Boto3 client and resource?​

A client is low-level and matches the AWS API exactly (every call is explicit). A resource is high-level and object-oriented (e.g., s3.Bucket('name').objects.all()). Use clients for clarity and control; use resources for brevity when available.

Can I run Boto3 outside of AWS?​

Yes. Any machine with Boto3 installed and AWS credentials can call AWS APIs (macOS, Linux, Windows, Raspberry Pi). For production, run Boto3 on EC2 or ECS so it can use IAM roles instead of hardcoded credentials.

How do I test Boto3 code locally?​

Use moto, a library that mocks AWS services. Install pip install moto, then decorate your tests with @mock_s3, @mock_ec2, etc. This lets you test without hitting real AWS and without credentials on your dev machine.

Is Boto3 synchronous or asynchronous?​

By default, Boto3 is synchronous (blocking). For async/await, use aioboto3 (built on top of Boto3) or the async Boto3 client (boto3.Session().client('service', config=Config(s3={'addressing_style': 'virtual'}))).

How do I handle rate limits and retries?​

Boto3 retries failed requests automatically (up to 3 times by default). For rate-limited APIs, use exponential backoff. Configure retry behavior via the Config object: boto3.client('s3', config=Config(retries={'max_attempts': 5})).

Further Reading​