Getting Started with South (Django Database Migrations)

southIf you have worked on a project in Django, you have undoubtedly discovered that ‘syncdb’ is great at turning your ‘’ files into real database tables but not so great at taking your modified models and altering your database with the new definitions. In fact, the Django documentation is pretty clear about this: “Syncdb will not alter existing tables”.

South is a Django project which solves this problem by providing “consistent, easy-to-use, database-agnostic migrations for Django applications.” Below are the most basic steps for getting South up and running in your project.


  1. pip install south     (if you’re lucky, otherwise RTFM)
  2. add ‘south’ to your project’s INSTALLED_APPS
  3. run ‘syncdb’     (before you create your own models)
  4. note: this is the last time you’ll run ‘syncdb’


  1. create a new app and create your initial ‘’ file for it
  2. add your app to your project’s INSTALLED_APPS
  3. run ‘python schemamigration myapp –initial’      (creates your initial migration, note: those are two dashes hyphens before initial)
  4. run ‘python migrate myapp’     (uses this initial migration to create your app’s DB tables)


  1. modify your app’s file    (e.g., add a new column somewhere)
  2. run ‘python schemamigration myapp –auto’    (creates a new migration, note: those are two dashes hyphens before auto)
  3. run ‘python migrate myapp’    (applies this new migration)

That’s it, the very bare bones steps to getting up and running with South. Obviously you’ll either need to run these commands in the same directory as ‘’ or change the commands to point to it.

One last thing…


  1. vi ~/.bash_aliases    (there’s probably a better home for this, but this is where I put mine)
  2. add:
    function mig() {
        python schemamigration "[email protected]" --auto;
        python migrate "[email protected]";
  3. source .bash_aliases    (to activate the changes)
  4. now you can run ‘mig myapp’ whenever you change the model for ‘myapp’

If you want to be able to run this shell function anywhere, put the full path to your project’s ‘’ file in the function body. Otherwise, you’ll have to run it in the same directory as the relevant ‘’.

For South’s more advanced goodness, check out the documentation.

South 0.7
Django 1.2.1
Python 2.5.2.