/aws-sdk-python-usage

Client Configuration Reference

botocore.config.Config

All configuration is passed via botocore.config.Config. Multiple configs can be merged:

from botocore.config import Config

base = Config(retries={"total_max_attempts": 2, "mode": "standard"})
s3_specific = Config(s3={"addressing_style": "path"})

# Merge -- later config wins on conflicts
client = boto3.client("s3", config=base.merge(s3_specific))

Retry Configuration

config = Config(
    retries={
        "total_max_attempts": 2,    # total attempts including first try (1 retry attempt here)
        "mode": "adaptive",         # legacy | standard | adaptive
    }
)

Prefer using total_max_attempts over the legacy max_attempts. The max_attempts value does not include the first attempt (it's actually the number of retry attempts).

Can also set via AWS_MAX_ATTEMPTS and AWS_RETRY_MODE env vars or ~/.aws/config.

Timeouts

config = Config(
    connect_timeout=5,    # seconds to establish connection (default 60)
    read_timeout=10,      # seconds to wait for response data (default 60)
)

Connection Pool

config = Config(
    max_pool_connections=50,  # default 10 per client
)

Each client maintains its own urllib3 connection pool. If you're making parallel requests (e.g. with concurrent.futures), set max_pool_connections to match your concurrency level to avoid connection churn.

Custom Endpoints

# Custom S3 endpoint on localhost.
client = boto3.client(
    "s3",
    endpoint_url="http://localhost:4566",
    region_name="us-east-1",
)

# FIPS endpoints
config = Config(use_fips_endpoint=True)
client = boto3.client("s3", config=config)

# Dual-stack (IPv4 + IPv6)
config = Config(use_dualstack_endpoint=True)
client = boto3.client("s3", config=config)

Proxy Configuration

# Via environment variables (preferred)
# HTTP_PROXY=http://proxy:8080
# HTTPS_PROXY=http://proxy:8080

# Via Config
config = Config(
    proxies={"https": "http://proxy:8080"},
    proxies_config={"proxy_ca_bundle": "/path/to/ca-bundle.crt"},
)

S3-Specific Configuration

config = Config(
    s3={
        "addressing_style": "path",       # path | virtual | auto (default)
        "payload_signing_enabled": False,  # skip payload signing for large uploads
        "us_east_1_regional_endpoint": "regional",
    },
    signature_version="s3v4",
)

# Transfer acceleration
config = Config(s3={"use_accelerate_endpoint": True})

User-Agent Customization

config = Config(
    user_agent_appid="my-app/1.0",
    user_agent_extra="custom-metadata",
)

Sharing Config Across Clients

from botocore.config import Config

config = Config(
    retries={"total_max_attempts": 2, "mode": "standard"},
    connect_timeout=5,
    read_timeout=10,
)

# Same config for multiple clients
s3 = boto3.client("s3", config=config)
dynamodb = boto3.client("dynamodb", config=config)
lambda_client = boto3.client("lambda", config=config)

You can also set a default client config in a botocore Session:

from botocore.config import Config
from botocore.session import Session

config = Config(
    retries={"total_max_attempts": 2, "mode": "standard"},
    connect_timeout=5,
    read_timeout=10,
)
session = Session()
session.set_default_client_config(config)
# Now all clients created will use this session-specific default
# config if an explicit config is not provided.
s3 = session.create_client('s3')
dynamodb = session.create_client('dynamodb')