You can import packages relatively inside a Python project. If you make a mistake in importing a package relatively, you’ll encounter the
beyond top level package error in relative import error.
In this guide, we’re going to discuss what this error means and why it is raised. We’ll walk through an example of this error to help you learn how to successfully write a relative import statement in your project.
beyond top level package error in relative import
A relative import uses the name of a module to determine its location.
Consider the following relative import:
from .. import app
This will import the “app” Python module from the directory above the folder in which the program with this import statement is written.
Let’s say that this file was called “program.py” and was contained within a folder called “app”. Our main project is called “cake”. Our file structure would look like this:
run.py cake/program/__init__.py cake/program/app.py cake/program/app/__init__.py cake/program/app/program.py
When we run the “program.py” file, Python sees our import statement as:
from program import app
We import from the “program” folder rather than from our current working directory (the folder we are viewing).
This is because “program” is two directories behind the one we are viewing. The __init__.py files tell Python that we are working with our own Python packages. This file is empty in both cases.
Your programs must use this structure, otherwise you’ll encounter an error.
An Example Scenario
We have a project called “cake” which prints out the statement “I like cake!” to the console. This project is going to get more complicated so we are using modules to divide up our code.
The file structure for our project looks like this:
app.py __init__.py printer.py app/__init__.py app/program.py
This code is all in a folder called “cake”. Inside our app.py file, we have a statement that imports our program.py file:
This is a standard import statement. Inside the app/program.py file, we have a relative import statement:
from .. import printer
This code imports the file “printer” from the directory above app/. The directory above app/ is the main directory for our project.
Our printer.py file contains a print statement:
print("I like cake!")
Let’s try to run our program to see if it works. We’re going to run our app.py file because it is the main file for our project:
When we run this file, we see the following message:
Traceback (most recent call last): File "app.py", line 1, in <module> import app.program File "/Users/James/cake/app/program.py", line 1, in <module> from .. import printer ValueError: attempted relative import beyond top-level package
Our program.py file cannot import our “printer” module.
We’re trying to import “printer” into our “app.program” file. This is an issue because “printer” itself is not in a package. Relative imports only work within packages.
To solve this issue, we need to change the directory structure of our project. We need to add our “printer” file and our “app” folder into its own directory so that “printer” is in a package. This will let us reference our “printer” file in the “app” folder.
We can keep our app.py file in its current directory because it will reference our subdirectories.
Let’s move all of our files, excluding app.py, into a new folder:
app.py cake/__init__.py cake/printer.py cake/app/__init__.py cake/app/program.py
All of our project files, aside from app.py, are in a new folder called “cake”. We need to modify our app.py file so that we reference the “cake” module:
This will import the “program” file that is in the cake/app directory.
Now that our printer.py file is in its own package, we should be able to successfully run our project. program.py should be able to access printer.py because both files are in a package.
Let’s run our code and see what happens:
I like cake!
Our program successfully prints the message “I like cake!” to the console. This message is defined in printer.py, as we talked about earlier.
This tells us that our program.py file was able to successfully import the printer.py file. When we imported the file, its contents were executed.
beyond top level package error in relative import error occurs when you use a relative import without the file you are importing being part of a package. To fix this error, make sure that any directories that you import relatively are in their own packages.
You now have the resources you need to solve this common Python error like a pro!