Oppia: a self-hosted platform for building interactive lessons

What Oppia is for, and who it is aimed at

Oppia is an online learning tool for creating and sharing interactive activities the project calls explorations. The README describes these as activities that simulate a one-on-one conversation with a tutor, so a learner answers a question, receives feedback, and the lesson branches based on that answer rather than playing a fixed sequence of slides. That branching model is the whole point: it is aimed at authors who want a lesson to react to the learner, not at people who want to publish a video or a PDF.

The repository is not just the platform. The team also publishes free lessons on basic mathematics, with the README naming a fractions lesson at oppia.org/fractions and stating that basic science and financial literacy are planned. The stated audience is learners who lack appropriate access to educational resources, which is why the project is a nonprofit effort with a donation link rather than a commercial product.

For an engineer, the practical framing is this: Oppia is the software you would self-host or deploy if you wanted to run your own instance of that authoring and delivery system, or if you wanted to contribute to the public instance. It is not a library you import into an existing application.

Architecture: Python, Angular and App Engine in one repository

The README states the web application is built using Python, Angular, and Google App Engine. The top-level layout matches that description. There is a core/ directory, an extensions/ directory, a src/ directory, and top-level Python entry points including main.py. On the front end, angular.json and tsconfig-strict.json sit alongside package.json, and package.json lists Angular CLI and Angular build tooling among its devDependencies.

Deployment configuration is visible at the top level: app_dev.yaml, cron.yaml, index.yaml, .gcloudignore and .firebase.json. The presence of cron.yaml and index.yaml points to scheduled jobs and datastore indexes as part of the runtime, which is characteristic of an App Engine application rather than a plain WSGI service. A redis.conf file is also present, so a Redis instance is part of the development or production topology.

Dependency management is split in a way worth understanding before you fork. requirements.txt is auto-generated by pip-compile with hashes and carries a header telling developers not to edit it, but to change requirements.in and regenerate. The same pattern applies to requirements_dev.in and requirements_dev.txt. The build also produces a Python package: setup.py states it builds a package used by Google Cloud Dataflow workers running Apache Beam, and apache-beam appears in requirements.txt. That means part of this codebase exists to run batch jobs on Dataflow, not to serve web requests.

Quality tooling is unusually dense for a project of this kind: mypy.ini, .pylintrc, .isort.cfg, .eslintrc, .stylelintrc, .htmllintrc, .prettierrc.json, tox.ini, pytest.ini and conftest.py. pyproject.toml configures black with a line length of 80 and skip-string-normalization set to true. Expect a contribution to be checked against all of that.

Installing Oppia and starting a first exploration

The README does not contain install commands. It says: "Please refer to the Installing Oppia page for full instructions," linking to the wiki page github.com/oppia/oppia/wiki/Installing-Oppia. That page is the only authoritative source for setup steps, and the exact commands, supported Python version and required services should be taken from it rather than guessed. What the repository does tell you is the shape of the toolchain you will need.

The dependency files show the Python side is pinned and hashed, and that pip-compile is the tool used to regenerate them. If you are preparing a machine, the regeneration workflow documented in requirements.in is the pattern the project expects:

pip-compile --generate-hashes --no-emit-index-url --output-file=requirements.txt --strip-extras requirements.in

Running that command regenerates requirements.txt from requirements.in. You should not hand-edit requirements.txt; its own header says so.

On the front end, package.json declares the project name as oppia and the version as 3.5.2, matching the most recent release listed for the repository. Angular CLI is a devDependency, so front-end builds go through the Angular toolchain configured in angular.json. The package.json test script is a placeholder that exits with an error, which tells you tests are not run through npm test.

{
  "name": "oppia",
  "version": "3.5.2",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "license": "Apache-2.0"
}

That snippet is the top of package.json, reproduced to show the declared version and the fact that the test script is not wired up. Test execution is configured elsewhere, through pytest.ini, tox.ini and conftest.py.

Once a local instance is running, the first real use is authoring rather than coding: you create an exploration and add states, each with content and a question, then define the destinations a learner reaches depending on their answer. The README frames this as simulating a one-on-one conversation with a tutor. The user documentation at oppia.github.io is the place to learn the authoring interface, and the contributors' wiki at github.com/oppia/oppia/wiki covers setting up for code changes.

