Python Circular Imports: Why They Happen and How to Fix Them

A Python Circular Import Example

Suppose you’re building a Python application to manage orders for an e-commerce store. You’ll build it as a shop package with a main.py script beside it:

shop_project/
│
├── shop/
│   ├── __init__.py
│   ├── order.py
│   └── product.py
│
└── main.py

The empty __init__.py makes shop a regular package. You can run the examples without it, but type checkers need it to work out that shop.order and shop.product belong together.

The package also keeps the error message accurate. From Python 3.13, if the failing module sits in the same folder as the script you run, Python suggests renaming the file instead of reporting the circular import. Keeping the modules inside shop/ avoids that misleading hint.

Every stage of this tutorial is a complete, runnable version of this project. The examples target Python 3.14, and the tutorial points out where older versions behave differently. You can download every stage here:

You have an Order class that tracks the product you order and any additional items you add. Since it works with Product objects, order.py imports the Product class:

from shop.product import Product

SHIPPING_FEE = 4.99

class Order:
    def __init__(self, product: Product, quantity: int) -> None:
        self.product = product
        self.quantity = quantity
        self.extras: list[Product] = []

    def add_shipping(self) -> None:
        self.extras.append(Product("Shipping", SHIPPING_FEE))

    def get_total(self) -> float:
        subtotal = self.product.price * self.quantity
        return subtotal + sum(extra.price for extra in self.extras)

Now look at product.py. Its order() method creates an Order object, and is_in_order() accepts an Order object to check whether the product belongs to that order. So product.py imports the Order class from order.py:

from shop.order import Order

class Product:
    def __init__(self, name: str, price: float) -> None:
        self.name = name
        self.price = price

    def order(self, quantity: int) -> Order:
        return Order(self, quantity)

    def is_in_order(self, order: Order) -> bool:
        return order.product.name == self.name

The main.py script creates a product and places an order for it:

from shop.product import Product

laptop = Product("Laptop", 1000.0)
order = laptop.order(1)
order.add_shipping()

print(order.get_total())

Run it from the project root, and Python stops when it encounters the cycle:

$ python main.py
Traceback (most recent call last):
  File "main.py", line 1, in <module>
    from shop.product import Product
  File "shop/product.py", line 1, in <module>
    from shop.order import Order
  File "shop/order.py", line 1, in <module>
    from shop.product import Product
ImportError: cannot import name 'Product' from partially initialized
⮑ module 'shop.product' (most likely due to a circular import)
⮑ (shop/product.py)

Python stopped while shop.product was still loading, which is why the message calls it a partially initialized module.

Tracing the Import Sequence

To see why Python raises this ImportError, follow the imports in the order Python runs them:

1. main.py runs from shop.product import Product.
2. Python creates the shop.product module, adds it to sys.modules, and starts executing product.py.
3. product.py runs from shop.order import Order. Since order.py hasn’t been executed yet, shop.order isn’t in sys.modules, so Python switches to loading order.py.
4. Python creates the shop.order module, adds it to sys.modules, and starts executing order.py.
5. order.py runs from shop.product import Product.
6. Python finds shop.product in sys.modules, but it’s still being initialized and Product isn’t available yet, so Python raises ImportError.

Step through that same sequence one import at a time:

Notice that Python adds shop.product to sys.modules in the second step, long before it defines any names in that module. The module object exists, so Python won’t start loading it a second time, but the names inside it don’t exist yet.

The problem is that product.py is waiting for order.py, while order.py is trying to import Product from product.py before product.py has finished defining it. Next, you’ll fix it.

Step 1: Remove the Runtime Dependency

The order() method in Product creates an Order object:

def order(self, quantity: int) -> Order:
    return Order(self, quantity)

This method forces product.py to import Order. Delete the method and create the Order directly in main.py instead. This removes the runtime dependency from product.py to order.py.

Here’s shop/product.py without the order() method:

