botocore

Warnings

• breaking Python 3.9 support ends 2026-04-29. After that date botocore will require Python 3.10+. Plan runtime upgrades now, especially for AWS Lambda functions still on the Python 3.9 runtime.
  Fix: Upgrade to Python 3.10 or later before 2026-04-29. Lambda: migrate function runtime to python3.10 or higher.
• breaking botocore.vendored.requests and botocore.vendored.requests.packages.urllib3 were removed. Any import from botocore.vendored.* raises ImportError at runtime.
  Fix: Replace `from botocore.vendored.requests.exceptions import ...` with `from botocore.exceptions import ClientError` (and other classes from botocore.exceptions). Import requests/urllib3 exceptions directly from those packages if needed.
• breaking The old Service/Operation object interface (session.get_service(), service.get_operation()) was fully removed. Only the client interface is supported.
  Fix: Use `session.create_client('service_name')` and call operations as methods on the client object (e.g., `client.describe_instances()`). All kwargs must be CamelCase — the old snake_case auto-mapping is gone.
• breaking The event system emits events keyed by service_id (hyphenated), not by endpoint prefix. Handlers registered against e.g. `before-call.autoscaling` may silently stop firing or start firing for unintended services when endpoint prefixes are shared.
  Fix: Derive the correct event name at runtime: `client.meta.service_model.service_id.hyphenize()`, then register your handler against `before-call.<hyphenized-service-id>`.
• gotcha All AWS service exceptions are raised as `ClientError`, not as typed subclasses. You cannot catch service-specific errors by exception type alone — you must inspect `e.response['Error']['Code']` (a string) to branch on specific error codes.
  Fix: Always check `e.response['Error']['Code']` inside an `except ClientError` block. Do not rely on HTTP status codes or exception message strings, which are subject to change.
• gotcha urllib3 v2 is only supported on Python 3.10+. On Python 3.9, botocore pins urllib3<1.27, which conflicts with packages that require urllib3>=2. Installing both in the same environment silently pins you to the older urllib3 or raises a ResolutionImpossible error.
  Fix: On Python 3.9 environments, pin urllib3<2 explicitly in your requirements. Prefer upgrading to Python 3.10+ where botocore supports urllib3 v2.
• gotcha Credentials are resolved lazily at first API call, not at client creation. Missing or expired credentials raise `NoCredentialsError` or `ClientError` (ExpiredTokenException) only when a request is made, making silent misconfiguration easy to overlook during startup.
  Fix: Validate credentials eagerly in application startup via `session.get_credentials()` and check the result is not None, or make a cheap test call (e.g., `sts.get_caller_identity()`) to fail fast.

Install

• pip install botocore Install botocore (standalone)
• pip install boto3 Install via boto3 (installs a compatible botocore automatically)

Imports

• get_session

  import botocore.session; session = botocore.session.get_session()

  The top-level `botocore` namespace does not expose session or client constructors directly. Always import `botocore.session` and call `get_session()`.
• ClientError

  from botocore.exceptions import ClientError

  All vendored requests/urllib3 exception imports (botocore.vendored.*) were removed. Use botocore.exceptions for all exception classes.
• BotoCoreError

  from botocore.exceptions import BotoCoreError

  Base class for all client-side botocore errors (config, validation, connectivity). Catch alongside ClientError for complete coverage.
• Config

  from botocore.config import Config

  Used to configure retries, timeouts, signature version, addressing style, and other per-client options passed via session.create_client(..., config=Config(...)).
• Session (low-level)

  import botocore.session; s = botocore.session.Session()

  botocore.session.Session is the raw low-level session. boto3.session.Session wraps it and is the preferred interface for most users.

Quickstart

Create a botocore session, build an S3 client using environment-variable credentials, and handle errors idiomatically by inspecting the structured error response.

import os
import botocore.session
from botocore.config import Config
from botocore.exceptions import ClientError, BotoCoreError

# Build session — credentials resolved from env, ~/.aws/credentials, or IAM role
session = botocore.session.get_session()

client = session.create_client(
    's3',
    region_name=os.environ.get('AWS_DEFAULT_REGION', 'us-east-1'),
    aws_access_key_id=os.environ.get('AWS_ACCESS_KEY_ID', ''),
    aws_secret_access_key=os.environ.get('AWS_SECRET_ACCESS_KEY', ''),
    config=Config(
        retries={'max_attempts': 5, 'mode': 'adaptive'},
        connect_timeout=5,
        read_timeout=10,
    ),
)

try:
    response = client.list_buckets()
    for bucket in response.get('Buckets', []):
        print(bucket['Name'])
except ClientError as e:
    # AWS service-side error — inspect the structured code, NOT the string message
    code = e.response['Error']['Code']
    msg  = e.response['Error']['Message']
    print(f'AWS error [{code}]: {msg}')
    if code == 'AccessDenied':
        raise PermissionError('Check IAM permissions') from e
except BotoCoreError as e:
    # Client-side error (bad config, network, credential resolution)
    print(f'botocore client error: {e}')
    raise