MacOS环境下如何全新安装Wagtail 5.1及以上版本？

我使用MacOS系统，尝试在venv虚拟环境中安装Wagtail 5.1。执行了pip install wagtail和wagtail start mysite mysite命令后，未进入mysite目录执行pip install -r requirements.txt，直接进入目录执行python manage.py migrate（目的是安装Wagtail 5.1而非2.1），但出现ModuleNotFoundError: No module named 'wagtail.core'错误，请问如何全新安装Wagtail 5.1及以上版本？

报错信息 #

Traceback (most recent call last):
  File "/Users/catman/Documents/dev/wt/mydir/catproject/manage.py", line 10, in <module>
    execute_from_command_line(sys.argv)
  File "/Users/catman/Documents/dev/wt/mydir/venv/lib/python3.11/site-packages/django/core/management/__init__.py", line 442, in execute_from_command_line
    utility.execute()
  File "/Users/catman/Documents/dev/wt/mydir/venv/lib/python3.11/site-packages/django/core/management/__init__.py", line 416, in execute
    django.setup()
  File "/Users/catman/Documents/dev/wt/mydir/venv/lib/python3.11/site-packages/django/__init__.py", line 24, in setup
    apps.populate(settings.INSTALLED_APPS)
  File "/Users/catman/Documents/dev/wt/mydir/venv/lib/python3.11/site-packages/django/apps/registry.py", line 91, in populate
    app_config = AppConfig.create(entry)
                 ^^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/catman/Documents/dev/wt/mydir/venv/lib/python3.11/site-packages/django/apps/config.py", line 193, in create
    import_module(entry)
  File "/opt/homebrew/Cellar/python@3.11/3.11.5/Frameworks/Python.framework/Versions/3.11/lib/python3.11/importlib/__init__.py", line 126, in import_module
    return _bootstrap._gcd_import(name[level:], package, level)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "<frozen importlib._bootstrap>", line 1204, in _gcd_import
  File "<frozen importlib._bootstrap>", line 1176, in _find_and_load
  File "<frozen importlib._bootstrap>", line 1140, in _find_and_load_unlocked
ModuleNotFoundError: No module named 'wagtail.core'

解决步骤 #

1. 清理混乱环境（可选但推荐） #

如果之前的虚拟环境和项目已经出现版本冲突，先彻底清理：

• 退出当前虚拟环境：deactivate
• 删除旧虚拟环境文件夹：rm -rf /Users/catman/Documents/dev/wt/mydir/venv
• 删除旧项目目录：rm -rf /Users/catman/Documents/dev/wt/mydir/catproject

2. 创建并激活全新虚拟环境 #

# 进入目标开发目录
cd /Users/catman/Documents/dev/wt/mydir
# 创建Python虚拟环境
python3 -m venv venv
# 激活虚拟环境
source venv/bin/activate

3. 安装指定版本的Wagtail #

直接安装5.1版本或更高稳定版：

# 安装Wagtail 5.1
pip install wagtail==5.1
# 或者安装最新稳定版
# pip install wagtail

4. 创建Wagtail项目并进入目录 #

wagtail start mysite
cd mysite

5. 安装项目依赖（关键步骤） #

这是你之前遗漏的环节，必须执行以确保依赖版本兼容：

pip install -r requirements.txt

6. 完成项目初始化 #

# 执行数据库迁移
python manage.py migrate
# 创建后台超级用户
python manage.py createsuperuser
# 启动开发服务器
python manage.py runserver

错误原因说明 #

wagtail.core是Wagtail 2.x版本的旧模块结构，Wagtail 3.0+已重构模块体系，移除了该路径并统一使用wagtail根模块。你跳过pip install -r requirements.txt后，项目配置可能仍引用旧模块路径，且依赖版本不匹配，导致报错。执行依赖安装会同步适配Wagtail 5.1的配置和兼容依赖版本。

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