Python relative imports in AWS Lambda fail with `attempted relative import with no known parent package`

aws-lambda-relative-import-no-known-parent-package.md

Python relative imports in AWS Lambda fail with attempted relative import with no known parent package

The Problem

In AWS Lambda if I attempt an explicit relative import like this

.
├── lambda_file.py
└── example.py

# lambda_file.py
from .example import lambda_handler

# example.py
def lambda_handler(event, context):
    return True

And I configure AWS Lambda's handler to lambda_file.lambda_handler I get the following errors

• Python 2.7 : Attempted relative import in non-package
• Python 3.7 : attempted relative import with no known parent package

Why use explicit relative imports

PEP008 says :

Implicit relative imports should never be used and have been removed in Python 3.

How to workaround by using implicit relative imports

If I change lambda_file.py to contain the following, it works, but no longer uses explicit relative imports

# lambda_file.py
from example import lambda_handler

How to correctly solve the problem

The solution is to ensure that the "Handler" value that you configure in AWS Lambda contain at least 2 . periods. To achieve this you need to put your code within a directory in your AWS Lambda code zip file and make that directory a module by adding an empty __init__.py file. The resulting structure looks like this

.
├── app
│   ├── __init__.py
│   ├── lambda_file.py
│   └── example.py

And you now change the "Handler" value from lambda_file.lambda_handler to app.lambda_file.lambda_handler

Additional Notes

• AWS Lambda loads your handler as a module import not as a top-level script
• This solution came after reading this explanation of explicit relative imports by Brendan Barnwell

Instead of folder restructuring you can add the line below to lambda_file.py. This adds the Lambda file's directory to the path.
You can then use absolute, rather than relative, imports inside lambda_file.py.

sys.path.append(os.path.join(os.path.dirname(__file__)))

@Jordan-Eckowitz
works great!

Deploying with container images
If you are Deploying container images, you may also need to make these modifications.
This is before breaking into multiple files.

.
├── app.py
|── Dockerfile
└── requirements.txt

After with the lambda_handler in the __init__.py

.
├── app
│   ├── __init__.py
│   ├── models.py
│   ├── exceptions.py
│   └── utils.py
|── Dockerfile
└── requirements.txt

You will also need to rework the Dockerfile COPY commands from

COPY app.py requirements.txt ./

RUN python3.8 -m pip install -r requirements.txt -t .

to

COPY requirements.txt ./
RUN python3.8 -m pip install -r requirements.txt -t .

COPY app/ ./app/

Via this method, you can keep the CMD command the same CMD ["app.lambda_handler"]
This is what I had to do to get it to work for me.

@AustinGilkison
Thanks for your input, it works perfectly fine for files that exist inside container.
Let say If I want to call the handler file located in EFS file system and its mounted to Lambda function with the mount path "/mnt/xxxfolder" .

I have copied the 'init.py' in all the folder structure defined till handler function, but Its still failing with

[ERROR] TypeError: the 'package' argument is required to perform a relative import for '.mnt.xxxfolder.yyfolder.lambda_handler'
Traceback (most recent call last):
  File "/var/lang/lib/python3.9/importlib/init.py", line 122, in import_module
    raise TypeError(msg.format(name))
    
 Appreciate your comments. Thanks.

And you now change the "Handler" value from lambda_file.lambda_handler to app.lambda_file.lambda_handler

Worked a treat. I also had to stick a bunch of __init__.py, due to deeply nested structure of some of the lambdas.

Thanks so much, this quickly helped me solve my problem!

Thanks .

Thanks a lot!

Thank you!

Thanks a bunch! I spent too much time figuring this out.

Really saved me a lot of time. Thank You!

LEGEND❤️

Thank you so so so much!! I ran into this issue and spent so much time trying to fix it I was losing my mind!! And there's little resources on google that talk about this until I saw this post. Much appreciated!!

The solution is to ensure that the "Handler" value that you configure in AWS Lambda contain at least 2 . periods. To achieve this you need to put your code within a directory in your AWS Lambda code zip file and make that directory a module by adding an empty __init__.py file. The resulting structure looks like this

├── app
│   ├── __init__.py
│   ├── lambda_file.py
│   └── example.py

And you now change the "Handler" value from lambda_file.lambda_handler to app.lambda_file.lambda_handler

just to add a bit more details for rookies like me: after doing this, you should use the module path to import your own code, i.e.

# in example.py
from app.labda_file import *

# in lambda_file.py
from app.example import *

this would make it work on both your local and on AWS lambda.