Quentin Fortier

Quentin Fortier

Teacher in computer science

How to import local modules with Python

3 minute read

Importing files for local development in Python can be cumbersome. In this article, I summarize some possibilities for the Python developer.

https://xkcd.com

TL; DR: I recommend using python -m to run a Python file, in order to add the current working directory to sys.path and enable relative imports.

Definitions

Script: Python file meant to be run with the command line interface.

Module: Python file meant to be imported.

Package: directory containing modules/packages.

Example

Consider the following project structure:

project
├── e.py
└── src
    ├── a
    │   └── b.py
    └── c
        └── d.py

Say that in b.py, we want to use d.py:

Let’s try to run python from the project directory:

~/Documents/code/project$ python3 src/a/b.py

Traceback (most recent call last):
  File "/home/qfortier/Documents/code/project/src/a/b.py", line 4, in <module>
    import src.c.d
ModuleNotFoundError: No module named 'src'

What happened? When Python tries to import a module, it looks at the paths in sys.path (including, but not limited to, PYTHONPATH): 

~/Documents/code/project$ python3 src/a/b.py

['/home/qfortier/Documents/code/project/src/a', '/usr/lib/python38.zip', '/usr/lib/python3.8',  ...]

We see that the directory containing b.py (the script we run) is added to sys.path. But d.py is not reachable from the directory a, hence the above error.

1st solution: add root to sys.path

We can add the path to the root of the project: 

~/Documents/code/project$ python3 src/a/b.py

['/home/qfortier/Documents/code/project/src/a',  ..., '.']

The added path ‘.’ refers to the current working directory (from which Python was run) ~/Documents/code/project. Python can indeed import c.d from this directory.

This solution works regardless of the directory used to run Python:

~/Documents/code/project$ cd ../..
~/Documents$ python3 code/project/src/a/b.py

['/home/qfortier/Documents/code/project/src/a',  ..., 'code/project']

It should also work on a different computer, with a different filesystem or OS, thanks to Pathlib.
However, modifying sys.path at the beginning of every file is tedious and hard to maintain. A better solution would be to use a context.py file modifying sys.pathand imported by every other file, but this is still unsatisfying.
Another possibility is to add the root directory to PYTHONPATH (before running the script). This is done automatically by poetry, for example.

Relative import

Relative imports were introduced in PEP 328 as a way to improve maintainability and avoid very long import statements. They must use the from .module import something syntax: 

~/Documents/code/project$ python3 src/a/b.py
Traceback (most recent call last):
  File "src/a/b.py", line 4, in <module>
    from ..c import d
ImportError: attempted relative import with no known parent package

This is not working! Indeed, relative imports rely on the __name__ or __package__ variable (which is __main__ and None for a script, respectively).
If we import b.py from another file, everything is fine:

~/Documents/code/project$ python3 e.py

Name: src.a.b
Package: src.a

Note: to go up several directories in relative imports, use additional dots: from ...c import d would go 2 directories up, for example.

2nd solution: run as a module

It is unfortunate that scripts can’t use relative imports. PEP 338 overcomes this limitation by adding the -m option. With this option, a script is run as if it was imported as a module. 

~/Documents/code/project$ python3 -m src.a.b  # note that we use . and not / here

Name: __main__
Package: src.a

python3 -m src.a.b acts as if a Python file containing import src.a.b was run in the current directory, with two notable differences:

  • the __package__ variable is filled, enabling relative imports (see PEP 366)
  • the directory from which Python was run (here: ~/Documents/code/project) is added to sys.path

Since I don’t see any drawback to this, I recommend always using python3 -m to run a script.

Run as a module on Visual Code

The default launch configuration in Visual Code runs Python files as scripts (without -m). This GitHub issue explains how to add -m automatically:

3rd solution : modify PYTHONPATH

With Visual Code, you can automatically add the root directory to your project by adding a line to the launch configuration :

Alternatively, you can add a .env file in the root directory :

4rd solution (outdated): install in editable mode

pip install -e ... installs a package in editable mode, which can then be imported anywhere on the computer. In practice, this is essentially a symbolic link to your package. Therefore, any modification of the package is reflected on the code importing it. It requires a setup.py at the root of your package.

Note: according to PEP 517, this is no longer recommended: Python packages should rely on a toml file (see Poetry) and not on setup.py anymore.

References

Comments

You May Also Enjoy