执行Django的makemigrations命令时出现循环依赖错误求助

开发者阿泽

2026-7-13

Django迁移报错CircularDependencyError: users.0001_initial的解决办法

先贴出报错信息：

@user: django_angular_auth_api % python3 manage.py makemigrations
Traceback (most recent call last):
  File "/Users/user/django-angular-auth/django_angular_auth_api/manage.py", line 22, in <module>
    main()
  File "/Users/user/django-angular-auth/django_angular_auth_api/manage.py", line 18, in main
    execute_from_command_line(sys.argv)
  File "/Library/Frameworks/Python.framework/Versions/3.11/lib/python3.11/site-packages/django/core/management/__init__.py", line 442, in execute_from_command_line
    utility.execute()
  File "/Library/Frameworks/Python.framework/Versions/3.11/lib/python3.11/site-packages/django/core/management/__init__.py", line 436, in execute
    self.fetch_command(subcommand).run_from_argv(self.argv)
  File "/Library/Frameworks/Python.framework/Versions/3.11/lib/python3.11/site-packages/django/core/management/base.py", line 412, in run_from_argv
    self.execute(*args, **cmd_options)
  File "/Library/Frameworks/Python.framework/Versions/3.11/lib/python3.11/site-packages/django/core/management/base.py", line 458, in execute
    output = self.handle(*args, **options)
             ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/Library/Frameworks/Python.framework/Versions/3.11/lib/python3.11/site-packages/django/core/management/base.py", line 106, in wrapper
    res = handle_func(*args, **kwargs)
          ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/Library/Frameworks/Python.framework/Versions/3.11/lib/python3.11/site-packages/django/core/management/commands/makemigrations.py", line 137, in handle
    loader = MigrationLoader(None, ignore_no_migrations=True)
             ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/Library/Frameworks/Python.framework/Versions/3.11/lib/python3.11/site-packages/django/db/migrations/loader.py", line 58, in __init__
    self.build_graph()
  File "/Library/Frameworks/Python.framework/Versions/3.11/lib/python3.11/site-packages/django/db/migrations/loader.py", line 305, in build_graph
    self.graph.ensure_not_cyclic()
  File "/Library/Frameworks/Python.framework/Versions/3.11/lib/python3.11/site-packages/django/db/migrations/graph.py", line 284, in ensure_not_cyclic
    raise CircularDependencyError(
django.db.migrations.exceptions.CircularDependencyError: users.0001_initial

以下是针对这个问题的具体解决思路，已排除常规的加依赖、重置数据库方法：

检查users/models.py里的模型关系：看看有没有自引用字段（比如parent = models.ForeignKey('self', ...)），或者和其他应用模型的双向关联（比如User里有外键到Post，Post里又有外键/多对多到User）。这种双向关联很容易触发循环依赖，建议把其中一方改成字符串引用模型（比如models.ForeignKey('app.Model', ...)），或者用related_name明确关联关系，避免自动生成的反向关联导致的依赖问题。
手动调整迁移文件的依赖：打开users/migrations/0001_initial.py，查看dependencies列表，看看有没有和其他应用迁移形成循环的项。如果发现循环，先暂时移除可疑的依赖，执行makemigrations生成新的迁移，之后再根据实际情况调整依赖顺序。
拆分迁移文件：如果0001_initial里同时创建了多个互相依赖的模型，把迁移拆成两步：先创建没有关联字段的基础模型，生成第一个迁移；再添加关联字段，生成第二个迁移。这样能避免单个迁移里的循环依赖。
用--fake参数重置迁移状态：如果数据库里已经有users表的数据，先执行python3 manage.py migrate --fake users zero，把users应用的迁移状态重置为初始；然后删除users/migrations下除了__init__.py之外的所有文件，重新执行python3 manage.py makemigrations users生成全新的迁移文件，再尝试迁移。
检查INSTALLED_APPS顺序：在settings.py里，确保users应用在所有依赖它的应用之前被声明。Django会按照INSTALLED_APPS的顺序解析迁移依赖，顺序不对也可能触发循环依赖报错。

内容的提问来源于stack exchange，提问作者Isa Khan