Creating an oTree project

In oTree terminology, a project is a folder that houses your experiment. Whenever you have a new experiment, it’s advisable to create a new project and potentially install oTree specifically for that project.

1 Don’t worry; moving parts(apps), like specific tasks, can be transferred from one project to another but this is for a later chapter.

In many software you may be accustomed to typically install the software separately from the project and you open your project files using that software. In oTree, oTree sofwtare is attached to the project somehow and should be installed each time you create a new project. This difference may be a bit confusing, but once you get the hang of it, you’ll see how is it convenient.

How to Create a New Project

  • First, open a terminal (or command prompt) window.
  • Navigate to the folder where you wish to create your new project. Generally, this folder will contain two essential items:
    • Your project files (template generated by oTree)
    • A virtual environment (a folder containing all the packages required for your project)

While your virtual environment can reside anywhere on your computer, it’s convenient to have it in the same folder as your project files so you don’t have to search for it each time. For more details, refer to the section on virtual environments, .

Step-by-step Instructions

  1. Open your terminal. Create a new parent folder for your oTree project and virtual environment.

    mkdir myexperiment

  2. Navigate into this folder.

    cd myexperiment

  3. Create a virtual environment inside this folder 

    python3 -m venv venv

    (Try python instead of python3 if you get an error)

2 The first part of the command (python3 -m venv) tells python to use the virtual environment module to create a new virtual environment. The second part (venv) is the name of the folder that will be created. You can name it anything you want, but venv is a common convention. For instance python3 -m venv mybeautifulvenv would create a virtual environment named mybeautifulvenv.

  1. Activate your virtual environment.

    For Mac/Linux:

    source venv/bin/activate

    For Windows:

    venv\Scripts\activate

  2. Install oTree in your virtual environment.

    pip install otree

  3. Create a new oTree project.

    otree startproject otreetest

    You will be prompted to include sample games. You can press ‘y’ and Enter to include them. (If you get some errors, try it once again but this time say no to the sample games instead.)

  4. Navigate to your project folder.

    cd otreetest

  5. Run your project.

    otree devserver

    You should see output similar to this:

    Open your browser to http://localhost:8000/
To quit the server, press Control+C.

    If you see this, your oTree server should be running locally until you stop it (Ctrl+C) or close the terminal.

  6. Go ahead and test it! Open a browser and navigate to http://localhost:8000. Explore the menus and try to understand their functionalities.

Installing a Specific Version of oTree

Sometimes you may want to use a specific version of oTree. For example, you might need to reproduce an experiment or require a particular feature.

To create a project using a specific version of oTree, specify the version number when installing oTree in your virtual environment. For instance, to install oTree version 3.3.10, execute the following command during step 5:

pip install otree==3.3.10

Common Errors

Error: python3: command not found and python: command not found

This indicates two things: either you don’t have python installed or it’s not in your path (meaning your terminal don’t know where python is installed). Try to install/reinstall Python (if you see an option like “Add to PATH”, make sure to check it) If that doesn’t work, you need to add python to your path manually.

You can google “add python to path” and you’ll find many tutorials. Here’s one for Windows:

and for mac: