Edit - Stack Overflow

You are not logged in. Your edit will be placed in a queue until it is peer reviewed.

We welcome edits that make the post easier to understand and more valuable for readers. Because community members review edits, please try to make the post substantially better than how you found it, for example, by fixing grammar or adding additional resources and hyperlinks.

Required fields*

Rev

Required fields*

Relative imports for the billionth time

I've been here:

and plenty of URLs that I did not copy, some on SO, some on other sites, back when I thought I'd have the solution quickly.

The forever-recurring question is this: how do I solve this "Attempted relative import in non-package" message?

ImportError: attempted relative import with no known parent package

I built an exact replica of the package on pep-0328:

package/
 __init__.py
 subpackage1/
 __init__.py
 moduleX.py
 moduleY.py
 subpackage2/
 __init__.py
 moduleZ.py
 moduleA.py

The imports were done from the console.

I did make functions named spam and eggs in their appropriate modules. Naturally, it didn't work. The answer is apparently in the 4th URL I listed, but it's all alumni to me. There was this response on one of the URLs I visited:

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.

The above response looks promising, but it's all hieroglyphs to me. How do I make Python not return to me "Attempted relative import in non-package"? It has an answer that involves -m, supposedly.

Why does Python give that error message? What does by "non-package" mean? Why and how do you define a 'package'?

Answer*

**Script vs. Module**

Here's an explanation. The short version is that there is a big difference between directly running a Python file, and importing that file from somewhere else. **Just knowing what directory a file is in does not determine what package Python thinks it is in.** That depends, additionally, on how you load the file into Python (by running or by importing).

There are two ways to load a Python file: as the top-level script, or as a 
module. A file is loaded as the top-level script if you execute it directly, for instance by typing `python myfile.py` on the command line. It is loaded as a module when an `import` statement is encountered inside some other file. There can only be one top-level script at a time; the top-level script is the Python file you ran to start things off.

**Naming**

When a file is loaded, it is given a name (which is stored in its `__name__` attribute). If it was loaded as the top-level script, its name is `__main__`. If it was loaded as a module, its name is the filename, preceded by the names of any packages/subpackages of which it is a part, separated by dots.

So for instance in your example:

 package/
 __init__.py
 subpackage1/
 __init__.py
 moduleX.py
 moduleA.py

 if you imported `moduleX` (note: *imported*, not directly executed), its name would be `package.subpackage1.moduleX`. If you imported `moduleA`, its name would be `package.moduleA`. However, if you *directly run* `moduleX` from the command line, its name will instead be `__main__`, and if you directly run `moduleA` from the command line, its name will be `__main__`. When a module is run as the top-level script, it loses its normal name and its name is instead `__main__`.

**Accessing a module NOT through its containing package**

There is an additional wrinkle: the module's name depends on whether it was imported "directly" from the directory it is in or imported via a package. This only makes a difference if you run Python in a directory, and try to import a file in that same directory (or a subdirectory of it). For instance, if you start the Python interpreter in the directory `package/subpackage1` and then do `import moduleX`, the name of `moduleX` will just be `moduleX`, and not `package.subpackage1.moduleX`. This is because Python adds the current directory to its search path when the interpreter is entered interactively; if it finds the to-be-imported module in the current directory, it will not know that that directory is part of a package, and the package information will not become part of the module's name.

A special case is if you run the interpreter interactively (e.g., just type `python` and start entering Python code on the fly). In this case, the name of that interactive session is `__main__`.

Now here is the crucial thing for your error message: **if a module's name has no dots, it is not considered to be part of a package**. It doesn't matter where the file actually is on disk. All that matters is what its name is, and its name depends on how you loaded it.

Now look at the quote you included in your question:

>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.

**Relative imports...**

Relative imports use the module's *name* to determine where it is in a package. When you use a relative import like `from .. import foo`, the dots indicate to step up some number of levels in the package hierarchy. For instance, if your current module's name is `package.subpackage1.moduleX`, then `..moduleA` would mean `package.moduleA`. For a `from .. import` to work, the module's name must have at least as many dots as there are in the `import` statement.

**... are only relative in a package**

However, if your module's name is `__main__`, it is not considered to be in a package. Its name has no dots, and therefore you cannot use `from .. import` statements inside it. If you try to do so, you will get the "relative-import in non-package" error.

**Scripts can't import relative**

What you probably did is you tried to run `moduleX` or the like from the command line. When you did this, its name was set to `__main__`, which means that relative imports within it will fail, because its name does not reveal that it is in a package. Note that this will also happen if you run Python from the same directory where a module is, and then try to import that module, because, as described above, Python will find the module in the current directory "too early" without realizing it is part of a package.

