What causes "Please run `pip install boto3 botocore` to use AWS services." in run-llama/llama_index?

Install the packages: pip install boto3 botocore.

run-llama/llama_index · error · ImportError

Please run `pip install boto3 botocore` to use AWS services.

Error message

Please run `pip install boto3 botocore` to use AWS services.

What it means

llama_index.core.utilities.aws_utils.get_aws_client() imports boto3/botocore lazily because they are optional dependencies of llama-index-core. If neither is installed, the ImportError tells you to install them explicitly before any AWS client (Bedrock, S3, etc.) can be created.

Source

Thrown at llama-index-core/llama_index/core/utilities/aws_utils.py:21

if TYPE_CHECKING:
    import botocore


def get_aws_service_client(
    service_name: Optional[str] = None,
    region_name: Optional[str] = None,
    aws_access_key_id: Optional[str] = None,
    aws_secret_access_key: Optional[str] = None,
    aws_session_token: Optional[str] = None,
    profile_name: Optional[str] = None,
    max_retries: Optional[int] = 3,
    timeout: Optional[float] = 60.0,
) -> "botocore.client.BaseClient":
    try:
        import boto3
        import botocore
    except ImportError:
        raise ImportError(
            "Please run `pip install boto3 botocore` to use AWS services."
        )

    config = botocore.config.Config(
        retries={"max_attempts": max_retries or 0, "mode": "standard"},
        connect_timeout=timeout,
    )

    try:
        if not profile_name and aws_access_key_id:
            session = boto3.Session(
                aws_access_key_id=aws_access_key_id,
                aws_secret_access_key=aws_secret_access_key,
                aws_session_token=aws_session_token,
                region_name=region_name,
            )
            client = session.client(service_name, config=config)  # type: ignore
        else:

View on GitHub (pinned to afd0fef371)

Solutions

Install the packages: pip install boto3 botocore.
Prefer the packaged integration extra, e.g. pip install llama-index-llms-bedrock, which pulls boto3 in.
Pin boto3 to a version compatible with your botocore to avoid downstream resolution errors.

Example fix

# before (ImportError at runtime)
 client = get_aws_client(service_name='bedrock-runtime', region_name='us-east-1')

# after (shell)
# pip install boto3 botocore
 client = get_aws_client(service_name='bedrock-runtime', region_name='us-east-1')

Defensive patterns

Strategy: validation

Validate before calling

def ensure_boto3_installed():
    try:
        import boto3, botocore  # noqa: F401
    except ImportError:
        raise RuntimeError('AWS features need boto3: pip install boto3 botocore')

ensure_boto3_installed()  # run at app startup, before any AWS call

Type guard

def aws_deps_available() -> bool:
    try:
        import boto3, botocore  # noqa: F401
        return True
    except ImportError:
        return False

Try / catch

try:
    client = get_aws_client('bedrock-runtime', region_name=region)
except ImportError as e:
    if 'boto3' in str(e):
        raise RuntimeError('Install AWS deps: pip install llama-index-llms-bedrock') from e
    raise

Prevention

Declare boto3 in requirements when using any AWS-backed integration.
Prefer integration extras (e.g. llama-index-llms-bedrock) that pull boto3 automatically.
Fail fast at startup with an import probe instead of mid-request.

When it happens

Trigger: Calling get_aws_client(service_name='bedrock-runtime', ...) (directly or via a Bedrock LLM/embedding integration or an S3 document reader) in an environment where 'pip install boto3 botocore' was never run.

Common situations: Fresh virtualenv with only llama-index-core installed; Docker images trimmed of optional deps; CI environments where the AWS extras were not declared in requirements.txt.

Related errors

AI-assisted analysis of run-llama/llama_index@afd0fef371 (2026-08-15). Data as JSON: /api/errors/7f12581e0347c72f. Report an issue: GitHub.