Installing oTree on macOS


If you want to try the beta of oTree Studio, which is a simplified graphical interface for creating oTree apps, sign up on oTree Hub and click the link “Studio” in the upper right corner of the page. (Heroku sign up is not necessary.)

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)

If the below steps don’t work for you, please email with details.

Step 1: Install Python

  • Download and install the latest Python.
  • In Finder, search for and open the “Terminal” app:
  • Enter:

    /Applications/Python\ 3.6/Install\ Certificates.command

    (if you are using Python 3.7, you should change the 3.6 to 3.7.)

Step 2: Install oTree

Enter this:

pip3 install -U otree

Step 3: Run oTree

Create your project folder:

otree startproject oTree

When it asks you “Include sample games?” choose yes.

Move into the folder you just created:

cd oTree

Run the server:

otree devserver

Open your browser to http://localhost:8000/. You should see the oTree demo site.

To stop the server, press Control + C at your command line.

Step 4: Install a Python editor (PyCharm)

Install PyCharm, which you will use for editing your Python files.

After installing, open PyCharm, go to “File -> Open...” and select your project folder.

Then click on PyCharm -> Preferences, and click through the following steps:

  • “Project -> Project interpreter”
  • Click the “gear” icon
  • Add...
  • System Interpreter

And set it to the location of your Python executable, something like: /Library/Frameworks/Python.framework/Versions/3.6/bin/python3.6). Once it’s configured, the imports at the top of an app’s should look like this , not this.

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


PyCharm’s autocompletion makes learning oTree much easier:


Upgrading/reinstalling oTree

We recommend you upgrade 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.

The command to upgrade is the same as the command to install:

pip3 install -U otree

If there is a problem with the upgrade, uninstall then reinstall:

pip3 uninstall otree
pip3 install -U otree