Enforcing Modular Boundaries with Import Linter in Python

Modularity decay in growing Python codebases

In dynamic, interpreted languages like Python, the runtime executes imports at startup. Python has no language-enforced visibility layers11 such as Java’s package-private visibility, C++‘s namespace restrictions, or C#‘s internal keyword , relying entirely on developer discipline and convention. If a module resides on the Python path, any other module can import it.

This means that modular boundaries exist only as conceptual agreements between developers. A single import statement in the wrong module can silently break architectural contracts, and no built-in tooling raises an alarm. The problem compounds as teams grow. New contributors unfamiliar with the intended layer separation introduce imports that shouldn’t be allowed.

As codebases grow, several modularity decay patterns emerge.

Developers often introduce shortcut imports when sibling layers bypass defined ports and import concrete adapters directly. The shortcut circumvents the port-adapter contract, making it difficult to swap implementations (e.g., swapping a database client) and causing compile-time or testing-time dependencies to leak across boundaries. In practice, shortcut coupling results in test suites requiring fully configured database connections just to verify simple application behavior.

Circular dependencies emerge when modules across different layers import each other, creating execution cycles during package initialization. Because Python executes import statements dynamically at runtime, these cycles cause ImportError crashes at application startup. Operationally, circular imports force developers to use localized or late imports, obscure the dependency graph, and make it hard to isolate a single component in a unit test.

Accidental coupling happens when the core domain layer imports external libraries22 like psycopg2, redis, or boto3 or low-level implementation details, often because an adapter has leaked into a domain model. When the domain layer directly couples to third-party dependencies, any upgrade or modification to those libraries forces changes inside the core business logic. This tight coupling defeats the purpose of clean architecture, which dictates that business logic must remain stable and unaffected by infrastructure changes.

A static analysis tool that treats architectural modular boundaries as first-class constraints solves this problem. The linter fails the build immediately if the source code violates a contract.

Enforcing modular boundaries with Import Linter

To prevent modularity decay, establish strict rules for dependency direction and package layout. As discussed in the previous article on Hexagonal Architecture,33 Ports and Adapters the core domain and application layers reside at the center. Outward adapters depend on inward ports.

Inbound driving flows occur when external drivers44 e.g., HTTP controllers, CLI commands, AMQP event consumers call the Application layer through driving ports. These drivers reside in the adapters module.

Outbound driven flows occur when the core application calls external services55 e.g., database engines, payment APIs, message brokers through driven ports, and the concrete implementations live in the same adapters module.

The central business domain remains isolated and maintains zero outbound dependencies.

# shop/application/use_cases.py: BEFORE (leaky)
from shop.adapters.db_adapter import (
    PostgresOrderRepository,
)

class OrderProcessor:
    def __init__(self) -> None:
        self._repo = PostgresOrderRepository(
            "postgresql://localhost/shop"
        )

$ lint-imports
=============
Import Linter
=============

----- Forbidden import -----

shop.application.use_cases
  -> shop.adapters.db_adapter

Contracts: 1 broken

# shop/application/use_cases.py: AFTER (clean)
from shop.ports.repositories import (
    OrderRepositoryPort,
)

class OrderProcessor:
    def __init__(
        self, repo: OrderRepositoryPort
    ) -> None:
        self._repo = repo

uv add --dev import-linter

[tool.importlinter]
root_package = "shop"
exclude_type_checking_imports = true

# Layers contract: enforce a strict top-down dependency hierarchy.
# exhaustiveness = true means adding a new top-level module under shop/
# (one not in the layers list) is itself a contract violation (preventing
# silent boundary creation in new code).
[[tool.importlinter.contracts]]
name = "Hexagonal layer hierarchy"
type = "layers"
layers = [
    "adapters",
    "application",
    "ports",
    "domain",
]
exhaustiveness = true

[[tool.importlinter.contracts]]
name = "Domain layer isolation"
type = "forbidden"
source_modules = ["shop.domain"]
forbidden_modules = [
    "shop.ports",
    "shop.application",
    "shop.adapters",
]
as_packages = false
unmatched_ignore_imports_alerting = "warn"

[[tool.importlinter.contracts]]
name = "Ports depend only on domain"
type = "forbidden"
source_modules = ["shop.ports"]
forbidden_modules = [
    "shop.application",
    "shop.adapters",
]
as_packages = false

