• All 51 popular Python repos I checked (1,000+ GitHub stars each) have circular import chains between files; in the median one, 16.4% of production files sit inside one.
• A Python circular import only fails with "partially initialized module" when a name is read from a module that has not finished running, such as a module-level from x import y, a base class, or a decorator that runs on import.
• Django has a 179-file import cycle and imports fine, because most of its cycles go through imports inside functions or imports used only for type hints.
• Fixes, in order: move the shared code to a third module, import the module instead of the name (with from __future__ import annotations), put type-only imports under TYPE_CHECKING, or import inside the function.

This is the error that sends people searching:

ImportError: cannot import name 'User' from partially initialized module 'shop.models' (most likely due to a circular import)

The usual advice is "you have a circular import, remove it". But I used repowise to look at the import graphs of 51 popular Python repositories (1,000+ GitHub stars each), and every single one has circular import chains between its files. In the median repo, 16.4% of production files sit inside one. In Django, one chain links 179 files, and Django imports fine.

So a cycle on its own is not the problem. Below: which cycles actually raise that error, why most do not, and how to fix the ones that do.

Reproduce it

Two modules in a package, each importing a name from the other:

# shop/models.py
from shop.services import send_welcome


class User:
    def __init__(self, email):
        self.email = email

# shop/services.py
from shop.models import User


def send_welcome(user: User):
    print(f"welcome, {user.email}")

# main.py
from shop.models import User
from shop.services import send_welcome

send_welcome(User("a@example.com"))

$ python main.py
Traceback (most recent call last):
  File "D:\devto-scratch\repro\shop\main.py", line 1, in <module>
    from shop.models import User
  File "D:\devto-scratch\repro\shop\shop\models.py", line 1, in <module>
    from shop.services import send_welcome
  File "D:\devto-scratch\repro\shop\shop\services.py", line 1, in <module>
    from shop.models import User
ImportError: cannot import name 'User' from partially initialized module 'shop.models' (most likely due to a circular import) (D:\devto-scratch\repro\shop\shop\models.py)

What happens, step by step:

1. main.py imports shop.models. Python creates an empty module object, puts it in sys.modules, and starts running models.py from the top.
2. Line 1 of models.py imports shop.services, so Python pauses models.py and starts running services.py.
3. Line 1 of services.py asks for User from shop.models. The module exists in sys.modules, but it is still on line 1. User has not been defined yet.

"Partially initialized" means exactly that: the module object exists, its code has not finished running. The cycle is only fatal because a name is read from the half-built module while it is still half built.

How common are circular imports in Python projects?

The 51 Python repos in the set include django, fastapi, airflow, langchain, prefect and paperless-ngx. Looking at file-to-file imports in production code only (tests, generated and vendored code excluded):

• 51 of 51 have at least one circular import group (a set of 2+ files that can all reach each other through imports).
• In the median Python repo, 16.4% of production files sit inside one.
• Across all 195 repos in the wider set, covering every language, the median is 9.2%.

To see why they do not break, I took a fresh clone of Django (commit 6a8248f) and looked at its import graph. Counting every import between the 900 non-test .py files under django/, 238 files sit inside a circular group and the largest group holds 179 files (the whole-repo index counts more, because it also includes files outside django/), from django/__init__.py through apps, conf, db and parts of contrib.

Then I dropped two kinds of import edges: imports written inside a function, and imports used only for type hints. Those two kinds do not run when the module is first loaded. The result:

Removing 152 import edges, about 5% of the total, shrinks the files involved by three quarters. Most of Django's cycles exist only because some function, somewhere, imports something when it is called. By then every module has finished loading, so there is nothing half built to trip over. Django's code is explicit about it. django/db/models/query_utils.py has this inside Q.check():

        # Avoid circular imports.
        from django.db.models import Value
        from django.db.models.sql import Query
        from django.db.models.sql.constants import SINGLE

git grep -i "circular import" -- 'django/*.py' finds 16 comments like that in 11 files.

The 35-file group that remains is django/db/models, and it survives import because of ordering. django/db/models/__init__.py re-exports names from its submodules, and the order of those imports is pinned:

