How to Import from the Parent Directory in Python

Python cannot import from a parent directory by default, because only the folder of the script you ran is on the import path. There are four ways round it. The quick one is sys.path manipulation, the correct one is an editable install, and the one most tutorials recommend — running with python -m from the project root — is usually all you actually need.

The situation#

project/
    config.py
    scripts/
        report.py       <- wants to import config

python scripts/report.py

ModuleNotFoundError: No module named 'config'

Running a file puts that file’s folder first on sys.path. So project/scripts/ is searched and project/ is not. Confirm it for yourself:

import sys
print(sys.path[0])

Method 1: run from the root with -m (usually the answer)#

project/
    __init__.py
    config.py
    scripts/
        __init__.py
        report.py

# scripts/report.py
from project.config import SETTINGS

cd /path/to/parent-of-project
python -m project.scripts.report

The -m flag runs a module rather than a file, and it puts the current directory on the path instead of the file’s folder. Absolute imports then resolve.

This requires no configuration and no path hacking. If you can arrange to run from the project root, stop here.

Method 2: an editable install (correct for anything lasting)#

Add a minimal pyproject.toml at the project root:

[project]
name = "myproject"
version = "0.1.0"

[build-system]
requires = ["setuptools>=61"]
build-backend = "setuptools.build_meta"

python -m pip install -e .

Now your package is importable from anywhere, in any script, in tests, in a notebook — and the -e means it points at your source folder, so edits take effect immediately with no reinstall.

from myproject.config import SETTINGS     # works from any directory

This is what real projects do. It takes five minutes once and then you never think about import paths again.

Method 3: sys.path manipulation (last resort)#

import sys
from pathlib import Path

sys.path.insert(0, str(Path(__file__).resolve().parent.parent))

from config import SETTINGS

It works. The reasons to avoid it:

• It must appear before the import, which linters flag and formatters may move.
• It ties the file to its position in the folder tree.
• Every script that needs it has to repeat it.
• It hides a structural problem rather than fixing it.

Two details if you do use it. Path(__file__).resolve() rather than a relative path, so it works regardless of the working directory. And insert(0, ...) rather than append, so your folder is searched first — though that also means your module can shadow a standard library one, so name things carefully.

Method 4: relative imports#

# scripts/report.py
from ..config import SETTINGS

Valid only when the file is run as part of a package. Run it directly and you get:

ImportError: attempted relative import with no known parent package

So this is really method 1 in different clothing — it still requires python -m. Prefer absolute imports; they say where the code lives and survive files being moved.

Tests#

Pytest handles this better than plain Python. With this layout:

project/
    pyproject.toml
    myproject/
        __init__.py
        config.py
    tests/
        test_config.py

python -m pytest

Running pytest with python -m puts the current directory on the path, so from myproject.config import SETTINGS works in the tests without any configuration. This is why python -m pytest is recommended over the bare pytest command.

An empty conftest.py at the project root also does the job, because pytest adds the folder containing it to the path.

Notebooks#

import sys
from pathlib import Path

sys.path.insert(0, str(Path.cwd().parent))

Notebooks are the one place where path manipulation is genuinely reasonable — they are interactive and not part of a package. Even so, an editable install is tidier if the notebook is part of a real project.

Which to use#

Where to go next#

• Python function import guide — the import rules in full.
• Building a complete Python project — the structure this assumes.
• Python virtual environments — where the editable install should go.