Bug: Suggested removal of docs breaks boto3

[Iamrodos]

Expected Behaviour

The latest release suggests adding this line to your build scripts.

# Remove documentation and examples
find build/ -name "docs" -type d -exec rm -rf {} +

If you include your own version of boto3 in your build, which I believe is recommend over relying on an unpinned version provided by lambda. You get the following error on importing boto3

{
    "timestamp": "2025-09-10T05:23:20Z",
    "log_level": "ERROR",
    "errorMessage": "Unable to import module 'lambda_web_function': No module named 'botocore.docs'",
    "errorType": "Runtime.ImportModuleError",
    "requestId": "",
    "stackTrace": []
}

I am not importing this, I am only importing

import boto3
from botocore.exceptions import ClientError

Current Behaviour

No error.

Code snippet

# Remove documentation and examples
find build/ -name "docs" -type d -exec rm -rf {} +

Possible Solution

Don't remove docs

Steps to Reproduce

See above

Powertools for AWS Lambda (Python) version

latest

AWS Lambda function runtime

3.13

Packaging format used

Lambda Layers

Debugging logs

[boring-cyborg]

Thanks for opening your first issue here! We'll come back to you as soon as we can.
In the meantime, check out the #python channel on our Powertools for AWS Lambda Discord: Invite link

[Iamrodos]

The import botocore.docs.utils statement is located directly within botocore/handlers.py. Specifically, it's found at the top of the file botocore/handlers.py

from botocore.docs.utils import (
      AppendParamDocumentation,
      AutoPopulatedParam,
      HideParamFromOperations,
  )

This import is executed immediately when a botocore.session.Session is initialized (which occurs when boto3 is imported). The botocore/handlers.py file definesBUILTIN_HANDLERS that are fundamental to botocore's runtime functionality (e.g., parameter handling, S3 customizations, etc.), and are not solely for documentation generation.

Therefore, botocore.docs appears to be a required runtime dependency for botocore's core operations. Its removal breaks essential functionality, leading to theImportModuleError. The suggestion to remove the docs directory seems to inadvertently remove a critical runtime component.

---

This analysis was with the assistance of a Gemini-powered AI agent.

[leandrodamascena]

Ohhh thanks a lot for this catch @Iamrodos! We really need to fix that, do you want to send a PR to fix it? I'd love your contribution here.

[Iamrodos]

Ohhh thanks a lot for this catch @Iamrodos! We really need to fix that, do you want to send a PR to fix it? I'd love your contribution here.

@leandrodamascena Happy to do a PR. How to handle it though? Change the command to exclude boto3? To add a comment to be aware of the issue? To remove the recommendation to remove docs from the list? Not sure which is the optimal resolution.

[leandrodamascena]

Ohhh thanks a lot for this catch @Iamrodos! We really need to fix that, do you want to send a PR to fix it? I'd love your contribution here.

@leandrodamascena Happy to do a PR. How to handle it though? Change the command to exclude boto3? To add a comment to be aware of the issue? To remove the recommendation to remove docs from the list? Not sure which is the optimal resolution.

For now, I think we just need to remove the docs and examples lines. We can't predict if someone is naming their folders that way.

find build/ -name "docs" -type d -exec rm -rf {} +
find build/ -name "examples" -type d -exec rm -rf {} +

[Iamrodos]

What about this? As its still a good idea, maybe it just needs sufficient warning.

Removing documentation and examples

To reduce package size, you may want to remove unwanted documentation and example folders from dependencies.
Be careful as some libraries might rely on folders without your knowledge. For example if you include a vendored version of Boto3, it relies on bootcore.docs.utils. Ensure you test the build artefact before deployment.

# Remove documentation and examples—but preserve botocore/docs to avoid Boto3 runtime errors
find build/ -type d -name "docs" ! -path "*/botocore/docs" -exec rm -rf {} +
find build/ -type d -name "examples" -exec rm -rf {} +

[Iamrodos]

I will do a PR on this in the morning and we can resolve there.

[leandrodamascena]

I would prefer to remove the docs lines, at least. If botocore did it, maybe other libraries can do it too. Maybe keep the examples.

[powertools-for-aws-oss-automation]

Warning

This issue is now closed. Please be mindful that future comments are hard for our team to see.
If you need more assistance, please either reopen the issue, or open a new issue referencing this one.
If you wish to keep having a conversation with other community members under this issue feel free to do so.