Where Oppia gets awkward

The biggest constraint is the deployment target. The README names Google App Engine explicitly, and the repository carries app_dev.yaml, cron.yaml and index.yaml. If your organisation runs on a different platform, or if you want a container you can drop onto a generic Kubernetes cluster, this is not a neutral choice you can ignore. The datastore index configuration and the cron configuration are App Engine concepts, and the setup.py docstring shows a further dependency on Google Cloud Dataflow for Beam workers. Adopting Oppia means adopting a slice of Google Cloud.

The install story is the second friction point. The README delegates entirely to a wiki page, which is normal for a project of this size but means the repository alone is not enough to get running. There is no Dockerfile at the top level, and no documented one-command setup in the README.

The third issue is contribution overhead. With mypy, pylint, isort, eslint, stylelint, htmllint, prettier, black, tox and pytest all configured, plus a lint-staged hook that runs prettier on everything and black on Python files, a small patch can generate a lot of tooling feedback before it is reviewed. That is a reasonable trade for a large codebase with many contributors, but it is a real cost for a drive-by fix.

Finally, the project is a platform, not a component. If you only need a quiz widget embedded in an existing site, Oppia is the wrong shape of tool. It wants to own the authoring interface, the runtime and the storage.

How Oppia differs from H5P and static courseware

The closest comparison in the open source learning space is H5P, which packages reusable interactive content types that you embed into an existing LMS such as Moodle or WordPress. The difference in approach is where the branching logic lives. H5P content types are self-contained units you drop into someone else's page; Oppia is a full application with its own authoring interface, its own learner-facing runtime and its own storage layer, and the exploration is the top-level object rather than an embed.

That gives Oppia more control over the learner experience. A conversation that adapts across many states is natural in Oppia and awkward to express as an embedded widget. It also means you take on the whole stack: App Engine configuration, datastore indexes, cron jobs and a Python plus Angular build. With H5P you take on a plugin and a content library.

Against plain static courseware, the contrast is starker. A set of HTML pages has no feedback loop and no branching, which is exactly what Oppia exists to provide. If your material genuinely is linear, static pages are cheaper to host and cheaper to maintain, and Oppia adds nothing.

Maintenance, releases and the licence

The repository is not archived, and the last push was on 2026-09-21. Releases are tagged and versioned: v3.5.2 on 2026-07-20, v3.5.1 on 2026-04-09 and v3.5.0 on 2026-03-05. The package.json version field matches v3.5.2, so the front-end package version tracks the release tag. The default branch is develop, which means the branch you clone by default is the integration branch, not a stabilised release branch. If you want the code behind a specific tag, check it out explicitly rather than assuming develop is release-ready.

Upgrade cost is dominated by the pinned dependency graph. requirements.txt is generated with hashes by pip-compile, and the file header instructs developers to change requirements.in and regenerate rather than edit the output. Any upgrade you make should follow that same path, or you will drift from the project's own tooling. The Angular version pinned in package.json is also worth noting before you plan a front-end upgrade, because Angular major upgrades are not small.

The code is released under Apache-2.0, and the LICENSE file is at the repository root with a NOTICE file alongside it. Apache-2.0 is a permissive licence that permits commercial use and modification, and it includes an explicit patent grant. It also requires that you preserve copyright and licence notices and that you state significant changes if you redistribute modified files. The NOTICE file exists precisely because Apache-2.0 has provisions around it, so read both files before redistributing a modified build. This is a description of the licence text, not legal advice; your own counsel should confirm obligations for your distribution model.

Editorial conclusion

Adopt Oppia if you need a self-hosted authoring and delivery platform for branching lessons and you are willing to run a Python, Angular and Google App Engine stack. Do not adopt it if you want a single static HTML lesson file or a platform that installs with one package manager command. Before committing, read the Installing Oppia wiki page in full, confirm that your deployment target supports the App Engine configuration in app_dev.yaml and cron.yaml, and check whether the maintainers accept the kind of contribution or customisation you plan to make.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. oppia/oppia on GitHub
3. Project website
4. README
5. Releases