boto3 Fundamentals Basics

Seven examples to get you started with boto3, the AWS SDK for Python: five basic and two intermediate.

Because this section is about the boto3 library itself, every example is plain Python. There is no TypeScript pairing here, since these are boto3's own conventions.

Prerequisites

• Install boto3: pip install boto3 (boto3 1.43.x on Python 3.10+; Python 3.9 reached end of life on 2026-04-29).
• Configure credentials once via aws configure, environment variables, or an IAM role. boto3 finds them automatically through its default chain.
• Set a default region with AWS_REGION (or AWS_DEFAULT_REGION), or pass region_name per client.

Basic Examples

1. Install and Import

boto3 is a single package that covers every AWS service.

# pip install boto3
import boto3
 
print(boto3.__version__)   # e.g. 1.43.x

• One install, not one package per service; you select the service later by name.
• boto3 pulls in botocore as a dependency, the lower-level engine it is built on.
• The same install also ships the AWS CLI's core, since the CLI uses botocore too.
• Pin boto3 in your requirements.txt so builds are reproducible.

Related: botocore Under the Hood - the engine beneath boto3.

2. Create a Client

The starting point for every call is a service client bound to a region.

import boto3
 
s3 = boto3.client("s3", region_name="us-east-1")
print(type(s3))   # <class 'botocore.client.S3'>

• boto3.client is one factory for every service, selected by the string name ("s3", "dynamodb", "sqs").
• The returned class is generated at runtime by botocore from the service model, which is why the type is botocore.client.S3.
• The region can also come from AWS_REGION, so you may omit region_name here.
• Creating a client is cheap and makes no network call; reuse it across requests.

Related: boto3's Session, Client & Resource Model - where the client comes from.

3. Make Your First Call

Call an operation method on the client and get a structured response back.

import boto3
 
s3 = boto3.client("s3")
response = s3.list_buckets()
for bucket in response["Buckets"]:
    print(bucket["Name"])

• boto3 exposes each AWS operation as a snake_case method (list_buckets for the ListBuckets API).
• The response is a plain Python dict whose keys mirror the AWS API reference in PascalCase.
• Every response also carries a ResponseMetadata key with the request id and HTTP status.
• No manual signing or HTTP is needed; boto3 builds, signs, and sends the request for you.

Related: boto3 Fundamentals Best Practices - habits to apply from the first call.

4. Read the Response Dict

Responses are ordinary dicts, so use dict access and .get() for optional keys.

import boto3
 
s3 = boto3.client("s3")
head = s3.head_object(Bucket="my-bucket", Key="report.pdf")
 
print(head["ContentLength"])          # required key, present on success
print(head.get("ContentType", "?"))   # optional key, guard with .get()
print(head["ResponseMetadata"]["RequestId"])

• Response keys match the API reference exactly, in PascalCase, even though your methods are snake_case.
• HeadObject fetches metadata only, without downloading the object body.
• Missing optional keys raise KeyError, so reach for .get() when a field may be absent.
• ResponseMetadata is always present and is where you find the request id for logging.

5. Handle Errors

AWS calls fail as ClientError, which you catch and inspect.

import boto3
from botocore.exceptions import ClientError
 
s3 = boto3.client("s3")
try:
    s3.get_object(Bucket="my-bucket", Key="missing.txt")
except ClientError as err:
    code = err.response["Error"]["Code"]           # e.g. "NoSuchKey"
    rid = err.response["ResponseMetadata"]["RequestId"]
    print(code, rid)

• ClientError from botocore.exceptions covers API-level errors for every service.
• Read the service error code from err.response["Error"]["Code"] and branch on it.
• The same err.response dict carries the request id, useful for AWS support cases.
• Never swallow errors silently; match the code you expect and re-raise the rest.

Related: Anatomy of an AWS API Request - what the request id identifies.

Intermediate Examples

6. Paginate a Large Result Set

Many list operations return one page at a time; paginators walk them for you.

import boto3
 
s3 = boto3.client("s3")
paginator = s3.get_paginator("list_objects_v2")
 
for page in paginator.paginate(Bucket="my-bucket", Prefix="logs/"):
    for obj in page.get("Contents", []):
        print(obj["Key"], obj["Size"])

• get_paginator takes the operation name and hides the ContinuationToken bookkeeping.
• Each yielded page is one HTTPS request, so a large prefix can mean many billed calls.
• Guard Contents with .get(..., []) because an empty page omits the key entirely.
• Filter with Prefix server-side so you fetch only the keys you need.

Related: boto3 Fundamentals Best Practices - why paginators beat manual loops.

7. Call a Second Service

The same loop applies to every service; only the client name and operation change.

import boto3
 
ddb = boto3.client("dynamodb", region_name="us-east-1")
ddb.put_item(
    TableName="Visits",
    Item={"id": {"S": "user-7"}, "count": {"N": "1"}},
)

• Switching services means a new client ("dynamodb") and new methods (put_item), nothing more.
• The low-level DynamoDB client uses typed attribute values ({"S": ...}, {"N": ...}).
• boto3 already includes every service, so there is no extra install to call DynamoDB.
• The client-call-dict shape is identical no matter which service you target.

Related: Low-Level Clients vs the Resources API - when a higher-level object layer helps.

Stack versions: This page was written for boto3 1.43.x on Python 3.10+ (and the AWS SDK for JavaScript v3, Node.js 18+, where contrasted).

383k393a3c3q3e393a3o1r3e3k3x383c3e3k1u1u1u1x3x1v1t1v1z1t20