Last modified 4 years ago Last modified on 11/18/09 16:49:39

Super Quick South Guide!


  • You already have a Django application with a database.
  • You have heard of wonders of South
  • You are getting sick of writing SQL migration scripts by hand!
  • You promise to read the full tutorial later on!

What is South?

  • South is a tool for Django that tracks changes in your models.
  • South changes your database to reflect the changes in your models

If you are doing anything useful, you are probably crying for a tool like this. Read on!


  1. Download & Put on Python path
  2. Add to installed apps in
  3. Run ./ syncdb to make South's history-tracking table.

1. Set up every application to be trackable by South

For every application in your project, do the following:

    python convert_to_south <app_name>

2. Every day use

As you develop, you will be using these two commands for your interactions with South.

python startmigration <app_name> <migration_name> --auto
python migrate 

startmigration is a command that introspects your models and determines the corresponding database schema. Then, the changes and current model structure get recorded in the migrations file.(More on this later)

--auto is a flag that you should use most of the time to automatically determine the changes between the last South migration and the current state of your models.

migrate is a command that applies changes in your migration scripts to the database.

3. (optional) Make a tiny change and see what happens

For now, just add a new column in any one of your models and run your favorite commands from step 2.

In the migrations folder (that lives in your app folder), South creates files of form #_<migration name>.py e.g. These files contain 3 important sections.

  • forward() method contains the code required to sync the database with the current state of the models.
  • backwards() method rolls back the changes created with forward().
  • 'Freeze' section of the file that describes the structure of the model and every model it is related to.

migrate command simply applies the changes described in forward() to the database.

That's it!

Now what you really need to do is read the full tutorial!
And, don't forget to read about how to use South in a team setting.