Front Matter

Information about the Alembic project.

Project Homepage

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.

Installation

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 /path/to/your/project/.venv/bin/pip.

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 setup.py file, we can also install it in the local virtual environment in editable mode:

$ /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 alembic command line tool from this directory without our project being “installed” in that environment.

Changed in version 1.5.5: Fixed a long-standing issue where the alembic command-line tool would not preserve the default sys.path of . by implementing prepend_sys_path option.

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

Dependencies

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.

Community

Alembic is developed by Mike Bayer, and is part of the SQLAlchemy project.

User issues, discussion of potential bugs and features are most easily discussed using Github Discussions.

Bugs

Bugs and feature enhancements to Alembic should be reported on the GitHub issue tracker.