# Imports that would create circular imports if sorted
from django.db.models.base import DEFERRED, Model  # isort:skip
from django.db.models.fields.related import (  # isort:skip
    ForeignKey,
    ForeignObject,
    OneToOneField,

So the real picture of a big Python codebase is: lots of cycles, nearly all of them harmless, and a handful held together by import order. The error shows up when someone reorders those imports or adds a new module-level import in the wrong direction.

Which circular imports raise "partially initialized module"?

1. A module-level from x import y that runs while x is half built

That is the reproduction above. from module import name reads the name immediately. If module is still running higher up the stack, the name does not exist yet.

2. Inheriting from a class across the cycle

A class statement needs its base class at the moment the class is created, so even "import the module, not the name" does not save you:

# plugins/base.py
from plugins.email import EmailNotifier


class Notifier:
    def send(self, msg):
        raise NotImplementedError


DEFAULT = EmailNotifier

# plugins/email.py
import plugins.base as base


class EmailNotifier(base.Notifier):
    def send(self, msg):
        print("email:", msg)

  File "D:\devto-scratch\repro\inherit\plugins\email.py", line 4, in <module>
    class EmailNotifier(base.Notifier):
                        ^^^^^^^^^^^^^
AttributeError: partially initialized module 'plugins.base' from 'D:\devto-scratch\repro\inherit\plugins\base.py' has no attribute 'Notifier' (most likely due to a circular import)

3. Registries and decorators that run on import

The classic web-app layout: app.py imports the views so the routes get registered, and views.py imports app to use its decorator.

# web/app.py
from web import views  # load the routes


class App:
    def __init__(self):
        self.routes = {}

    def route(self, path):
        def register(fn):
            self.routes[path] = fn
            return fn
        return register


app = App()

# web/views.py
from web.app import app


@app.route("/")
def index():
    return "hello"

  File "D:\devto-scratch\repro\registry\web\views.py", line 1, in <module>
    from web.app import app
ImportError: cannot import name 'app' from partially initialized module 'web.app' (most likely due to a circular import) (D:\devto-scratch\repro\registry\web\app.py)

The decorator runs at import time, so it needs app before app.py has created it.

How do you fix a circular import in Python?

All of these were run on Python 3.13.

Move the shared piece to a third module

The best fix removes the cycle. In the inheritance example, base.py only imported EmailNotifier to set a default. Move the default somewhere that sits above both:

# plugins/base.py
class Notifier:
    def send(self, msg):
        raise NotImplementedError

# plugins/defaults.py
from plugins.email import EmailNotifier

DEFAULT = EmailNotifier

$ python main.py
email: hi

Now base imports nothing, email imports base, defaults imports email. The arrows only point one way. For the registry example the same idea is an app factory, or a main.py that imports app first and views second.

Import the module, not the name, and defer annotations

from shop import models binds the module object, which exists even while it is half built. You then read models.User later, when it exists. One catch: annotations are evaluated when the function is defined, so this still fails on Python 3.13:

# shop/services.py
from shop import models


def send_welcome(user: models.User):
    print(f"welcome, {user.email}")

    def send_welcome(user: models.User):
                           ^^^^^^^^^^^
AttributeError: partially initialized module 'shop.models' from 'D:\devto-scratch\repro\shop\shop\models.py' has no attribute 'User' (most likely due to a circular import)

Add from __future__ import annotations at the top of services.py and it runs, because annotations become strings that are never evaluated at import time. (Python 3.14 defers annotation evaluation by default, PEP 649.)

If the import is only for type hints, use TYPE_CHECKING

# shop/services.py
from __future__ import annotations

from typing import TYPE_CHECKING

if TYPE_CHECKING:
    from shop.models import User


def send_welcome(user: User):
    print(f"welcome, {user.email}")

$ python main.py
welcome, a@example.com

The import only exists for mypy, pyright and your editor. At runtime it never executes.

Import inside the function

# shop/models.py
class User:
    def __init__(self, email):
        self.email = email

    def welcome(self):
        from shop.services import send_welcome
        send_welcome(self)

This is what Django does in those 16 commented places. It works, and it is fine as a local patch. It is also how a codebase ends up with a 179-file cycle that nobody can see, so leave a comment, like Django does, saying why the import is there.

How do you find circular imports in your own project?

For a list in the terminal, pylint has a check for exactly this:

pylint --disable=all --enable=cyclic-import django/db

On Django's django/db it reported 72 cyclic-import messages in 8.5 seconds, for example:

django\db\models\sql\__init__.py:1:0: R0401: Cyclic import (django.db.models.manager -> django.db.models.query) (cyclic-import)
django\db\models\sql\__init__.py:1:0: R0401: Cyclic import (django.db.models.base -> django.db.models.fields.related) (cyclic-import)

pylint counts imports inside functions too, so expect it to list cycles that never fail at runtime. pydeps yourpackage --show-cycles draws the same cycles as a graph (it needs Graphviz installed). To stop new cycles in CI, import-linter can fail the build on cycles between subpackages. The setup for that, plus the TypeScript and Go equivalents, is in this guide to finding circular dependencies.

To look at the cycles on a picture instead of a list, Django's architecture view shows the same import graph, and the trace tool on that page finds the path between any two files.

How I got these numbers

The 51 repos are the Python part of a set of 195 of the most-starred public repositories indexed on repowise (1,000+ GitHub stars each, 253,688 production source files, November 2026), each measured at its own latest index between May and November 2026. The cross-language numbers are in finding 6 of the code health 2026 report. Cycles are counted on file-to-file imports between production files, so __init__.py re-exports count as edges. The Django breakdown comes from repowise init --yes --no-prose --no-editor-setup on a fresh clone at 6a8248f, then a strongly connected components pass over the stored import graph, once with every import edge and once without the edges marked as function-level or type-only.

FAQ

What does "partially initialized module ... most likely due to a circular import" mean? Python has created the module object and put it in sys.modules, but the module's code is still running further up the import chain. Something asked for a name that the module has not defined yet, so the import fails with that message.

Does from __future__ import annotations fix circular imports? Only when the cycle breaks on a type hint. It turns annotations into strings that are not evaluated at import time, so def f(user: models.User) stops failing. It does not help when the name is needed while the module loads, such as a base class or a decorator.

Are circular imports always a bug in Python? No. All 51 Python repos in this set have circular import chains between files and import fine. A cycle only fails when one module reads a name from another before that module has finished running.

• 45 of 50 popular Python repos (1,000+ GitHub stars) have at least one dead-code finding in production code, and in the median repo 3.9% of production files are flagged as unreachable.
• In Python, a file nothing imports is often loaded by name: 82 of Django's 100 dead-code candidates are locale files imported from a string at runtime.
• 814 of the 819 files flagged in LangChain are compatibility shims that keep old import paths working for its users.
• vulture finds unused names inside a file and an import-graph pass finds whole files nothing imports; Python projects need both, plus a string search before each delete.

I ran a dead-code pass with repowise over 51 popular Python repositories, each with 1,000+ GitHub stars: Django, FastAPI, Airflow, LangChain, Prefect, paperless-ngx and 45 more. Then I took three of them, cloned them fresh, and read the flagged files one group at a time to see what they really were.

The short version: almost every popular Python repo has code that nothing imports, and in Python "nothing imports this" very often means "something loads this by name". Below are the numbers, what the hand check found, and a way to clean up your own project that takes both facts into account.

What counts as dead code in Python?

Two kinds of finding, on production source files only (tests, generated code, vendored code, build scripts and docs examples are excluded):

• A file flagged as unreachable: no other file imports it, and it is not an entry point.
• An unused export: a public function, class or constant defined in one module that no other module imports.

Each finding has a confidence between 0 and 1. I call 0.7 and above "high confidence".

How much dead code do popular Python projects carry?

Dead-code data exists for 50 of the 51 Python repos.

• 45 of 50 have at least one finding. 45 of 50 have at least one unused export, 42 have at least one file flagged as unreachable, and 37 have at least one high-confidence finding.
• The median repo has 15.7 findings per 100 production files, and 3.9% of its production files are flagged as unreachable.
• Pooled across the 50 repos: 4,074 flagged files and 6,008 unused exports, in 38,285 production files.

Some recognisable names, each measured at its own latest index:

FastAPI's own package has no findings at all (the table counts production files only). When I re-ran it on a fresh clone, all 259 candidates were in docs_src/ (the code samples behind its documentation), scripts/ and docs/, none in fastapi/.

The bottom rows are where it gets interesting, because what a flagged file means depends on how the project loads its code. Here is what the flagged files were.

What I found when I checked by hand

I cloned each repo, indexed it with the repowise CLI, listed the findings, and then read the flagged files in groups.

Django: 82 of 100 candidates are locale files loaded by string

On Django at commit 6a8248f, the dead-code pass returned 100 candidates. 82 of them are files like these:

django/conf/locale/ar/formats.py
django/conf/locale/ar_DZ/formats.py
django/conf/locale/az/formats.py

No Python file imports django/conf/locale/ar/formats.py. Django loads it at runtime, by building the module name as a string, in django/utils/formats.py:

    for location in format_locations:
        for loc in locales:
            try:
                yield import_module("%s.formats" % (location % loc))
            except ImportError:
                pass

Delete one of those files and Arabic date formatting silently falls back to the default. The other 18 candidates were eight JavaScript files (the admin's static scripts and a JS template, served to the browser), the Sphinx config, extensions and docs linter under docs/, and three functions in scripts/manage_translations.py that its command-line parser dispatches to.

These are files to keep, and the tool treats them that way. Asking for deletion-ready findings only returns nothing, with the reason:

$ repowise dead-code --safe-only
100 finding(s), none deletion-ready: a finding is deletion-ready only when missing imports are evidence for its language. Review the ranked list without the safe-only filter.

LangChain: 814 files that keep old import paths working

On LangChain at commit 1a41b51, 819 files are flagged as unreachable, and 814 of them sit in one package: libs/langchain/langchain_classic. Nearly all look like this:

from typing import TYPE_CHECKING, Any

from langchain_classic._api import create_importer

if TYPE_CHECKING:
    from langchain_community.agent_toolkits.jira.toolkit import JiraToolkit

# Create a way to dynamically look up deprecated imports.
# Used to consolidate logic for raising deprecation warnings and
# handling optional imports.
DEPRECATED_LOOKUP = {"JiraToolkit": "langchain_community.agent_toolkits.jira.toolkit"}

_import_attribute = create_importer(__package__, deprecated_lookups=DEPRECATED_LOOKUP)


def __getattr__(name: str) -> Any:
    """Look up attributes dynamically."""
    return _import_attribute(name)

That is a compatibility shim. Code written against an older LangChain still does from langchain.agents.agent_toolkits.jira.toolkit import JiraToolkit, and this file forwards the import to its new home with a deprecation warning. Nothing inside the repo imports it because the importers are LangChain's users.

I sorted all 819 by what they contain: 758 use create_importer like the file above, 48 only re-export names. Of the remaining 13, nine are importable modules of the same package (prompt templates and API documentation strings), two are version.py files kept for backwards compatibility in partner packages, and two sit in an examples folder. Removing any of the package files is a breaking change for users, not a cleanup.

Across the whole repo, one finding is marked ready to delete: an example function, run_calculator_http, that git grep finds nowhere except its own definition.

Airflow: example DAGs, docs configs, and one repeated helper

On Airflow at commit 6a8bc716, the pass returned 791 candidates: 352 flagged files, 436 unused exports and 3 unused workspace packages. I sorted the 352 files:

• 111 are example DAGs under example_dags/ folders. Airflow never imports them. It points its DAG processor at the folder and parses every file in it, in airflow-core/src/airflow/dag_processing/bundles/manager.py:

def _add_example_dag_bundle(bundle_config_list: list[_ExternalBundleConfig]):
    from airflow import example_dags

    example_dag_folder = next(iter(example_dags.__path__))

• 109 are docs/conf.py files, one Sphinx config per provider package. Sphinx loads them by path.
• 14 are generated OpenAPI client files for the web UI, and most of the rest are other front-end and dev tooling files.
• 59 are copies of a small version_compat.py helper from the provider package template. In those 59 providers, git grep finds nothing that imports it, so they are the ones worth a look: a few lines each, ready for whenever a provider needs the version check.

So most of Airflow's flagged files are loaded from a folder or by a tool, the same shape as the other repos, and the clear candidates come down to one small template file.

The pattern

In all three, most of the files an import graph cannot reach were reached another way:

• by a module name built from a string (import_module, __import__, Django's INSTALLED_APPS, Celery task names), or a folder scanned at runtime (Airflow's DAG folders),
• by packaging metadata (console scripts and plugin entry points in pyproject.toml),
• or by code outside the repo (a published library's public import paths).

That is why a good dead-code pass for Python reports confidence and a separate "ready to delete" decision, and why the second step is always a search for the module's dotted name as a string.

Vulture or an import graph: what does each one find?

The tool most Python developers know is vulture. It reads each file's syntax tree and reports names that are defined and never used. On the same Django clone:

$ vulture django/ --min-confidence 80
django\contrib\admindocs\middleware.py:14: unused variable 'view_args' (100% confidence)
django\contrib\admindocs\middleware.py:14: unused variable 'view_kwargs' (100% confidence)
django\contrib\auth\middleware.py:54: unused variable 'view_args' (100% confidence)
django\contrib\auth\middleware.py:54: unused variable 'view_kwargs' (100% confidence)
django\contrib\gis\management\commands\ogrinspect.py:14: unused variable 'option_string' (100% confidence)
django\contrib\gis\management\commands\ogrinspect.py:28: unused variable 'option_string' (100% confidence)
django\core\serializers\xml_serializer.py:506: unused variable 'has_internal_subset' (100% confidence)
django\core\serializers\xml_serializer.py:510: unused variable 'is_parameter_entity' (100% confidence)
django\db\backends\utils.py:94: unused variable 'ignored_wrapper_args' (100% confidence)
django\db\backends\utils.py:107: unused variable 'ignored_wrapper_args' (100% confidence)
django\db\models\enums.py:78: unused variable 'last_values' (100% confidence)
django\utils\inspect.py:138: unused variable 'annotation_format' (100% confidence)

Every one of these is a parameter the function has to keep: a callback signature, an overridden method, or a keyword kept for API compatibility. process_view(self, request, view_func, view_args, view_kwargs) has to accept view_args even if this middleware never reads it. At vulture's default threshold of 60%, the same run prints 2,010 lines, mostly unused variables, methods and classes that Django's own machinery or its users call.

The two checks answer different questions:

Use both. They rarely flag the same thing.

How do you find dead code in a Python project?

Start with vulture at a high threshold, and keep a whitelist for the framework hooks it cannot see:

pip install vulture
vulture src/ --min-confidence 80
vulture src/ --make-whitelist > whitelist.py   # review it, then:
vulture src/ whitelist.py --min-confidence 80

Then look at whole files and exports. With the repowise CLI, which builds the import graph locally and needs no API key:

pip install repowise
repowise init --yes --no-prose --no-editor-setup
repowise dead-code --min-confidence 0.7
repowise dead-code --safe-only

For every file on that list, before deleting it, search for its dotted module name and its file stem as strings:

$ git grep -n "django.conf.locale" -- 'django/*.py'
django/utils/formats.py:76:    format_locations.append("django.conf.locale.%s")
django/utils/translation/__init__.py:270:    from django.conf.locale import LANG_INFO
django/utils/translation/trans_real.py:14:from django.conf.locale import LANG_INFO

If anything builds the name dynamically, you will usually find the prefix, as in the first line here. Search pyproject.toml and setup.cfg too, for entry points.

What I would delete first

1. Files that are flagged, have no string reference anywhere, and have not changed in a long time. Old and unreferenced is the safest combination.
2. Unused private helpers vulture finds at 80% or more inside files you already own. Low risk, small diffs.
3. Nothing in a published package's import surface until a major version. Move it behind a deprecation warning first, the way LangChain does.

Delete in small pull requests, one directory or one kind of finding at a time. Run the full test suite on each, plus an import of every module in the package, which catches a deleted file that something still imports by name at load time:

python -c "import importlib, pkgutil, mypkg; [importlib.import_module(m.name) for m in pkgutil.walk_packages(mypkg.__path__, 'mypkg.')]"

If you are choosing a tool, this comparison of dead code detection tools covers vulture, the import-graph approach and the options for other languages. Django's code health page shows the dead-code list from the table above in the browser.

Which loading pattern has bitten you when deleting "unused" Python code: string imports, entry points, or something else?

How I got these numbers

The 51 repos are the Python part of a set of 195 of the most-starred public repositories indexed on repowise (1,000+ GitHub stars each, 253,688 production source files, November 2026); the dead-code numbers for the full set are in the code health 2026 report. Findings are counted at confidence 0.4 and above, on production files only, with each repo measured at its own latest index between May and November 2026, so the table is a snapshot per repo. The hand checks were fresh clones on 10 November 2026: Django 6a8248f (full history), LangChain 1a41b51 and Airflow 6a8bc716 (last 300 commits), FastAPI ba5d72b (last 500 commits), each indexed with repowise init --yes --no-prose --no-editor-setup (repowise 0.60.1), plus vulture 2.16 on Django. A fresh run can differ from the table, because the code and the tool both move between index dates.

FAQ

What does vulture do in Python? vulture reads each file's syntax tree and reports functions, classes, variables and imports that are defined and never used, each with a confidence score. It works on names, so it does not report a whole module that nothing imports, and it cannot see names that a framework calls through reflection.

Does Ruff find dead code? Ruff finds unused imports (F401) and unused local variables (F841) inside each file, and commented-out code with its eradicate rules (ERA001). It does not track whether another module ever uses a function or file, so unused exports and unreachable files need vulture or an import-graph tool.

How do I find unreachable code in Python? For statements that can never run, such as code after a return, pylint reports unreachable (W0101). For whole files that nothing reaches, build the import graph (for example repowise dead-code --min-confidence 0.7), then search for each file's dotted module name as a string before deleting it, because Python code is often loaded by name.