Installing and connecting

migra is written in Python and thus requires a recent version of Python to be installed. Make sure you use at least Python 3.6: migra will very soon stop supporting earlier versions (Python 2 will soon reach end-of-life anyway).

Installing migra

Install migra and necessary dependencies with the usual pip install:

pip install migra

This doesn't include the PostgreSQL driver, but you can install that separately, or at the same with:

pip install migra[pg]

If you're on zsh, you'll need quote marks, as in: 'migra[pg]'.


migra uses database URLs to specify database connections. If you're unfamiliar with these, they work very much like a URL, incorporating all the details necessary for making a database connection into one concise string.

The general form is as follows:

connectiontype://username:[email protected]/databasename?extraparam1=a&extraparam2=b

These can be left out if not necessary. For instance, if connecting locally, using your default system username and passwordless "trust" login, only a connection type and database name is required:


Note that all the slashes are still required, so there are three slashes in a row.

Alternate drivers can be specified with a + modifier to the connection type:


For further details, consult the sqlalchemy docs: This is what migra uses under the hood to do connections (via a wrapper module called sqlbag).

Background: Installing python and pip


Your operating system may include Python, but possibly not the latest version. migra will always work best with the latest stable version of Python, so ideally install the latest stable release (as specified on

On Windows/MacOS, you can use the installer from On linux, as always, this situation is more complicated: Your default OS repos often have version 2 installed by default, and if they have a separate version of Python 3 it won't be the latest one. You can add various external repos or build your own version from source. I wrote a tool called autovenv that manages multiple python versions (and virtual environments). Feel free to try it (I use it on both MacOS and linux), but it may be buggy (it isn't yet production software).


Once you have python installed you need to install pip. This too can complicated - recent python versions automatically install pip too, but often OS-managed versions do not. Check that when you run pip -V that it runs the desired Python version you have installed.

Aside: Virtual environments

python has the notion of virtual environments (often called virtualenvs or venvs) which create an isolated place to install external python packages separate from what might have already be installed by the operating system. It's generally good practice to use these when working with Python - but if you're not otherwise using Python and just need migra from the command line, these may not be worth bothering with.

Give feedback