Python 3.11 安装 Django 2.x 或 3.1 以下版本会因语法不兼容直接报 SyntaxError：旧版 Django 硬引用已被移除的 collections.Iterator，且未适配 3.11 新解析规则；唯一可靠解法是升级至 Django 3.2+（首个正式支持 3.11 的 LTS 版），并注意 mysqlclient 等依赖版本匹配。
Python 3.11 安装 Django 2.x 或 3.1 以下版本直接报 SyntaxError: invalid syntax
因为旧版 Django（如 2.2、3.0）的源码里用了 Python 3.11 已废弃或重定义的语法结构。最典型的是 collections.Iterator —— Python 3.11 把它从 collections 模块移走了，改由 typing.Iterator 提供。而 Django 2.2 及更早版本硬编码引用了 collections.Iterator，一导入就崩。
另一个常见表现是生成器表达式或 f-string 解析异常，尤其在 widgets.py 或模板渲染相关模块中。这不是 pip 安装失败，而是运行时首次 import django 就触发的 SyntaxError。
- Django 2.2 最高只支持到 Python 3.8，官方明确不兼容 3.11
- Django 3.1 虽宣称支持 3.9+，但实际未覆盖 3.11 的
collections拆分变更 - 哪怕强制用
pip install Django==2.2成功，python -m django --version也会立即抛错
升级到 Django 3.2+ 是唯一可靠解法，但要注意 MySQL 驱动兼容性
Django 3.2 是第一个正式声明支持 Python 3.11 的长期支持版本（LTS），它把所有 collections.* 引用替换为 typing.*，并适配了新语法解析规则。不过别直接跳到 Django 4.2+ —— 如果项目还在用 mysqlclient < 2.2.0，Django 4.2 会因底层 C API 变更而拒绝启动，报错类似 AttributeError: 'Connection' object has no attribute '_sock'。
- 稳妥组合：
python3.11+Django==3.2.24+mysqlclient==2.1.1 - 若必须用 Django 4.x，请同步升级
mysqlclient>=2.2.0或改用pymysql（纯 Python 实现，无编译依赖） -
pip install --upgrade django默认装最新版，可能越过兼容层，建议显式指定版本
虚拟环境隔离不等于自动兼容，conda 和 venv 行为有差异
即使你用 python3.11 -m venv myenv 创建干净环境，pip 仍可能从缓存里装入旧版 Django 的 wheel 包 —— 特别是之前在同一机器上装过 Django 2.x。conda 则更严格：执行 conda create -n py311-django32 python=3.11 django=3.2 会自动解决所有子依赖冲突，包括 pytz、sqlparse 等隐式依赖的版本锁定。
立即学习“Python免费学习笔记（深入）”；
- pip 缓存干扰：运行
pip cache purge再装，避免复用损坏的旧 wheel - venv 下装完务必验证：
python -c "import django; print(django.__version__)"，不能只信 pip 输出 - conda 用户注意：
conda install django默认走 conda-forge 通道，版本更新比 pip pypi 快，但有时滞后于安全补丁
django-debug-toolbar 在 Python 3.11 下需 Django ≥4.2.9，否则静默失效
这个调试工具看似和核心框架无关，但它依赖 Django 内部的中间件注册机制和模板引擎钩子。Django 4.2 之前版本在 Python 3.11 下虽能启动，但 django-debug-toolbar 的 JS 注入点会因字符串编码处理差异被跳过，浏览器控制台看不到 toolbar，也没有报错 —— 你只会发现“明明装了却没显示”。
- 最低要求：
django-debug-toolbar>=4.2.0且Django>=4.2.9 - 检查方式：访问
/__debug__/路径，返回 404 或空白页即说明未生效 - 若用 Django 3.2，只能退回到
django-debug-toolbar==3.2.4，但该版本不支持 Python 3.11 的async def中间件写法
