Skip to main content
v2026.11,986 entries · CC-BY 4.0

oTree: Python Framework for Behavioral Experiments

oTree is an open-source Python framework for multiplayer games, behavioral experiments and surveys; learn its session model, bot testing and hosting.

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.

  1. Design the structure. Decide the session’s apps, the number of rounds, the group size and how groups form, and which treatments exist.
  2. Implement. Define the data fields in models, the sequence of pages, and the templates and forms that collect responses.
  3. Test with bots. Use bots to simulate participants before any real participant sees the study.
  4. 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

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 core concepts: documentation definitions and research-design meaning
oTree termDocumentation definitionResearch-design meaning
SessionA series of subsessions; also a sequence of apps played one after anotherOne complete run of the experiment with a set of participants
SubsessionA section or module of the session, made up of a sequence of pages; each round is its own subsessionOne stage or one round of a repeated game
GroupA division of players within a subsession, such as pairs or teams; can be reshuffled between subsessionsThe matching structure for interacting participants
PlayerA temporary role played by a participant; separate objects in each roundA participant's role and recorded data in one round
ParticipantPersists across the whole session and across appsThe person; the unit that carries data across rounds and apps
AppA folder of Python and HTML code; a project contains multiple appsA task or module, such as a game followed by a survey

Sources

Compiled by CASRAI from the sources above. Free to reuse under CC BY 4.0 with attribution.

Follow CASRAI

Research-administration guidance, standards updates and independent tool reviews.

Ask CASRAI · free to try

Ask about oTree: Python Framework for Behavioral Experiments

2 free questions a day, no account.

An AI assistant for research: funder rules, compliance, methods and publishing. It links the sources behind its answers and labels answers that come from a web search.

Answers draw on CASRAI's guides and dictionary plus the federal and funder documents we index: Federal Register, Grants.gov, Regulations.gov and UKRI.

Works on this site and inside Claude, Cursor and the AI tools you already use.

Everything CASRAI publishes — this page, the dictionary, the guides and the news — stays open to read, with no account and no card.

Referenced across the research world

University of Cambridge logoColumbia University logoCrossref logoUniversity of Edinburgh logoHarvard University logoUniversity of Oxford logoPrinceton University logoStanford School of Medicine logoUniversity College London logoORCID logoUniversity of Cambridge logoColumbia University logoCrossref logoUniversity of Edinburgh logoHarvard University logoUniversity of Oxford logoPrinceton University logoStanford School of Medicine logoUniversity College London logoORCID logo
  • University of Cambridge logo
  • Columbia University logo
  • Crossref logo
  • University of Edinburgh logo
  • Harvard University logo
  • University of Oxford logo
  • Princeton University logo
  • Stanford School of Medicine logo
  • University College London logo
  • ORCID logo

View CASRAI adoption →