class Product:
    def __init__(self, name: str, price: float) -> None:
        self.name = name
        self.price = price

    def is_in_order(self, order: Order) -> bool:
        return order.product.name == self.name

is_in_order() stays in place. It needs Order only for its type hint, and Step 2 handles that case.

Here’s the updated main.py:

from shop.order import Order
from shop.product import Product

laptop = Product("Laptop", 1000.0)
order = Order(laptop, 2)
order.add_shipping()

print(order.get_total())

You’ve removed the runtime behavior that required Order in product.py. But is_in_order() still names Order in its type annotation, and nothing imports it anymore.

On Python 3.14, the code runs and prints 2004.99 because Python evaluates annotations lazily. That’s only half the story. Run a type checker such as mypy on the same file, and it reports that Order isn’t defined:

$ python -m mypy shop/product.py
shop/product.py:6: error: Name "Order" is not defined  [name-defined]
Found 1 error in 1 file (checked 1 source file)

Your code runs, but your type hints are broken.

So you still need the import, just not at runtime. That’s what TYPE_CHECKING is for, and you need it on every Python version, including 3.14.

Step 2: Guard the Type-Only Import

Python’s TYPE_CHECKING constant lets you import modules for static type checking without performing those imports at runtime. Basically, TYPE_CHECKING is False when Python runs the code, but static type checkers treat it as True.

Update shop/product.py like this:

from typing import TYPE_CHECKING

if TYPE_CHECKING:
    from shop.order import Order

class Product:
    def __init__(self, name: str, price: float) -> None:
        self.name = name
        self.price = price

    def is_in_order(self, order: "Order") -> bool:
        return order.product.name == self.name

The quotes around "Order" make the annotation a string, so Python 3.13 and earlier don’t try to look up Order at runtime. On Python 3.14, you can leave them out.

Now the runtime cycle is gone, and the program runs:

$ python main.py
2004.99

On Python 3.13 and earlier, the quotes around "Order" do real work. Without them, Python evaluates the annotation as soon as it defines is_in_order(), and you get NameError: name 'Order' is not defined. You’ll also encounter codebases that add from __future__ import annotations at the top of the file to get the same deferred behavior on older versions. You don’t need it on Python 3.14, but it’s worth recognizing when you see it.

Defer Imports to Inside Functions

Move the import statement from the top of the module into the function that needs it. Python then executes the import only when that function runs. By then, Python may have finished loading the other module, making the required class, function, or variable available.

For example, move the import inside order() in product.py:

from typing import TYPE_CHECKING

if TYPE_CHECKING:
    from shop.order import Order

class Product:
    def __init__(self, name: str, price: float) -> None:
        self.name = name
        self.price = price

    def order(self, quantity: int) -> "Order":
        from shop.order import Order

        return Order(self, quantity)

    def is_in_order(self, order: "Order") -> bool:
        return order.product.name == self.name

order.py and main.py stay unchanged. The TYPE_CHECKING block at the top isn’t a runtime import, so Order still isn’t imported when product.py starts loading. Python finishes defining the Product class without switching to order.py in the middle of the process.

Later, when Product.order() is called, Python executes from shop.order import Order. This starts loading order.py, which imports Product from product.py. By this point, the Product class has already been defined, so order.py safely imports it and finishes loading.

Run it, and the order goes through:

$ python main.py
1004.99

Because product.py no longer imports shop.order while it’s loading, this version works no matter which module your program imports first. You can check this by importing shop.order first:

$ python -c "import shop.order; print('OK')"
OK

Try the same command after you move imports to the bottom or change how you import the module, and you’ll get the ImportError again.

Move Imports to the Bottom

Another way to delay an import is to move it to the bottom of the file. This lets Python define all the classes and functions before importing another module:

class Product:
    def __init__(self, name: str, price: float) -> None:
        self.name = name
        self.price = price

    def order(self, quantity: int) -> "Order":
        return Order(self, quantity)

    def is_in_order(self, order: "Order") -> bool:
        return order.product.name == self.name

from shop.order import Order

