boto3's Session, Client & Resource Model

boto3 has three layered objects you need to keep straight: the Session, the client, and the resource.

Almost every confusing boto3 behavior (wrong region, missing credentials, a NoRegionError from nowhere) traces back to which session you are really using.

This page builds the mental model so the rest of this section reads as variations on one theme. It is a Python-specific model, so the code here is plain boto3 with no cross-SDK pairing.

Summary

• A Session is the object that owns your credentials, default region, and configuration. Clients and resources are always created from a session, whether you see it or not.
• Insight: boto3.client("s3") at module level is not sessionless; it borrows a hidden default session that boto3 lazily creates for you.
• Key Concepts: session, default session, client, resource, credential resolution, region binding, thread safety.
• When to Use: an explicit boto3.Session() whenever you juggle more than one profile, region, or thread; the default session for simple single-account scripts.
• Limitations/Trade-offs: the Resources API is in maintenance mode and does not cover every service, so new code should default to clients.
• Related Topics: named profiles, clients vs the Resources API, and botocore underneath it all.

Foundations

Think of the three objects as layers stacked on top of the AWS API.

At the bottom is the Session. It answers one question: who am I and where am I calling? It resolves credentials from the standard chain (environment variables, shared config files, IAM roles) and pins a default region. Nothing in a session talks to AWS by itself.

In the middle is the client. A client is a thin, auto-generated wrapper whose methods map one-to-one onto AWS API operations: s3.list_buckets(), s3.put_object(...), ddb.get_item(...). This is the low-level surface, and it is what almost all modern boto3 code uses.

At the top, for some services only, is the resource. A resource is an object-oriented layer over the client, exposing things like bucket.objects.all() instead of a paginated list_objects_v2 call. It is ergonomic but legacy.

import boto3
 
session = boto3.Session()            # 1. owns credentials + region
s3_client = session.client("s3")     # 2. low-level, one method per API op
s3_resource = session.resource("s3") # 3. high-level object layer (legacy)
 
print(session.region_name)           # e.g. "us-east-1"

Every client and resource you use is spawned from some session. The only question is whether you named that session or let boto3 create a default one behind your back.

Mechanics & Interactions

When you call boto3.client("s3") (the module-level function, not a session method), boto3 checks for a process-wide default session stored on boto3.DEFAULT_SESSION. If none exists yet, it creates one and reuses it for every later module-level call.

import boto3
 
# These two clients share ONE hidden default session.
s3 = boto3.client("s3")
ddb = boto3.client("dynamodb")
 
# The default session is created lazily on first use.
print(boto3.DEFAULT_SESSION is not None)   # True after the first call

That default session is why setting AWS_PROFILE or AWS_REGION in the environment "just works" for quick scripts: the default session reads them. It is also why a script that needs two profiles cannot rely on the default session. You need explicit sessions instead.

An explicit session takes its configuration as constructor arguments:

import boto3
 
prod = boto3.Session(profile_name="prod", region_name="us-east-1")
dev = boto3.Session(profile_name="dev", region_name="eu-west-1")
 
prod_s3 = prod.client("s3")   # prod credentials, us-east-1
dev_s3 = dev.client("s3")     # dev credentials, eu-west-1

Now each client is bound to a distinct identity and region, which is impossible with the single default session.

Credential and region resolution happen once, when the session is built and first asked for credentials, not on every call. Two clients from the same session share the same resolved credentials and the same region unless you override the region per client.

Advanced Considerations & Applications

Thread safety is the sharp edge of this model, and it is worth memorizing.

Sessions are not thread-safe. A boto3.Session (including the hidden default session) should not be shared across threads. The recommended pattern is one session per thread.

Resources are not thread-safe either, so create a resource per thread as well.

Clients are thread-safe for calling operations. You can construct one client and share it across many threads safely, which is exactly why the default session plus a shared client is a fine pattern for most concurrent code.

import boto3
from concurrent.futures import ThreadPoolExecutor
 
# One client, shared across threads: this is safe.
s3 = boto3.client("s3")
 
def head(key):
    return s3.head_object(Bucket="my-bucket", Key=key)["ContentLength"]
 
with ThreadPoolExecutor(max_workers=8) as pool:
    sizes = list(pool.map(head, ["a.txt", "b.txt", "c.txt"]))

The Resources API adds a second consideration: it is in maintenance mode. AWS has stated the Resources interface receives no new features, and many services (anything added in recent years) never got a resource layer at all. It still works and is not slated for removal, but new code should default to clients so you are never blocked by a missing resource.

Where the model pays off is multi-account tooling: a deployment script that assumes a role per account builds one session per account, spawns the clients it needs, and keeps each account's calls cleanly isolated.

Common Misconceptions

• "boto3.client() has no session." - It always uses a session; if you did not pass one, it uses the lazily created default session on boto3.DEFAULT_SESSION.
• "A client and a resource are the same thing with different syntax." - A client maps one method per raw API operation; a resource is a higher-level object layer built on top of a client, and it exists for only some services.
• "I should prefer resources because they look cleaner." - The Resources API is in maintenance mode with no new features and partial coverage; new code should default to clients.
• "A session opens a connection to AWS." - A session only holds credentials, region, and config; no network call happens until a client or resource actually invokes an operation.
• "One session is fine for all my threads." - Sessions and resources are not thread-safe; create one per thread, though a single client can be shared.

FAQs

Related

• boto3 Fundamentals Basics - your first client call and response dict.
• Sessions: Default, Named Profile & Explicit - constructing sessions for multi-account code.
• Low-Level Clients vs the Resources API - why new code should default to clients.
• botocore Under the Hood - the layer beneath boto3.

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).