Why Python’s Import System Is Fundamentally Flawed—and How to Survive

We discuss Python’s import mechanism, a feature you use daily until it breaks and makes you question your career choices.

The Circular Import Debacle

Typical circular import example:

# File: user.py
from post import Post

class User:
    def __init__(self, name):
        self.name = name
        self.posts = []

    def create_post(self, content):
        return Post(content, self)

# File: post.py
from user import User

class Post:
    def __init__(self, content, author: User):
        self.content = content
        self.author = author

Running this yields:

ImportError: cannot import name 'Post' from partially initialized module 'post'

The Python community often dismisses this as a design flaw, claiming the code is poorly structured, while other modern languages handle such cases gracefully.

Absolute vs. Relative Import Confusion

Two import styles:

# sometimes works
from mypackage.subpackage import MyClass

# sometimes works too
from .subpackage import MyClass

# works in some contexts but not always
from . import subpackage

Behavior depends on whether the file is run as a script or imported as a module, and on the current working directory. When run as a script, __package__ is None, causing relative imports to fail.

sys.path Pitfalls

Python searches modules using sys.path, a list of directories. The first entry is the current directory, so the same import may succeed or fail depending on where you run the script.

import sys
print(sys.path)
# ['', '/usr/lib/python39.zip', '/usr/lib/python3.9', ...]

You can hack the path at runtime:

import sys
sys.path.insert(0, '/path/to/my/modules')
import my_module

Dependency on Directory Structure

When refactoring, moving a file requires updating every import that referenced the old location.

project/
    __init__.py
    models/
        __init__.py
        user.py     # from ..utils import helper
    utils/
        __init__.py
        helper.py
    main.py

After restructuring:

project/
    __init__.py
    core/
        models/
            __init__.py
            user.py    # import now broken
        utils/
            __init__.py
            helper.py
    main.py

Performance: Import Overhead

Importing is slow and synchronous: Python searches sys.path, loads and compiles the file, executes top‑level code, then caches the result. The Global Interpreter Lock (GIL) prevents parallel imports, leading to long startup times for large applications.

# seemingly harmless line that may import hundreds of modules
import some_heavy_library

The Magic __init__.py File

Packages require an __init__.py file, even if empty, to be recognized. This ritualistic requirement dates back to 1999 and has not aged well.

mypackage/
    __init__.py      # must exist, even if empty
    module1.py
    subpackage/
        __init__.py  # also required
        module2.py

How Other Languages Do It Better

ES6 Modules

// clear explicit exports
export { myFunction, MyClass };

// clear explicit imports
import { myFunction, MyClass } from './mymodule.js';

// circular dependencies? no problem.

Go

// simple package imports
import "fmt"
import "myproject/mypackage"

// no circular import issues
// no relative/absolute import confusion
// no magic files needed

Rust

// explicit module declarations
use std::collections::HashMap;
use crate::mymodule::MyStruct;

// compiler catches import errors
// runtime surprises are avoided

These languages provide clear, file‑system‑independent imports, compile‑time checks, and graceful handling of circular dependencies—areas where Python’s system falls short.

Community Stockholm Syndrome

The community often blames the user: “you’re using it wrong,” “it’s not Pythonic,” or “proper code organization fixes it,” reinforcing acceptance of a broken design.

Real‑World Consequences

Onboarding friction: New developers waste hours fixing imports instead of learning the language.

Refactoring resistance: Fragile imports discourage structural changes.

Testing complexity: Circular imports make unit tests harder.

Performance overhead: Slow startup degrades user experience.

Deployment issues: Import paths that work locally may break in production due to different directory layouts.

How to Improve

Explicit exports: Modules should declare what they export.

Path‑independent imports: Moving files shouldn’t break import statements.

Compile‑time checks: Import errors should be caught before runtime.

Better circular‑dependency handling: Languages should allow reasonable cycles.

Performance optimizations: Imports should be fast and possibly parallelizable.

Simpler syntax: No need for magical __init__.py files or confusing relative/absolute syntax.

Survival Strategies Until Python Fixes It

1. Stick to absolute imports

# good
from myproject.models.user import User

# avoid
from .user import User

2. Use lazy imports when necessary

def get_user_posts(user_id):
    from myproject.models.post import Post  # import inside function
    return Post.objects.filter(user_id=user_id)

3. Leverage TYPE_CHECKING for type hints

from typing import TYPE_CHECKING

if TYPE_CHECKING:
    from myproject.models.post import Post

class User:
    def get_posts(self) -> list['Post']:
        # forward reference
        pass

4. Install the project as a package

pip install -e .

This makes imports more reliable but adds setup complexity.

Conclusion

Python’s import system is a relic from an era of small scripts, lagging behind modern language evolution. We should not accept opaque rules around __package__ and sys.path, nor redesign good code just to satisfy a flawed importer.