Importing Initial Data

Once you’ve got Tabbycat installed, the next step is to import data for the tournament: that is, import details of teams, speakers, adjudicators and rounds. There are a few ways to do this, each with their advantages and disadvantages.

To help you decide which to choose, here’s a summary:

Method Best for Drawcard Drawback
Demonstration data Trying out Tabbycat Loads sample data in one click Not for use with real tournaments
Simple importer Small and medium-sized tournaments Easy to use Only deals with basic data
Edit database Adding data not handled by the simple importer or editing existing data Can handle all types of information Adding large amounts of data is time consuming
importtournament command Large tournaments Easier to repeat, can handle most formats of information Requires basic knowledge of how to use a command line interface
Developing your own importer Large tournaments with custom needs Easier to repeat, will take information in whatever format it is already in Requires background in Python and and learning about the importer classes

Demonstration data

If you’re just learning or experimenting with Tabbycat, there are two demonstration datasets available, each with a sample set of teams, adjudicators, etc., so that you can immediately start running rounds. Just be aware that these probably won’t relate to anyone at your real-life tournament.

To load a demonstration dataset, click New Tournament link on the home page (once logged in as admin). You’ll see a page titled “Create New Tournament”. Scroll to the bottom of this page and click on one of the links at the bottom.

Simple importer

The simple importer is the easiest way to get a tournament going, and we recommend it for small- and medium-sized tournaments. It allows you to add institutions, teams, adjudicators, venues, venue categories and venue constraints. (If you need to add anything else, use the Edit Database area instead.)

To get started, create a new tournament using the New Tournament link on the home page (once logged in as admin). It’ll ask you for a few basic pieces of information.


Then, once you’re in your tournament, click Setup in the left-hand menu, then Import Data, to open the simple importer.


You first need to add institutions. Once institutions are added, you can then add teams and adjudicators in the relevant sections. Each of these is a two-step process:

  • For institutions and venues, it will first ask you to copy-paste a list of names and properties in a comma-separated table format. The second step is to confirm individual fiels.
  • For teams and adjudicators, it will first ask you how many teams/adjudicators to add for each institution (or who lack an institutional affiliation). The second step is to fill in their details, for example, names.
../_images/add-institutions.png ../_images/add-teams-1.png ../_images/add-teams-2.png

Finally, if you would like to use venue categories and/or venue constraints, you can do so using the two last sections of the simple importer.


If copying and pasting from a spreadsheet, an easy way to make a comma-separated table is to save a spreadsheet with the relevant information as a *.csv file, then open this file in a plain text editor (such as Notepad or TextEdit), and copying it from there.

Editing the database

Sometimes, the simple importer just isn’t enough—whether because you need more customization than the simple importer handles (e.g. adjudicator feedback questions), or because some participants changed their details after you imported the inital data. In this case, the easiest thing to do is to edit the database via the Django administrative interface (under Setup > Edit Database).

The general pattern goes like this: Go to Setup > Edit Database, find the type of object you wish to add/change, and click “Add” or “Change”. Then, fill in what you need to and save the object.


The Edit Database area is very powerful, and naturally if you mess things up, you can insert potentially catastrophic inconsistencies into the database. For participant information this is hard to do, but it’s worth keeping in mind.

The importtournament command

We’ve written a management command called importtournament to help automate the tournament set-up. The script, however, is neither foolproof nor comprehensive, so you might find you need to modify things slightly if your tournament structure is different from ours. Be prepared to try this a few times to get it to work. Nonetheless, this is probably the fastest way to set up a tournament.

  1. Copy and rename the data/demo folder
  2. See the CSV files in the new folder, and add/replace the data as per your tournament. Note that the institutions (i.e. first column) in the speakers.csv and adjudicators.csv files must match the institutions in the second column of the institutions.csv file. And that all CSV files must end with a blank line.
  3. Use this command, replacing YOUR_DATA_DIR with your new folder’s name. (Square brackets indicate optional arguments; if you use them, omit the square brackets. All of them relate to the name of your tournament.)
$ ./ importtournament YOUR_DATA_DIR [--slug SLUG] [--short-name SHORT_NAME] [--name FULL_NAME]

This script has a number of options. They’re worth taking a look at before you run the script. For details, see:

$ ./ importtournament --help
  1. Assuming the command completes successfully without errors, you should double check the data in the Django interface, as described above in Editing the database. In particular you should check that the Rounds have the correct draw types and that silent rounds have been marked correctly.


Currently the importtournament command cannot add Adjudicators or Teams without an institutional affiliation. However, these can be imported with the Simpler Importer or edited in the Database area.

importtournament on Heroku installs

The importtournament script can be run on Heroku directly; you just need to commit and push your new data directory to your server first. See Installing on Heroku for details. If you have a local installation ready, you might like to iron out all the errors in your data until you can import locally without error, before pushing your data files to your server to be imported there.

If you want to import locally and push the database to the server, you can use the heroku pg:push command. We assume that, if you want to use this method, you know what you’re doing or are comfortable reading the Heroku documentation to find out. We’re happy to help if you have questions about this, but for most tournaments, committing the data to the server and running the script on the server directly will be easier.

Developing your own importer

If our suggested file formats cause you headaches, it might be easier to write your own importer. We have a generic importer framework that should make this easier, so for some tournaments it might (very conceivably) be faster to write your own importer to conform to your data, than it is to make your data conform to our importer. You need a background in Python in order to do this. For more details, see Tournament Data Importers.