Python beyond top level package error in relative import Solution

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:

import app.program

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:

python3 app.py

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.

The Solution

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:

import cake.app.program

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:

"Career Karma entered my life when I needed it most and quickly helped me match with a bootcamp. Two months after graduating, I found my dream job that aligned with my values and goals in life!"

Venus, Software Engineer at Rockbot

Find Your Bootcamp Match

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.

Conclusion

The 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!