AWS SDK for Python (boto3)

Warnings

• gotcha Region is not globally defaulted. Calling boto3.client('s3') without region_name and without AWS_DEFAULT_REGION raises botocore.exceptions.NoRegionError. This is the most common source of 'it works on my machine' failures when deploying to CI/CD.
  Fix: Always pass region_name= explicitly, or set AWS_DEFAULT_REGION in the environment.
• gotcha NoCredentialsError means the credential chain was exhausted — no credentials found anywhere. Common in CI/CD when AWS_ACCESS_KEY_ID is set but AWS_SECRET_ACCESS_KEY is missing, or when ~/.aws/credentials exists locally but not in the deployment environment.
  Fix: Check all chain links: env vars (both KEY and SECRET required), ~/.aws/credentials format, IAM instance role attachment.
• gotcha boto3.client() and boto3.resource() return different objects with different APIs. S3 client uses client.put_object(), resource uses s3.Object().put(). Mixing client and resource patterns causes AttributeError.
  Fix: Choose one pattern per codebase. boto3.resource() is higher-level but covers fewer services. boto3.client() covers all services.
• gotcha Pinning boto3 without pinning botocore (or vice versa) causes version conflicts. boto3 and botocore ship together daily and must stay version-compatible.
  Fix: Pin both: boto3==X.Y.Z botocore==A.B.C. Check boto3's setup.py for the exact botocore version it requires.
• gotcha ClientError contains all AWS service errors. The error code is at e.response['Error']['Code'], not as a Python exception type. Catching specific AWS errors requires checking this string.
  Fix: except ClientError as e: if e.response['Error']['Code'] == 'NoSuchBucket': ...
• gotcha boto3.setup_default_session() modifies global state and is not thread-safe. In multi-threaded or async applications, concurrent calls with different credentials will interfere.
  Fix: Use boto3.Session() to create isolated sessions per thread/coroutine.

Install

• pip install boto3 Python
• pip install boto3[crt] With CRT (faster S3 transfers)

Imports

• boto3.client (low-level)

  import boto3
  
  # Explicit credentials (not recommended for production)
  client = boto3.client(
      's3',
      region_name='us-east-1',
      aws_access_key_id='KEY',
      aws_secret_access_key='SECRET'
  )
  
  # Preferred: let credential chain resolve
  client = boto3.client('s3', region_name='us-east-1')

  Omitting region_name raises NoRegionError for most services unless AWS_DEFAULT_REGION is set.
• boto3.Session (multi-profile)

  import boto3
  
  session = boto3.Session(
      profile_name='my-profile',
      region_name='eu-west-1'
  )
  client = session.client('dynamodb')

  setup_default_session() modifies global state — unsafe in multi-threaded apps. Use Session() instead.

Quickstart

Credential chain order: (1) explicit in code, (2) env vars AWS_ACCESS_KEY_ID/AWS_SECRET_ACCESS_KEY, (3) ~/.aws/credentials, (4) ~/.aws/config, (5) EC2/ECS instance metadata.

import boto3
from botocore.exceptions import ClientError, NoCredentialsError

# Credential chain: env vars → ~/.aws/credentials → IAM role → ...
# Set AWS_DEFAULT_REGION or pass region_name explicitly
client = boto3.client('s3', region_name='us-east-1')

try:
    # List buckets
    response = client.list_buckets()
    for bucket in response['Buckets']:
        print(bucket['Name'])
except NoCredentialsError:
    print('No AWS credentials found')
except ClientError as e:
    print(f"Error: {e.response['Error']['Code']}: {e.response['Error']['Message']}")