pip install alembic 即可安装官方PyPI最新稳定版1.19.1，自动依赖SQLAlchemy（≥1.4）和可选python-dotenv，但不创建配置或初始化项目结构，仅提供命令行工具alembic。
pip install alembic 就够了，不需要额外参数或源指定，除非你明确遇到网络或镜像问题。
pip install alembic 会装什么
- 安装的是官方 PyPI 上的最新稳定版（当前是
1.19.1，2026年8月发布） - 同时自动拉取依赖：主要是
SQLAlchemy（>=1.4）和python-dotenv（可选，用于读取 .env） - 不会自动创建配置、不初始化项目结构，只是把命令行工具
alembic放进你的PATH
安装后运行不了 alembic 命令？
常见原因和应对：
- 虚拟环境没激活 → 检查是否执行了
source venv/bin/activate（Linux/macOS）或venv\Scripts\activate（Windows） - 安装到了系统 Python 而不是当前虚拟环境 → 运行
which alembic（macOS/Linux）或where alembic（Windows），确认路径在你的venv里 - Windows 下提示“不是内部或外部命令” → 重启终端，或手动把
venv\Scripts加进当前 shell 的PATH - 用
uv管理依赖？→ 改用uv add alembic，但行为一致，仍需后续alembic init
需不需要指定版本或国内源？
一般不需要。但以下情况建议显式控制：
- 项目有兼容性要求（比如只支持 SQLAlchemy 2.0 以下）→ 用
pip install "alembic==1.13.0" - 公司内网无法访问 PyPI → 加
-i <a href="https://www.php.cn/link/29ab8937c72f36ca382c32ece8ca5595">https://www.php.cn/link/29ab8937c72f36ca382c32ece8ca5595</a> - CI/CD 流水线中追求确定性 → 在
requirements.txt里写死版本，例如：alembic==1.19.1
安装本身很简单，真正容易卡住的地方是下一步：怎么让 alembic 找到你的数据库模型和 SQLAlchemy 引擎。那个环节出错，很多人误以为是安装失败。
