Attempted relative import beyond top-level package in Python, is an error that occurs when you do a relative import for a file that is not part of a package.
In this article I’m going to try to present the solution that worked for me and also present some alternative solutions that worked for other developers.
Explaining The Error : Attempted relative import beyond top-level package in Python
I first got this error running my code in Python 3, after a lot of research, I realised that a lot of people encountered the same error. The error is caused when we try to execute a relative import.
The confusing thing is that when we are in the parent folder or directory of package and we run the code bellow, everything is fine.
This is the error we get
#
"ValueError: attempted relative import beyond top-level package"
#
Solution 1 : use append(“.”) with one dot
First of all, I want to make it clear and say that the success of these solutions is not guaranteed, This is by far one of the worst errors i have seen in Python.
This is the solution that ended up working for me, if it does not work for you, checkout the other solutions bellow.
Let’s say we have the following folder structure :
#
packageA/
subpackageA/
moduleA.py
packageB/
subpackageB/
moduleB.py
#
Let us say that I want to import from moduleA into moduleB. The solution that worked for me is the code bellow:
#
import sys
sys.path.append(".")
#
For a lot of people append(“..”) with two dots worked, but not for me, I needed to use only one dot as follows append(“.”)
In this case, the working directory is the root of my project. That’s why it worked.
Solution 2 : run your code as a module
As I said before, this is one of the more confusing errors in Python.
This is what the Python documentation said about relative imports :
Note that relative imports are based on the name of the current module. Since the name of the main module is always “main”, modules intended for use as the main module of a Python application must always use absolute imports.
Relative imports use a module’s name attribute to determine that module’s position in the package hierarchy. If the module’s name does not contain any package information (e.g. it is set to ‘main’) then relative imports are resolved as if the module were a top level module, regardless of where the module is actually located on the file system.
As the documentation said, it is better to avoid relative imports, so how do we solve this problem?
If you want to run your code as a module and not as a top level script, you can run the code bellow in the command line:
#
python -m package.test_A.test
#
Solution 3 : put a root file in the root directory
Another way to solve this error is to put a root file in the root directory which calls the modules and packages, so you have to use the code :
#
from package.A import foo
#
instead of the line of code :
#
import sys
sys.path.append("..")
#
The error is gone and the output becomes :
#
package.A.foo has been imported
Module's name is: package.test_A.test
#
This solution worked for me, I hope it does work for you, if you find our blog valuable consider donating to our Kofi account above and tell us what is the issue we helped you solve.
If none of the above worked, let us explore other possible solutions.
Solution 4 : removing ..
This may sound bizarre to you, but a lot of people solved the issue by just removing .. in test.py. And everything worked well.
Summing-up
If you have to go against the recommendations in the Python documentation and want to use relative imports, just know that the first solution solved the error for me and most other developers who had this issue, I hope you found a solution in our article, keep creating and keep coding, cheers.
If you want to learn more about Python, please check out the Python Documentation : https://docs.python.org/3/