为何mypy检测SQLAlchemy代码时报错：找不到declarative_base属性

问题分析 #

你遇到的报错是因为同时安装了sqlalchemy-stubs和sqlalchemy2-stubs两个类型存根包，二者存在版本冲突：

• sqlalchemy2-stubs是为SQLAlchemy 2.0+设计的
• 你当前使用的是SQLAlchemy 1.4.42，对应的类型存根需适配1.4版本，冲突导致mypy无法找到正确的declarative_base类型定义。

调试与解决步骤 #

1. 卸载冲突的类型存根包 #

执行以下命令移除两个冲突的stubs：

pip uninstall -y sqlalchemy-stubs sqlalchemy2-stubs

2. 重新安装适配SQLAlchemy 1.4的mypy支持 #

只保留官方的sqlalchemy[mypy]扩展，确保版本与你的SQLAlchemy一致：

pip install -U sqlalchemy[mypy]==1.4.42

3. 配置mypy启用SQLAlchemy插件 #

确保mypy加载SQLAlchemy的官方类型检查插件，有两种方式：

• 方式一：添加配置文件
  在项目根目录创建mypy.ini或pyproject.toml，添加：

  [mypy]
  plugins = sqlalchemy.ext.mypy.plugin
  

• 方式二：命令行参数
  执行mypy时直接指定插件：

  python3 -mmypy --sqlalchemy-strict test.py
  

4. 验证运行时代码正确性 #

先确认代码在运行时无问题，执行：

python test.py

如果运行正常，说明代码本身无语法问题，问题仅出在类型检查层面。

5. 确认虚拟环境激活状态 #

检查当前使用的mypy是否属于虚拟环境：

which mypy

输出路径应指向你的虚拟环境bin目录，若不是，重新激活虚拟环境后再执行mypy。

内容的提问来源于stack exchange，提问作者Patrick B.