Sessions: Default, Named Profile & Explicit

A boto3.Session is the object that owns your credentials and region. There are three ways to build one, and picking the right one is the difference between clean multi-account code and a tangle of environment hacks.

This is a boto3-specific construct, so every example is plain Python.

Recipe

Build an explicit session when you need a specific profile, region, or credential set instead of whatever the environment happens to provide.

import boto3
 
# Named profile: selects an account defined in ~/.aws/config.
session = boto3.Session(profile_name="prod", region_name="us-east-1")
 
s3 = session.client("s3")
for bucket in s3.list_buckets()["Buckets"]:
    print(bucket["Name"])

When to reach for this:

• You work across more than one AWS account or role in the same process.
• You need to pin a region independently of AWS_REGION.
• You are in a multithreaded app and want one isolated session per thread.
• You are passing temporary credentials from an STS AssumeRole call.

Working Example

This shows all three session styles side by side, plus assuming a role to get a fully explicit session.

import boto3
 
# 1. Default session (implicit): reads env vars + shared config.
default_s3 = boto3.client("s3")   # uses boto3.DEFAULT_SESSION under the hood
 
# 2. Named-profile session: pick a specific account.
dev = boto3.Session(profile_name="dev", region_name="eu-west-1")
dev_s3 = dev.client("s3")
 
# 3. Explicit-credentials session: pass keys directly.
sts = boto3.client("sts")
creds = sts.assume_role(
    RoleArn="arn:aws:iam::222222222222:role/ReadOnly",
    RoleSessionName="report-run",
)["Credentials"]
 
assumed = boto3.Session(
    aws_access_key_id=creds["AccessKeyId"],
    aws_secret_access_key=creds["SecretAccessKey"],
    aws_session_token=creds["SessionToken"],   # required for temp creds
    region_name="us-east-1",
)
assumed_s3 = assumed.client("s3")
print(assumed.client("sts").get_caller_identity()["Arn"])

What this demonstrates:

• The default session needs no arguments and is what module-level boto3.client() uses.
• profile_name selects credentials and region defaults from the shared config files.
• Explicit credentials require the aws_session_token too whenever they are temporary.
• Each session yields independent clients bound to that session's identity.

Deep Dive

The Three Session Styles

• Default (implicit): you never write Session(). Module-level boto3.client() creates and caches one on boto3.DEFAULT_SESSION, reading AWS_PROFILE, AWS_REGION, and the shared config.
• Named profile: boto3.Session(profile_name="...") looks up a [profile NAME] block in ~/.aws/config and matching credentials in ~/.aws/credentials.
• Explicit credentials: boto3.Session(aws_access_key_id=..., aws_secret_access_key=..., aws_session_token=...) skips the config files entirely and uses exactly what you pass.

Where Credentials Come From

• A session resolves credentials lazily through the standard chain: constructor arguments, then environment variables, then shared credentials/config files, then container and instance IAM roles.
• profile_name only changes which config section the file-based steps read; it does not disable the rest of the chain.
• For assumed roles, prefer letting a profile with role_arn + source_profile do the AssumeRole for you, so boto3 also handles automatic credential refresh.

Region Binding

• region_name on the session becomes the default for every client it creates.
• A client can still override it: session.client("s3", region_name="ap-south-1").
• With no region anywhere (session, client, AWS_REGION, config), the first call raises NoRegionError.

One Session Per Thread

• Sessions are not thread-safe. In a ThreadPoolExecutor or multiprocess worker, build a session inside each worker rather than sharing one.
• Clients, by contrast, are thread-safe, so a single client created from one session can be shared across threads.

Gotchas

• Passing temporary keys without the session token - assumed-role and STS credentials need aws_session_token; omitting it fails with an auth error. Fix: always pass all three fields for temporary credentials.
• Assuming profile_name sets the region - a profile may define a region, but if it does not, you still get NoRegionError. Fix: pass region_name explicitly or set it in the profile.
• Sharing one session across threads - sessions are not thread-safe and can produce corrupt or racy credential state. Fix: one session per thread; share only clients.
• Hardcoding keys in an explicit session - literal keys leak into source control and do not rotate. Fix: use a named profile or role, and reserve explicit credentials for values you fetched at runtime from STS.
• Confusing the default session with no session - module-level calls still use a session; changing AWS_PROFILE after the first call will not retroactively rebuild the cached default session. Fix: set env vars before the first boto3 call, or build an explicit session.
• Mixing profiles via env vars in one process - AWS_PROFILE is process-wide, so you cannot serve two accounts by flipping it. Fix: build one explicit session per account instead.

Alternatives

FAQs

Related

• boto3's Session, Client & Resource Model - the object model behind sessions.
• boto3 Fundamentals Basics - your first client and call.
• boto3 Fundamentals Best Practices - session reuse and credential hygiene.
• Low-Level Clients vs the Resources API - what a session spawns.

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