Information about the Alembic project.
Alembic is hosted on GitHub at https://github.com/sqlalchemy/alembic under the SQLAlchemy organization.
Releases and project status are available on Pypi at https://pypi.python.org/pypi/alembic.
The most recent published version of this documentation should be at https://alembic.sqlalchemy.org.
While Alembic can be installed system wide, it’s more common that it’s installed local to a virtual environment , as it also uses libraries such as SQLAlchemy and database drivers that are more appropriate for local installations.
The documentation below is only one kind of approach to installing Alembic for a project; there are many such approaches. The documentation below is provided only for those users who otherwise have no specific project setup chosen.
To build a virtual environment for a specific project, first we assume that Python virtualenv is installed systemwide. Then:
$ cd /path/to/your/project $ virtualenv .venv
There is now a Python interpreter that you can access in
/path/to/your/project/.venv/bin/python, as well as the pip installer tool in
We now install Alembic as follows:
$ /path/to/your/project/.venv/bin/pip install alembic
The install will add the
alembic command to the virtual environment. All
operations with Alembic in terms of this specific virtual environment will then
proceed through the usage of this command, as in:
$ /path/to/your/project/.venv/bin/alembic init .
The next step is optional. If our project itself has a
file, we can also install it in the local virtual environment in
$ /path/to/your/project/.venv/bin/pip install -e .
If we don’t “install” the project locally, that’s fine as well; the default
alembic.ini file includes a directive
prepend_sys_path = . so that the
local path is also in
sys.path. This allows us to run the
command line tool from this directory without our project being “installed” in
Changed in version 1.5.5: Fixed a long-standing issue where the
command-line tool would not preserve the default
As a final step, the virtualenv activate
tool can be used so that the
alembic command is available without any
path information, within the context of the current shell:
$ source /path/to/your/project/.venv/bin/activate
Alembic’s install process will ensure that SQLAlchemy is installed, in addition to other dependencies. Alembic will work with SQLAlchemy as of version 1.3.0.
Changed in version 1.5.0: Support for SQLAlchemy older than 1.3.0 was dropped.
Alembic supports Python versions 3.7 and above
Changed in version 1.8: Alembic now supports Python 3.7 and newer.
Changed in version 1.7: Alembic now supports Python 3.6 and newer; support for Python 2.7 has been dropped.
User issues, discussion of potential bugs and features are most easily discussed using Github Discussions.
Bugs and feature enhancements to Alembic should be reported on the GitHub issue tracker.