Front Matter — Alembic 1.8.1 documentation

# 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.