Importing a Python module from another directory works best when the project has a clear package layout. Quick path hacks can unblock a script, but a package structure is easier to run, test, and deploy.
The right method depends on what you are building. A one-off script can temporarily adjust sys.path. A real project should use packages, __init__.py files, absolute imports, relative imports inside packages, or an editable install.
Most import problems come from running code from the wrong working directory or treating a package file like an isolated script. The same file can behave differently depending on whether Python sees it as part of a package.
The official Python modules documentation explains module search behavior. For related topics, see the __init__.py guide and the import from subdirectory guide.
Understand The Project Layout
Start by choosing a layout where imports are predictable. A common pattern keeps application code under one package directory.
# Example layout:
# project/
# app/
# __init__.py
# main.py
# helpers.py
# tests/
# test_helpers.py
from app import helpers
print(helpers.__name__)
The __init__.py file tells Python that app is a package. Modern Python can use namespace packages too, but explicit package files are still clearer for many projects.
A clear layout also helps tests. When tests run from the project root, they can import the package the same way the application does, which avoids special-case test-only paths.
Use Absolute Imports
Absolute imports start from the package name. They are usually the clearest option for application code.
# app/main.py
from app.helpers import format_name
def run():
name = format_name("ada lovelace")
print(name)
run()
Run this from the project root or install the project so Python can find app. Running files from random nested directories is a common source of import failures.
Absolute imports are also easier to search and refactor. When a module moves, the import path tells you exactly which package boundary is involved.
Add A Directory To sys.path Carefully
For a small script, you can add a known directory to sys.path. Use an absolute path built from the current file, not a fragile relative path.
from pathlib import Path
import sys
project_root = Path(__file__).resolve().parents[1]
sys.path.insert(0, str(project_root))
from app.helpers import format_name
print(format_name("grace hopper"))
This is useful for scripts, migration tools, or quick diagnostics. For long-term application code, prefer a package install over repeated path edits.
If you do edit sys.path, insert the project root near the start and keep the change close to the script entry point. Hidden path edits deep inside library modules make debugging much harder.
Use Relative Imports Inside Packages
Inside a package, relative imports can reference nearby modules. They work when the code is executed as part of the package, not as a loose file.
# app/reports/monthly.py
from ..helpers import format_name
def build_title(owner):
return f"Monthly report for {format_name(owner)}"
print(build_title("alan turing"))
If relative imports fail with “attempted relative import with no known parent package”, run the module through the package, such as with python -m app.reports.monthly.
Relative imports are best for internal package relationships. They are not a good way to reach across unrelated project folders.
Run A Module With -m
The -m flag tells Python to run a module by package name. That keeps package imports working.
import subprocess
import sys
command = [sys.executable, "-m", "app.main"]
result = subprocess.run(command, capture_output=True, text=True)
print(result.returncode)
print(result.stdout or result.stderr)
Use this style for package entry points during development. It avoids many problems caused by running a file directly from inside a package folder.
The -m form also matches how many console entry points behave. It encourages you to think in modules and packages instead of filesystem locations.
Inspect The Import Search Path
When imports are confusing, print the search path from the process that fails.
import sys
for index, path in enumerate(sys.path):
print(index, path)
print("module search paths:", len(sys.path))
The first entries explain where Python looks first. If the project root is missing, the package cannot be imported by its top-level name.
Be careful with duplicate names. If a local file has the same name as an installed package, Python may import the local file first and produce confusing errors.
Best Practices
Use path edits only when they are local, explicit, and easy to remove. If several files need the same path edit, that is a sign the project should be packaged properly.
For applications and libraries, create a package, add __init__.py where appropriate, use absolute imports, and run modules from the project root. For tools that must be launched from anywhere, use an editable install or a console script entry point.
The reliable pattern is to design the package layout first, then choose the import style. That avoids brittle directory assumptions and makes the code behave the same way in local scripts, tests, notebooks, and deployment jobs.