botocore is the low-level, data-driven core of boto3 and the AWS CLI, providing a direct interface to Amazon Web Services APIs. It handles request signing (AWS Signature Version 4), credential resolution, retry logic, pagination, and service model loading. Current version is 1.42.77, released by Amazon Web Services. Releases are extremely frequent — often multiple times per week — tracking new and updated AWS service APIs. Most users interact with botocore indirectly via boto3, but direct use is common for fine-grained control, event hooks, custom credential providers, and low-overhead Lambda code.
Install & Compatibility
Where this runs
tested against v1.43.25 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.950 runs
installs and imports cleanly · install 0.0s · import 0.587s · 50.8MB
glibcpy 3.10–3.950 runs
installs and imports cleanly · install 3.3s · import 0.545s · 51MB
49MB installed
● package 49MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
get_session
✓ import botocore.session; session = botocore.session.get_session()
✗ import botocore; botocore.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
✗ from botocore.vendored.requests.exceptions import ...
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.
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
Debug
Known issues
breakingPython 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.fixUpgrade to Python 3.10 or later before 2026-04-29. Lambda: migrate function runtime to python3.10 or higher.
affects: all versions after 2026-04-29
breakingbotocore.vendored.requests and botocore.vendored.requests.packages.urllib3 were removed. Any import from botocore.vendored.* raises ImportError at runtime.fixReplace `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.
affects: <1.x (removal was progressive; fully gone in modern 1.x releases)
breakingThe old Service/Operation object interface (session.get_service(), service.get_operation()) was fully removed. Only the client interface is supported.fixUse `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. affects: <1.0 (pre-GA code)
breakingThe 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.fixDerive the correct event name at runtime: `client.meta.service_model.service_id.hyphenize()`, then register your handler against `before-call.<hyphenized-service-id>`.
affects: >=1.x (introduced with service_id migration)
gotchaAll 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.fixAlways 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.
affects: all
gotchaurllib3 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.fixOn Python 3.9 environments, pin urllib3<2 explicitly in your requirements. Prefer upgrading to Python 3.10+ where botocore supports urllib3 v2.
affects: all on Python 3.9
gotchaCredentials 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.fixValidate 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.
affects: all
Errors
Common errors & fixes
botocore.exceptions.NoCredentialsError: Unable to locate credentials
The botocore library cannot find valid AWS credentials in any of the expected locations, such as environment variables, shared credentials file (`~/.aws/credentials`), or an attached IAM role.
fixConfigure AWS credentials by running `aws configure` via the AWS CLI, setting `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, and optionally `AWS_SESSION_TOKEN` environment variables, or ensuring an appropriate IAM role is assigned to your AWS compute resource (e.g., EC2, Lambda).
botocore.exceptions.ClientError: An error occurred (InvalidClientTokenId) when calling the [Operation] operation: The security token included in the request is invalid.
AWS received the request but rejected the provided security token because it is expired, incorrect, deactivated, or there is a clock skew between your system and AWS servers.
fixVerify your AWS access key ID and secret access key are correct and active, refresh temporary credentials if using them (e.g., from AWS STS or SSO), ensure your system's clock is synchronized, and check for conflicting credential sources or cached tokens.
botocore.exceptions.EndpointConnectionError: Could not connect to the endpoint URL
The botocore library failed to establish a network connection to the AWS service endpoint, often due to network issues, incorrect AWS region configuration, DNS problems, or proxy settings.
fixCheck your network connectivity, ensure the AWS region configured in your code or environment (e.g., `AWS_DEFAULT_REGION`) matches the target service, verify proxy settings if applicable, and confirm proper DNS resolution for the endpoint.
botocore.exceptions.ParamValidationError: Parameter validation failed: Missing required parameter in input: "ParameterName"
An AWS API call was made with missing required parameters or parameters of the wrong data type or format, according to the specific AWS service's API model.
fixConsult the official Boto3/botocore documentation for the specific AWS service and operation you are calling to ensure all required parameters are provided with the correct types and values.
botocore.exceptions.EndpointConnectionError: Could not connect to the endpoint URL: "https://..."
The client failed to establish a connection to the specified AWS service endpoint, often due to network issues, an incorrect endpoint URL, or firewall restrictions.
fixCheck network connectivity, verify the AWS region and service endpoint URL are correct, confirm any proxy settings are configured properly, or examine firewall rules that might be blocking the connection.
Audit
Dependencies
urllib3requiredHTTP transport layer for all AWS API requests. botocore pins urllib3>=1.25.4,<1.27 on Python <3.10 and supports urllib3 v2 only on Python 3.10+.
python-dateutilrequiredDate/time parsing for AWS response timestamps and credential expiry.
jmespathrequiredJMESPath query engine used for response filtering and waiters.
awscrtoptionalOptional AWS Common Runtime for improved TLS and HTTP/2 performance (used by S3 Transfer and CRT-based auth).