{"id":240,"library":"botocore","title":"botocore","description":"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.","status":"active","version":"1.42.77","language":"python","source_language":"en","source_url":"https://github.com/boto/botocore","tags":["aws","cloud","amazon","s3","ec2","iam","http-client","sdk","boto3","cli"],"install":[{"cmd":"pip install botocore","lang":"bash","label":"Install botocore (standalone)"},{"cmd":"pip install boto3","lang":"bash","label":"Install via boto3 (installs a compatible botocore automatically)"}],"dependencies":[{"reason":"HTTP 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+.","package":"urllib3","optional":false},{"reason":"Date/time parsing for AWS response timestamps and credential expiry.","package":"python-dateutil","optional":false},{"reason":"JMESPath query engine used for response filtering and waiters.","package":"jmespath","optional":false},{"reason":"Optional AWS Common Runtime for improved TLS and HTTP/2 performance (used by S3 Transfer and CRT-based auth).","package":"awscrt","optional":true}],"imports":[{"note":"The top-level `botocore` namespace does not expose session or client constructors directly. Always import `botocore.session` and call `get_session()`.","wrong":"import botocore; botocore.session()","symbol":"get_session","correct":"import botocore.session; session = botocore.session.get_session()"},{"note":"All vendored requests/urllib3 exception imports (botocore.vendored.*) were removed. Use botocore.exceptions for all exception classes.","wrong":"from botocore.vendored.requests.exceptions import ...","symbol":"ClientError","correct":"from botocore.exceptions import ClientError"},{"note":"Base class for all client-side botocore errors (config, validation, connectivity). Catch alongside ClientError for complete coverage.","symbol":"BotoCoreError","correct":"from botocore.exceptions import BotoCoreError"},{"note":"Used to configure retries, timeouts, signature version, addressing style, and other per-client options passed via session.create_client(..., config=Config(...)).","symbol":"Config","correct":"from botocore.config import Config"},{"note":"botocore.session.Session is the raw low-level session. boto3.session.Session wraps it and is the preferred interface for most users.","symbol":"Session (low-level)","correct":"import botocore.session; s = botocore.session.Session()"}],"quickstart":{"code":"import os\nimport botocore.session\nfrom botocore.config import Config\nfrom botocore.exceptions import ClientError, BotoCoreError\n\n# Build session — credentials resolved from env, ~/.aws/credentials, or IAM role\nsession = botocore.session.get_session()\n\nclient = session.create_client(\n    's3',\n    region_name=os.environ.get('AWS_DEFAULT_REGION', 'us-east-1'),\n    aws_access_key_id=os.environ.get('AWS_ACCESS_KEY_ID', ''),\n    aws_secret_access_key=os.environ.get('AWS_SECRET_ACCESS_KEY', ''),\n    config=Config(\n        retries={'max_attempts': 5, 'mode': 'adaptive'},\n        connect_timeout=5,\n        read_timeout=10,\n    ),\n)\n\ntry:\n    response = client.list_buckets()\n    for bucket in response.get('Buckets', []):\n        print(bucket['Name'])\nexcept ClientError as e:\n    # AWS service-side error — inspect the structured code, NOT the string message\n    code = e.response['Error']['Code']\n    msg  = e.response['Error']['Message']\n    print(f'AWS error [{code}]: {msg}')\n    if code == 'AccessDenied':\n        raise PermissionError('Check IAM permissions') from e\nexcept BotoCoreError as e:\n    # Client-side error (bad config, network, credential resolution)\n    print(f'botocore client error: {e}')\n    raise\n","lang":"python","description":"Create a botocore session, build an S3 client using environment-variable credentials, and handle errors idiomatically by inspecting the structured error response."},"warnings":[{"fix":"Upgrade to Python 3.10 or later before 2026-04-29. Lambda: migrate function runtime to python3.10 or higher.","message":"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.","severity":"breaking","affected_versions":"all versions after 2026-04-29"},{"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.","message":"botocore.vendored.requests and botocore.vendored.requests.packages.urllib3 were removed. Any import from botocore.vendored.* raises ImportError at runtime.","severity":"breaking","affected_versions":"<1.x (removal was progressive; fully gone in modern 1.x releases)"},{"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.","message":"The old Service/Operation object interface (session.get_service(), service.get_operation()) was fully removed. Only the client interface is supported.","severity":"breaking","affected_versions":"<1.0 (pre-GA code)"},{"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>`.","message":"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.","severity":"breaking","affected_versions":">=1.x (introduced with service_id migration)"},{"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.","message":"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.","severity":"gotcha","affected_versions":"all"},{"fix":"On Python 3.9 environments, pin urllib3<2 explicitly in your requirements. Prefer upgrading to Python 3.10+ where botocore supports urllib3 v2.","message":"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.","severity":"gotcha","affected_versions":"all on Python 3.9"},{"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.","message":"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.","severity":"gotcha","affected_versions":"all"}],"env_vars":null,"last_verified":"2026-05-12T12:16:43.603Z","next_check":"2026-06-25T00:00:00.000Z","problems":[{"fix":"Configure 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).","cause":"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.","error":"botocore.exceptions.NoCredentialsError: Unable to locate credentials"},{"fix":"Verify 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.","cause":"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.","error":"botocore.exceptions.ClientError: An error occurred (InvalidClientTokenId) when calling the [Operation] operation: The security token included in the request is invalid."},{"fix":"Check 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.","cause":"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.","error":"botocore.exceptions.EndpointConnectionError: Could not connect to the endpoint URL"},{"fix":"Consult 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.","cause":"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.","error":"botocore.exceptions.ParamValidationError: Parameter validation failed: Missing required parameter in input: \"ParameterName\""},{"fix":"Check 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.","cause":"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.","error":"botocore.exceptions.EndpointConnectionError: Could not connect to the endpoint URL: \"https://...\""}],"ecosystem":"pypi","meta_description":null,"install_score":100,"install_tag":"verified","quickstart_score":80,"quickstart_tag":"verified","pypi_latest":null,"install_checks":{"last_tested":"2026-05-12","tag":"verified","tag_description":"installs cleanly on critical runtimes, fast import, recently tested","results":[{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.53,"mem_mb":12.7,"disk_size":"50.3M"},{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.53,"mem_mb":12.7,"disk_size":"48.1M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.41,"mem_mb":12.7,"disk_size":"51M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.41,"mem_mb":12.7,"disk_size":"49M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.76,"mem_mb":14.4,"disk_size":"53.2M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.76,"mem_mb":14.4,"disk_size":"50.9M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.64,"mem_mb":14.4,"disk_size":"54M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.65,"mem_mb":14.4,"disk_size":"51M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.65,"mem_mb":14,"disk_size":"44.9M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.65,"mem_mb":14,"disk_size":"42.5M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.65,"mem_mb":14,"disk_size":"45M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.65,"mem_mb":14,"disk_size":"43M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.63,"mem_mb":14.9,"disk_size":"44.5M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.61,"mem_mb":14.9,"disk_size":"42.2M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.63,"mem_mb":14.9,"disk_size":"45M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.65,"mem_mb":14.9,"disk_size":"43M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.43,"mem_mb":11.9,"disk_size":"49.8M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.43,"mem_mb":11.9,"disk_size":"47.6M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.39,"mem_mb":11.9,"disk_size":"50M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.39,"mem_mb":11.9,"disk_size":"48M"}]},"quickstart_checks":{"last_tested":"2026-04-23","tag":"verified","tag_description":"quickstart runs on critical runtimes, recently tested","results":[{"runtime":"python:3.10-alpine","exit_code":0},{"runtime":"python:3.10-slim","exit_code":0},{"runtime":"python:3.11-alpine","exit_code":0},{"runtime":"python:3.11-slim","exit_code":0},{"runtime":"python:3.12-alpine","exit_code":0},{"runtime":"python:3.12-slim","exit_code":0},{"runtime":"python:3.13-alpine","exit_code":0},{"runtime":"python:3.13-slim","exit_code":0},{"runtime":"python:3.9-alpine","exit_code":0},{"runtime":"python:3.9-slim","exit_code":0}]}}