main.py stays as it was, importing shop.product first:

from shop.product import Product

laptop = Product("Laptop", 1000.0)
order = laptop.order(1)
order.add_shipping()

print(order.get_total())

Python starts loading product.py and defines the Product class before reaching from shop.order import Order at the bottom. Python then loads order.py, which imports Product from product.py. This time, Product already exists, so the import succeeds and Python finishes loading both modules.

The program runs as expected:

$ python main.py
1004.99

However, you should avoid this approach in production code. It goes against PEP 8, which recommends placing all imports at the top of a file, and linters flag it. Flake8 reports it as E402 (“module level import not at top of file”), and Ruff reports the same code once you enable the pycodestyle rules with ruff check --select E402.

This works because main.py imports shop.product first. If something in your project imports shop.order first instead, then Python loads order.py, which imports product.py, which reaches from shop.order import Order at the bottom before order.py has defined Order. The ImportError comes back.

Change How You Import the Module

from shop.product import Product and from shop import product don’t behave the same way during a circular import.

With from shop.product import Product, Python immediately looks for Product inside shop.product. If shop.product is still being initialized and Product hasn’t been defined yet, the import fails.

With from shop import product, Python gets the product module itself. The attribute lookup happens later, when the code accesses product.Product.

Update shop/order.py as follows:

from typing import TYPE_CHECKING

from shop import product

if TYPE_CHECKING:
    from shop.product import Product

SHIPPING_FEE = 4.99

DEFAULT_PRODUCT = product.Product("product_a", 0.0)

class Order:
    def __init__(self, product: "Product", quantity: int) -> None:
        self.product = product
        self.quantity = quantity
        self.extras: list["Product"] = []

    def add_shipping(self) -> None:
        self.extras.append(product.Product("Shipping", SHIPPING_FEE))

    def get_total(self) -> float:
        subtotal = self.product.price * self.quantity
        return subtotal + sum(extra.price for extra in self.extras)

The ImportError is gone, but this version adds DEFAULT_PRODUCT = product.Product("product_a", 0.0) at the module level in order.py. This line accesses Product immediately, raising an AttributeError:

$ python main.py
Traceback (most recent call last):
  File "main.py", line 1, in <module>
    from shop.product import Product
  File "shop/product.py", line 1, in <module>
    from shop.order import Order
  File "shop/order.py", line 10, in <module>
    DEFAULT_PRODUCT = product.Product("product_a", 0.0)
                      ^^^^^^^^^^^^^^^
AttributeError: partially initialized module 'shop.product' from
⮑ 'shop/product.py' has no attribute 'Product' (most likely due to a
⮑ circular import)

Here’s what happened:

• main.py starts loading shop.product, which immediately imports shop.order.
• order.py runs from shop import product. Python returns the partially initialized shop.product module from sys.modules without looking for Product.
• order.py runs DEFAULT_PRODUCT = product.Product("product_a", 0.0). product.py hasn’t reached the Product class definition yet, so the attribute lookup fails.

To avoid the error, don’t access Product at the module level at all. Delete DEFAULT_PRODUCT and leave the only access inside add_shipping(), where it runs long after both modules have loaded.

Here’s the updated order.py:

from typing import TYPE_CHECKING

from shop import product

if TYPE_CHECKING:
    from shop.product import Product

SHIPPING_FEE = 4.99

class Order:
    def __init__(self, product: "Product", quantity: int) -> None:
        self.product = product
        self.quantity = quantity
        self.extras: list["Product"] = []

    def add_shipping(self) -> None:
        self.extras.append(product.Product("Shipping", SHIPPING_FEE))

    def get_total(self) -> float:
        subtotal = self.product.price * self.quantity
        return subtotal + sum(extra.price for extra in self.extras)

The cycle is still there, but nothing touches product.Product too early, so both modules finish loading:

$ python main.py
1004.99

As with the previous workaround, this depends on main.py importing shop.product first. Change which module your program imports first, and the cycle fails again.