Django连接MongoDB出现ImproperlyConfigured报错如何解决

这个报错本质是Django无法加载你配置的MongoDB数据库后端，按以下顺序逐次排查即可，覆盖所有已知触发场景：

1. 先搞定依赖版本匹配 #

Django本身原生不支持MongoDB，不要试图直接用pymongo对接原生Django ORM，目前主流稳定适配方案是djongo，版本不兼容是最高发的问题：

• 先卸载所有可能冲突的相关包：

pip uninstall -y django djongo pymongo mongoengine

• 按你用的Django版本装对应匹配的组合，不要乱装最新版：
  • Django 3.2.x LTS版本：安装djongo==1.3.6 + pymongo==3.12.3
  • Django 4.0/4.1/4.2.x版本：安装djongo==1.3.7 + pymongo==4.5.0
    注意pymongo不要装4.6以上版本，和现有稳定版djongo存在导入兼容问题，装了必报错。

2. 逐行核对settings.py数据库配置 #

配置格式写错是第二大诱因，直接对照下面的正确模板改，不要自己瞎写ENGINE值：

DATABASES = {
    'default': {
        # 这里ENGINE必须严格写'djongo'，不要写成django.db.backends.djongo、django、mongo这类错值
        'ENGINE': 'djongo',
        'NAME': '你要使用的MongoDB库名', # 不需要提前建库，写入数据时自动创建
        'CLIENT': {
            'host': 'MongoDB服务地址', # 本地默认填127.0.0.1
            'port': 27017, # 改了端口就填你自己的实际端口
            # 开了账号密码认证就加下面两个字段，没开直接删掉
            # 'username': '数据库账号',
            # 'password': '数据库密码',
            # 副本集、SSL这类额外配置统一放在CLIENT字典里即可
        }
    }
}

只要ENGINE值写错，100%会抛出你贴的这个报错，别在这个字段上自由发挥。

3. 排查导入链路冲突 #

前两步做完还报错的话，基本是导入路径的问题，按下面查：

• 先在项目对应的虚拟环境里执行命令，验证包能不能正常导入：

python -c "import djongo; print(djongo.__version__)"

如果这一步直接报ImportError，说明你装包的虚拟环境和跑Django项目的虚拟环境不是同一个，切到项目用的虚拟环境重新装依赖就行。

• 检查你的项目根目录下，有没有自己建的叫djongo的文件夹、或者叫django.py/djongo.py的文件，这类命名会和第三方安装包重名，Python导入时会优先读你本地的错误文件，直接把冲突的文件/文件夹重命名即可。
• 如果你配置了DATABASE_ROUTERS多库路由，先临时注释掉，确认单库连接正常后再逐步恢复路由规则。

4. 极端场景兜底处理 #

• 清空项目下所有__pycache__缓存文件夹，重启Django服务，避免旧错误配置的缓存导致的问题。
• Windows环境下检查Python对应site-packages目录的权限，确保运行项目的用户有目录读权限，权限不足会导致无法导入安装好的djongo包。
• 不要同时装多个MongoDB适配Django的包，比如mongoengine、django-mongodb-engine这类，会互相修改Django后端注册逻辑导致冲突。

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