Installing oTree

Important note

If you publish research conducted using oTree, you are required by the oTree license to cite this paper. (Citation: Chen, D.L., Schonger, M., Wickens, C., 2016. oTree - An open-source platform for laboratory, online and field experiments. Journal of Behavioral and Experimental Finance, vol 9: 88-97)

Command line basics

To use oTree, you need to use PowerShell (Windows) or Terminal (Mac). In this documentation, we refer to these programs as your “command prompt” or “command line”.

A few tips:

  • You can retrieve the previous command you entered by pressing your keyboard’s “up” arrow
  • If you get stuck running a command, you can press Control + C.
  • In PowerShell, you should right-click to paste a command.

Install Python

New versions of oTree require Python 3.4 or higher. If you created an old oTree project with Python 2 and would like to migrate to Python 3, follow the instructions here.

If you already have Python 3.6 installed (check by entering pip3 -V at your command prompt), you can skip the below section. Or, uninstall your existing version of Python, and proceed with the below steps.

Install Python 3.6 (Windows)

Download and install Python 3.6. (Python 3.4 and 3.5 are also OK.) Check the box to add Python to PATH:


Once setup is done, open PowerShell and enter:

pip3 -V

It will output a line that gives the version of Python at the end; this should match the version of Python you just installed.

Install Python 3.6 (Mac OSX)

You should install Python 3.6

Although Mac OSX comes pre-installed with Python, it is version 2.7, which is not supported by oTree. You should install Python 3.4 or higher. We recommend installing it with Homebrew. (However, if you already have Python 3.6 installed through Conda, that should be OK.) To install Python 3 via Homebrew:

  • Open your Terminal and run:
xcode-select --install

When prompted, select to install the “command line developer tools”.

ruby -e "$(curl -fsSL"
  • Update your PATH variable to state that homebrew packages should be used before system packages:

    echo "export PATH=/usr/local/bin:/usr/local/sbin:\$PATH" >> ~/.bash_profile
  • Reload .bash_profile to ensure the changes have taken place:

    source ~/.bash_profile
  • Install python:

    brew install python3
  • Then test that it worked:

    pip3 -V

It will output a line that gives the version of Python at the end; this should match the version of Python you just installed.

Install Python (Linux/UNIX)

We recommmend installing using your system’s package manager to install Python 3.6. If Twisted fails to compile, install the python-dev package (e.g. through apt-get).

More information in the Linux server setup section.

Install oTree

pip3 install -U otree-core

Windows issue: vcvarsall.bat and Visual C++

If you get this Windows error about Twisted and vcvarsall.bat:

error: Microsoft Visual C++ 9.0 is required (Unable to find vcvarsall.bat). Get it from

To fix this, install the Visual C++ Build Tools.

Running oTree

Open PowerShell (on Windows) or Terminal (on Mac OS X), and cd to the directory where you want to store your oTree code (such as Documents).


otree startproject oTree

If it’s your first time, we recommend choosing the option to include the sample games.

Then change to the directory you just created:

cd oTree

Reset the database:

otree resetdb

(You might see a message about migrations; you can ignore that.)

Then run the server:

otree runserver


If Python crashes when you run this command, and you’re using PowerShell, try using CMD instead.

Then open your browser to You should see the oTree demo site.

To stop the server, enter Control + C at your command line. To restart the server from the command line, pressing your keyboard’s “up” arrow (this will retrieve the last command you entered), and hit Enter.

Install a Python editor (PyCharm)

You will need a text editor to write your Python code.

We recommend using PyCharm. Professional Editon is better than Community Edition because it makes Django programming easier. PyCharm Professional is free if you are a student, teacher, or professor.

Even if you normally use another text editor, we recommend at least trying PyCharm, because PyCharm’s autocompletion makes learning oTree much easier:


Once you have installed PyCharm, go to “File -> Open...” and select the folder you created with otree startproject.

Then click on File –> Settings (or Default Settings) and navigate to Languages & Frameworks -> Django, check “Enable Django Support” and set your oTree folder as the Django project root, with your and


If PyCharm displays this warning, select “Ignore requirements”:


Upgrading/reinstalling oTree

The oTree software has two components:

  • oTree-core: The engine that makes your apps run
  • oTree library: the folder of sample games and other files (e.g. that you download from here and customize to build your own project.

Upgrade oTree core

We recommend you do this on a weekly basis, so that you can get the latest bug fixes and features. This will also ensure that you are using a version that is consistent with the current documentation.


pip3 install -U otree-core
otree resetdb

Upgrade oTree library

Run otree startproject [folder name]. This will create a folder with the specified name and download the latest version of the library there.

If you originally installed oTree over 5 months ago, we recommend you run the above command and move your existing apps into the new project folder, to ensure you have the latest, etc.