How to import local modules with Python
Importing files for local development in Python can be cumbersome. In this article, I summarize some possibilities for the Python developer.
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.
Script: Python file meant to be run with the command line interface.
Module: Python file meant to be imported.
Package: directory containing modules/packages.
Consider the following project structure:
project ├── e.py └── src ├── a │ └── b.py └── c └── d.py
Say that in
b.py, we want to use
Let’s try to run
python from the
~/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
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.
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 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
__package__ variable (which is
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:
__package__variable is filled, enabling relative imports (see PEP 366)
- the directory from which Python was run (here: ~/Documents/code/project) is added to
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
- add the “Command Variable” extension to Visual Code
- set the following Python launch configuration in your settings.json:
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
- Topics on stackoverflow: https://stackoverflow.com/questions/22241420/execution-of-python-code-with-m-option-or-not, https://stackoverflow.com/questions/16981921/relative-imports-in-python-3
- Import system of Python: https://docs.python.org/3/reference/import.html, https://docs.python.org/3/library/runpy.html
- pip install: https://pip.pypa.io/en/stable/cli/pip_install/