Written and maintained by CASRAI Editorial Board
Published
On this page
oTree is an open-source, Python-based framework for building multiplayer strategy games such as the prisoner’s dilemma and auctions, controlled behavioral experiments in economics and psychology, and surveys and quizzes. Researchers write an experiment once as a set of apps, pages and rules, run it on a web server, and let participants take part through an ordinary web browser, in a laboratory or online.
What is oTree?
The oTree documentation describes the framework as a tool for multiplayer games, controlled experiments and surveys, and the project’s home page says it can be used to build any kind of task or interaction. Its example library includes MaxDiff tasks, the Stroop task, poker, the prisoner’s dilemma and surveys. The project site lists organisations such as the World Bank, the OECD, the IRS and the Behavioural Insights Team among its users, reports more than 3,000 publications that used it, and names the Alfred P. Sloan Foundation as a funder.
The package is published on PyPI under the summary “Framework for multiplayer strategy games and complex surveys”, with an MIT License in its metadata, and is installed with pip. The current PyPI release at the time the metadata was read was 6.0.15. The oTree documentation also points to oTreeHub, which hosts demos, a forum, and OTAI, a chat interface for building apps without writing code.
For a research office or a methods course, the practical meaning is this: oTree is a software environment for implementing the designs described in behavioral economics and its neighbouring fields, where participants make incentivised decisions, often interacting with one another, and the researcher needs exact control over what each participant sees and when. Published results from this kind of work are discussed in venues such as those profiled in Journal of Experimental Economics.
Core concepts: sessions, subsessions, groups, players and participants
oTree organises every experiment around a fixed vocabulary, and the vocabulary maps directly onto research-design terms. According to the conceptual overview in the documentation, a session is a series of subsessions. A subsession is a section or module of the session, made up of a sequence of pages. A group is a division of the players within a subsession, such as pairs or teams, and groups can be reshuffled between subsessions. A player is described as a temporary role played by a participant, while the participant persists across the whole session. The data table below sets out these terms, the documentation’s wording, and what each means for a study design.
How the hierarchy maps onto a research design
The distinction between a participant and a player is the part newcomers most often miss. A participant is the person. A player is the role that person occupies in one subsession. In a repeated game the same participant therefore appears as a different player object in every round, because, as the documentation states, each round of a repeated game is its own subsession with its own subsession, group and player objects. This has a direct data-structure consequence: a value stored on the player in round 1 is not visible on the player in round 2.
The documentation gives two ways to carry data forward. Within one app, methods such as in_previous_rounds(), in_all_rounds(), in_rounds() and in_round() return the same participant’s player objects from other rounds. For example, in the last round of a 10-round game, in_previous_rounds() returns a list of 9 player objects, and in_all_rounds() returns 10 because it includes the current round. Across apps, data should be stored on the participant object using fields declared in the PARTICIPANT_FIELDS setting. The documentation also notes that the in-round methods are not meaningful for groups when groups are re-shuffled between rounds.
Apps and rounds
An oTree app is a folder of Python and HTML code, and a project contains several apps. A session is essentially a sequence of apps played one after another, set through the app_sequence in the session configuration. Rounds are set with NUM_ROUNDS. The documentation’s own example: if app_sequence is app1 followed by app2, app1 has three rounds and app2 has one, the session contains four subsessions. Round numbers start from 1 and are available as round_number.
Treatments, pages and timeouts
The documentation’s table of contents groups the remaining building blocks: models (the data fields recorded for each player, group and subsession), pages (including wait pages that hold a participant until others have finished, and randomized page sequences), templates and forms for what participants see and enter, treatments for assigning different conditions, timeouts, and live pages for real-time interaction. Mapping them to design language, treatments are how a between-participant manipulation is implemented, repeated rounds implement within-participant repetition, and wait pages are how synchronous multiplayer interaction is enforced.
Build, test and deploy workflow
A practical oTree project moves through four stages. These stages are an editorial summary of the documentation’s structure rather than a prescribed procedure from the oTree authors.
- Design the structure. Decide the session’s apps, the number of rounds, the group size and how groups form, and which treatments exist.
- Implement. Define the data fields in models, the sequence of pages, and the templates and forms that collect responses.
- Test with bots. Use bots to simulate participants before any real participant sees the study.
- Host and run. Choose a server setup and open the session to participants.
Testing with bots
Per the documentation, bots simulate participants playing your app: they click through each page, fill out forms and check that everything works. To run them, add test code to the app, set use_browser_bots=True in the session config, run the server, create a session, and the pages auto-play once the start links are opened. Test code makes one yield per page submission. A page with no form is submitted by name, and a page with form fields is submitted with a dictionary of values. If a bot submits invalid input, or submits pages in the wrong order, the test system raises an error.
Bot code plays one round at a time and oTree runs it NUM_ROUNDS times. Conditional logic can depend on the player, group or round number, for example giving only the first player in a group the offer page. Wait pages are ignored when writing bots. The expect() statement checks that a value is what the researcher predicts, with operators such as less than, equal, in and not in, and SubmissionMustFail() checks that form validation correctly rejects invalid input, such as two numbers that must add up to 100. For a research team this means the incentive arithmetic and validation rules of a design can be checked before data collection begins.
Hosting options
The documentation’s server-setup section covers deployment on Heroku, on Ubuntu Linux and on Windows Server. The documentation also lists admin, rooms, and MTurk and Prolific integration as separate topics, which is relevant when participants are recruited online rather than in a lab. The choice of host is an institutional decision: data location, retention and access rules for participant data sit with the researcher’s ethics approval and data-management plan.
Licence and versions
PyPI lists the package under the MIT License and reports version 6.0.15 when the metadata was read. The documentation’s history lists releases from 5.0 through 6.0, and it mentions variants such as oTree Lite. Because the software has changed across major versions, a methods section should name the exact version used. That is an editorial recommendation, but it follows the same reasoning that applies to any research software: results that depend on code are reproducible only when the code version is recorded.
Reporting and citing oTree in research
Reporting an oTree experiment is mostly reporting the design, not the tool: the structure of the session (apps, rounds, group size and matching), the treatments and their assignment, the incentives, the version of oTree used, and the hosting setup. Sharing the app code alongside the data lets others replicate the exact flow of pages, and the code makes the assignment mechanism inspectable. Researchers who go on to analyse such data with causal methods may also want the DoWhy causal inference guide; those who model processes by simulation can compare SimPy. When a paper reports that oTree was used, cite the software as the oTree project asks and state the version. The project’s own pages are the place to confirm the current citation request.
Common mistakes with oTree designs
- Expecting a value set in one round to appear in the next. Each round has separate objects, so use the in-round methods or participant fields.
- Using in_rounds-style group lookups after re-shuffling groups, which the documentation says does not make sense.
- Skipping bot tests. Bots exist so that page order, validation and payoff logic fail in testing, not in front of participants.
- Failing to record the oTree version, hosting arrangement and session configuration in the methods section.
Sources
- oTree documentation, home page (read 2026-11-18)
- oTree documentation, conceptual overview (read 2026-11-18)
- oTree documentation, apps and rounds (read 2026-11-18)
- oTree documentation, bots (read 2026-11-18)
- oTree project site (read 2026-11-18)
- otree on PyPI (read 2026-11-18)
Data: oTree core concepts: documentation definitions and research-design meaning
Compiled from the oTree documentation's conceptual overview and apps and rounds pages: each core object, how the documentation defines it, and what it corresponds to in an experimental design.
| oTree term | Documentation definition | Research-design meaning |
|---|---|---|
| Session | A series of subsessions; also a sequence of apps played one after another | One complete run of the experiment with a set of participants |
| Subsession | A section or module of the session, made up of a sequence of pages; each round is its own subsession | One stage or one round of a repeated game |
| Group | A division of players within a subsession, such as pairs or teams; can be reshuffled between subsessions | The matching structure for interacting participants |
| Player | A temporary role played by a participant; separate objects in each round | A participant's role and recorded data in one round |
| Participant | Persists across the whole session and across apps | The person; the unit that carries data across rounds and apps |
| App | A folder of Python and HTML code; a project contains multiple apps | A task or module, such as a game followed by a survey |
Sources
- oTree documentation, conceptual overview (accessed 2026-11-18)
- oTree documentation, apps and rounds (accessed 2026-11-18)
Compiled by CASRAI from the sources above. Free to reuse under CC BY 4.0 with attribution.