[[tool.importlinter.contracts]]
name = "Adapter sibling independence"
type = "independence"
modules = [
    "shop.adapters.db_adapter",
    "shop.adapters.stripe_adapter",
]

[[tool.importlinter.contracts]]
name = "Framework public API"
type = "protected"
include_modules = [
    "shop.framework.api",
]
expose_modules = [
    "shop.domain",
]

[[tool.importlinter.contracts]]
name = "No cycles between plugins"
type = "acyclic_siblings"
modules = [
    "shop.plugins.auth",
    "shop.plugins.billing",
    "shop.plugins.notifications",
]

[tool.importlinter]
root_package = ["shop", "shop_admin", "shop_worker"]

lint-imports

Managing test suites and type hint cycles

Integrating architectural contracts into real-world codebases introduces practical challenges around unit testing exceptions and cyclic type annotations.

[[tool.importlinter.contracts]]
name = "Domain layer isolation"
type = "forbidden"
source_modules = ["shop.domain"]
forbidden_modules = ["shop.adapters"]
ignore_imports = [
    "shop.domain.tests.test_models -> shop.adapters.db_adapter",
]

from typing import TYPE_CHECKING, Protocol

if TYPE_CHECKING:
    from shop.domain.models import Order


class OrderProcessorPort(Protocol):
    async def process(
        self, order: Order
    ) -> bool: ...

Benchmarking Import Linter on real codebases

I benchmarked lint-imports against three open source projects that already use it in production, with their real contract configurations in place, to see how this tool performs in different situations.

A clean venv keeps the import graph from picking up unrelated site-packages:

uv venv .bench-venv
source .bench-venv/bin/activate
uv pip install import-linter

For a project that already declares import-linter in pyproject.toml, install it in editable mode so the linter picks up the real root_package and contracts:

git clone --depth=1 https://github.com/janbjorge/pgqueuer.git
cd pgqueuer
uv pip install -e .[dev]

I used hyperfine to time the linter because it’s written in rust it runs warmups and reports standard deviation:

hyperfine --warmup 1 --runs 5 'lint-imports'

Here are the benchmarks on an Apple M1 Pro:

The PostHog figure is the most representative for “large codebase” expectations. Even with 6k files and 10k import edges, the linter finishes in under half a second, and the entire graph fits in 65 MB of RAM.

Key practices for enforcing modular boundaries

• Import Linter automates boundary enforcement by treating architectural rules as build errors.
• Keeping test suites external to the source package simplifies contracts and eliminates the need for ignore_imports whitelists.
• Tracking the ignore_imports count over time surfaces architectural debt before boundaries erode.
• Resolving type hint cycles with TYPE_CHECKING guards keeps the linter happy without introducing runtime overhead.

What about dynamic imports?

Import Linter handles static import analysis comprehensively, but it can’t detect importlib.import_module calls or inline imports hidden inside function bodies. In most cases, static contracts are sufficient. However, there are some cases where dynamic imports are useful:

• Optional dependencies with hard fallbacks. A driver package that supports multiple backends keeps the imports inside the dialect functions so the package can be imported without the optional library installed.
• Plugin discovery and entry points. Loading a list of installed plugins from a package’s entry_points group, or from a config file that names a module path, is dynamic by construction: the project does not know at build time which plugins are installed.
• Circular-import workarounds that have no static equivalent. Sometimes, a deferred import inside a function is the only way to break the cycle. The TYPE_CHECKING import is preferred when it works; the inline import is the fallback when it does not.
• Heavy or rarely-used modules. Importing a large third-party library (a pandas ETL helper, a matplotlib report generator) at the top of a module pulls it into every process that touches the module, including CLI tools and web request handlers that never need it. Deferring the import until the function that actually uses it keeps the cold-start path cheap and the dependency graph clean.

In the core domain layer, none of these use cases apply: they all belong to the infrastructure layer.

If you need to detect dynamic imports in the domain layer, then an AST scanning tool can be the way to go, especially in codebases where dynamic import bypasses have been observed in code reviews or where the contributor base is large enough that convention alone is insufficient.

References and additional resources

• Import Linter Documentation for detailed contract specifications.
• Python ast module documentation to understand abstract syntax trees.