Python Imports – When to Use Absolute Imports

Python relative imports are no longer strongly discouraged, but using absolute_import is strongly suggested in that case.

Please see this discussion citing Guido himself:

"Isn't this mostly historical? Until the new relative-import syntax was implemented there were various problems with relative imports. The short-term solution was to recommend not using them. The long-term solution was to implement an unambiguous syntax. Now it is time to withdraw the anti-recommendation. Of course, without going overboard -- I still find them an acquired taste; but they have their place."

The OP correctly links the PEP 328 that says:

Several use cases were presented, the most important of which is being able to rearrange the structure of large packages without having to edit sub-packages. In addition, a module inside a package can't easily import itself without relative imports.

Also see almost duplicate question When or why to use relative imports in Python

Of course it still stands as a matter of taste. While it's easier to move code around with relative imports, that might also unexpectedly break things; and renaming the imports is not that difficult.

To force the new behaviour from PEP 328 use:

from __future__ import absolute_import

In this case, implicit relative import will no longer be possible (eg. import localfile will not work anymore, only from . import localfile). For clean and future proof behaviour, using absolute_import is advisable.

An important caveat is that because of PEP 338 and PEP 366, relative imports require the python file to be imported as a module - you cannot execute a file.py that has a relative import or you'll get a ValueError: Attempted relative import in non-package.

This limitation should be taken into account when evaluating the best approach. Guido is against running scripts from a module in any case:

I'm -1 on this and on any other proposed twiddlings of the __main__ machinery. The only use case seems to be running scripts that happen to be living inside a module's directory, which I've always seen as an antipattern. To make me change my mind you'd have to convince me that it isn't.

Exhaustive discussions on the matter can be found on SO; re. Python 3 this is quite comprehensive:

• Relative imports in Python 3

The distinction between absolute and relative that's being drawn here is very similar to the way we talk about absolute and relative file paths or even URLs.

An absolute {import, path, URL} tells you exactly how to get the thing you are after, usually by specifying every part:

import os, sys
from datetime import datetime
from my_package.module import some_function

Relative {imports, paths, URLs} are exactly what they say they are: they're relative to their current location. That is, if the directory structure changes or the file moves, these may break (because they no longer mean the same thing).

from .module_in_same_dir import some_function
from ..module_in_parent_dir import other_function

Hence, absolute imports are preferred for code that will be shared.

I was asked in comments to provide an example of how from __future__ import absolute_import ties into this, and how it is meant to be used. In trying to formulate this example, I realized I couldn't quite explain its behavior either, so I asked a new question. This answer gives a code sample showing a correctly working implementation of from __future__ import absolute_import, where it actually resolves an ambiguity.

The accepted answer goes into more detail about why this works the way it does, including a discussion of the confusing wording of the Python 2.5 changelog. Essentially, the scope of this directive (and by extension the distinction between absolute and relative imports in Python) is very, very narrow. If you find yourself needing these distinctions to make your code work, you're probably better off renaming your local module if at all possible.