使用asyncpg的FastAPI项目出现psycopg2依赖问题及Docker部署报错

1. 明确指定SQLAlchemy的异步驱动约束 #

如果项目使用了SQLAlchemy，它默认会将psycopg2列为可选依赖，Poetry解析时可能自动安装。需要强制绑定asyncpg作为唯一异步驱动：

• 在pyproject.toml中更新SQLAlchemy的依赖声明：

  [tool.poetry.dependencies]
  # 替换成你实际使用的SQLAlchemy版本
  sqlalchemy = { version = "^2.0", extras = ["asyncpg"] }
  asyncpg = "^0.29.0"
  

• 执行命令同步依赖并更新lock文件：

  poetry install --sync
  poetry lock --no-update
  

2. 定位隐式依赖来源 #

如果上述操作后psycopg2仍存在，用更精准的命令排查间接依赖：

poetry show --tree | grep -B2 -A2 psycopg2

重点检查是否有其他依赖（比如Alembic、数据库工具包）将psycopg2列为可选依赖并被默认安装。例如Alembic需要单独配置异步支持：

alembic = { version = "^1.12.0", extras = ["async"] }

3. 强制清理lock文件并重新生成 #

删除现有poetry.lock，完全重建依赖链，避免旧依赖缓存干扰：

rm poetry.lock
# 先安装依赖（不包含项目本身）
poetry install --no-root

如果此时psycopg2仍被安装，说明有依赖强制要求它，需检查该依赖的文档，确认是否支持仅使用asyncpg。

4. 修正SQLAlchemy连接配置 #

确保异步引擎的连接字符串使用postgresql+asyncpg://前缀，避免SQLAlchemy自动尝试加载psycopg2：

from sqlalchemy.ext.asyncio import create_async_engine, AsyncSession
from sqlalchemy.orm import sessionmaker

# 正确的异步连接字符串格式
DATABASE_URL = "postgresql+asyncpg://user:password@db_host:5432/db_name"
engine = create_async_engine(DATABASE_URL, echo=True)
async_session = sessionmaker(engine, class_=AsyncSession, expire_on_commit=False)

5. Docker部署时的依赖同步 #

在Dockerfile中使用--sync参数确保只安装lock文件中声明的必要依赖，避免冗余包：

# 假设已安装Poetry的基础镜像
COPY pyproject.toml poetry.lock ./
RUN poetry install --no-dev --sync

不要在Dockerfile中手动安装psycopg2相关包，避免触发SQLAlchemy的同步驱动检测错误。

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