Also remember that when you run the interactive interpreter, the "name" of that interactive session is always `__main__`. Thus **you cannot do relative imports directly from an interactive session**. Relative imports are only for use within module files.

**Two solutions:**

 1. If you really do want to run `moduleX` directly, but you still want it to be considered part of a package, you can do `python -m package.subpackage1.moduleX`. The `-m` tells Python to load it as a module, not as the top-level script.

 1. Or perhaps you don't actually want to *run* `moduleX`, you just want to run some other script, say `myfile.py`, that *uses* functions inside `moduleX`. If that is the case, put `myfile.py` *somewhere else* &ndash; *not* inside the `package` directory &ndash; and run it. If inside `myfile.py` you do things like `from package.moduleA import spam`, it will work fine.

**Notes**

 - For either of these solutions, the package directory (`package` in your example) must be accessible from the Python module search path (`sys.path`). If it is not, you will not be able to use anything in the package reliably at all.

 - Since Python 2.6, the module's "name" for package-resolution purposes is determined not just by its `__name__` attributes but also by the `__package__` attribute. That's why I'm avoiding using the explicit symbol `__name__` to refer to the module's "name". Since Python 2.6 a module's "name" is effectively `__package__ + '.' + __name__`, or just `__name__` if `__package__` is `None`.)

Draft saved

Draft discarded

Edit Summary*

Cancel

18

See python.org/dev/peps/pep-0366 -- "Note that this boilerplate is sufficient only if the top level package is already accessible via sys.path . Additional code that manipulates sys.path would be needed in order for direct execution to work without the top level package already being importable." -- this is the most disturbing bit to me since this "additional code" is actually quite long and can't be stored elsewhere in package to run easily.

Michael Scott Asato Cuthbert
– Michael Scott Asato Cuthbert

2015年08月29日 08:04:58 +00:00
Commented Aug 29, 2015 at 8:04
68

I keep coming back to this post despite being a Python veteran. The main message for me is: Either fiddle around with sys.path and __package__ (which is rather ugly, see the other answers) or simply create a "main script" main.py in the root directory of your project and put all modules to be imported in subdirectories. main.py can then access all modules directly through their package names (= the names of the respective folders they're in).

balu
– balu

2017年03月27日 12:29:14 +00:00
Commented Mar 27, 2017 at 12:29
65

This answer is currently off on a few important details regarding __name__ and sys.path. Specifically, with python -m pkg.mod, __name__ is set to __main__, not pkg.mod; relative imports are resolved using __package__ rather than __name__ in this case. Also, Python adds the script's directory rather than the current directory to sys.path when running python path/to/script.py; it adds the current directory to sys.path when running most other ways, including python -m pkg.mod.

user2357112
– user2357112

2018年10月05日 19:22:29 +00:00
Commented Oct 5, 2018 at 19:22
23

Finally understand after hours of reading... Worth noting that code under if __name__ == '__main__' will still run when using -m. See the comment from @user2357112

adamF
– adamF

2019年01月22日 20:18:11 +00:00
Commented Jan 22, 2019 at 20:18
75

A feature is broken if you have to spend an hour reading this, and if you have to google it time after time, and still only the gurus get it. The python designers dropped the ball on this one, and it should just work, the first time, like any other programming language.

C.J.
– C.J.

2022年01月07日 16:10:43 +00:00
Commented Jan 7, 2022 at 16:10

| Show 24 more comments

How to Edit

Correct minor typos or mistakes
Clarify meaning without changing it
Add related resources or links
Always respect the author’s intent
Don’t use edits to reply to the author

How to Format

create code fences with backticks ` or tildes ~
```
like so
```
add language identifier to highlight code
```python
def function(foo):
print(foo)
```
put returns between paragraphs
for linebreak add 2 spaces at end
_italic_ or **bold**
indent code by 4 spaces
backtick escapes `like _so_`
quote by placing > at start of line
to make links (use https whenever possible)

<https://example.com>

[example](https://example.com)

<a href="https://example.com">example</a>

formatting help »
answering help »

How to Tag

A tag is a keyword or label that categorizes your question with other, similar questions. Choose one or more (up to 5) tags that will help answerers to find and interpret your question.

complete the sentence: my question is about...
use tags that describe things or concepts that are essential, not incidental to your question
favor using existing popular tags
read the descriptions that appear below the tag

If your question is primarily about a topic for which you can't find a tag:

combine multiple words into single-words with hyphens (e.g. python-3.x), up to a maximum of 35 characters
creating new tags is a privilege; if you can't yet create a tag you need, then post this question without it, then ask the community to create it for you

popular tags »

lang-py

CollectivesTM on Stack Overflow

Relative imports for the billionth time

Answer*