Five Ways to Solve Persistent Python Import Errors Across Directories

Python import system basics

When a module is imported, Python searches the directories listed in sys.path. By default sys.path contains the script’s directory, directories from the PYTHONPATH environment variable, the standard library, and site‑packages. All cross‑directory import techniques modify sys.path or rely on package structure.

Method 1 – modify sys.path at runtime

Append or insert a directory:

import sys
import os
# Append to end
sys.path.append('/path/to/your/module/directory')
# Insert at beginning
sys.path.insert(0, '/path/to/your/module/directory')
import your_module

Dynamic version using the current file’s parent directory:

import sys, os
current_dir = os.path.dirname(os.path.abspath(__file__))
parent_dir = os.path.dirname(current_dir)
sys.path.insert(0, parent_dir)
import target_module

Method 2 – set PYTHONPATH environment variable

Linux/macOS:

export PYTHONPATH="/path/to/your/module/directory:$PYTHONPATH"
# add to ~/.bashrc or ~/.zshrc for persistence

Windows:

set PYTHONPATH="path\to\your\module\directory;%PYTHONPATH%"

Method 3 – relative imports inside a package

Given a package layout:

project/
├── __init__.py
├── app1/
│   ├── __init__.py
│   ├── models.py
│   └── views.py
└── app2/
    ├── __init__.py
    └── models.py

Imports from app1/views.py:

# absolute imports
from project.app1 import models
from project.app2.models import SomeClass

# explicit relative imports
from . import models
from ..app2.models import SomeClass

Import types:

Same‑level import : from . import module – imports a module in the same package.

Parent‑level import : from .. import module – imports from the parent package.

Sub‑package import : from .subpackage import module – imports from a sub‑package.

Method 4 – create a full package structure

Example:

my_package/
├── __init__.py
├── module1.py
├── module2.py
├── subpackage/
│   ├── __init__.py
│   └── module3.py
└── script.py

Module contents:

# module1.py
def greet():
    return "Hello from module1!"

# module2.py
def farewell():
    return "Goodbye from module2!"

# module3.py
def welcome():
    return "Welcome from module3!"

# __init__.py (expose public API)
from .module1 import greet
from .module2 import farewell

Usage in script.py:

from my_package import greet, farewell
from my_package.subpackage.module3 import welcome

if __name__ == "__main__":
    print(greet())
    print(farewell())
    print(welcome())

Method 5 – dynamic import with importlib

Utility function:

import importlib

def import_and_execute(module_name, function_name):
    try:
        module = importlib.import_module(module_name)
        func = getattr(module, function_name)
        print(func())
    except ModuleNotFoundError:
        print(f"Module '{module_name}' not found.")
    except AttributeError:
        print(f"Function '{function_name}' not found in module '{module_name}'.")

Typical scenarios: plugin systems, configuration‑driven loading, debugging tools.

Best practices and common pitfalls

Import order convention

# 1. Standard library
import os
import sys
from typing import Dict, List

# 2. Third‑party libraries
import requests
import numpy as np

# 3. Local application imports
from my_package import utils
from . import local_module

Avoid circular imports

When two modules import each other, refactor shared code, move imports inside functions, or use importlib to break the cycle.

Handle import errors gracefully

try:
    import expensive_module
except ImportError:
    expensive_module = None

def feature():
    if expensive_module is None:
        print("Feature not available: expensive_module not installed")
        return
    expensive_module.do_something()

Security considerations (Python 3.15+)

Use the -P flag or the PYTHONSAFEPATH environment variable to prevent unsafe paths from being added to sys.path.

Practical case – refactoring project structure

Original layout:

project/
├── utils.py
├── models.py
├── api/
│   └── handler.py
└── db/
    └── connector.py

Target layout with a dedicated core package:

project/
├── __init__.py
├── core/
│   ├── __init__.py
│   ├── utils.py
│   └── models.py
├── api/
│   ├── __init__.py
│   └── handler.py
└── db/
    ├── __init__.py
    └── connector.py

Before refactor, api/handler.py used:

import sys
sys.path.append('..')
from utils import some_function
from db.connector import connect

After refactor, it can use relative imports:

from ..core.utils import some_function
from ..db.connector import connect