Misago: a Django forum that ships the moderation tools most forums bolt on later

What Misago is for, and who should care

Misago is a forum application, not a library you import into an existing Django project. The setup.py description calls it a "modern, fully featured forum application written in Python and ES6, powered by Django and React.js," and the README says it "works out of the box and can be run alone or be connected to existing site with built in OAuth 2 client." That second half matters. If you already run a Django site and want a forum attached to it rather than a separate login silo, the OAuth2 client and JSON API are the intended bridge.

The audience is a site operator or a developer who has decided a forum is the right shape for their community and does not want to assemble moderation queues, ban systems, read tracking and permission rules from scratch. The README lists those as shipped features, along with private threads, polls with public or private voters, attachments with thumbnailing, best-answer marking, and an edits log with revert. None of that is exotic for forum software. The difference is that it is already wired into Django's admin, auth and permissions rather than sitting beside them.

The README also states the development status plainly: "Bananas," linking to the Wikipedia article on perpetual beta. That is the author's own framing, and it should shape how you read everything else on this page.

How the pieces fit: Django, React, Celery and Postgres

The architecture is visible in the repository layout and the compose file rather than described in prose. The backend is Django 5.2.15 per requirements.txt, with djangorestframework for the JSON API and ariadne plus ariadne-django for GraphQL tooling that is already in the dependency list. Celery with Redis is a hard dependency, and the compose file runs a separate celery-worker service with the command celery -A devproject worker --loglevel=info. So background work is not optional plumbing you can skip: the development setup expects a worker process alongside the web process.

The frontend is split in two. The README says that "with exception of Admin Panel, Misago frontend relies heavily on React.js components backed by Django API," built with webpack. Admin assets live in misago-admin and are deployed to misago/static/misago/admin on build. That split has a practical consequence: if you plan to restyle the public forum, you work in frontend and rebuild assets; if you plan to restyle the admin, you work in a different directory entirely.

Categories use django-mptt, which is the standard Django approach to tree structures and explains the README's promise of unlimited subcategory depth. Plugins load from a directory controlled by the MISAGO_PLUGINS environment variable, set to /app/plugins in the Dockerfile, and the image runs ./dev bootstrap_plugins during build. The README lists a plugin system as a future feature, so treat the plugins directory as an existing mechanism with an unfinished story rather than a documented extension API.

Installing Misago with Docker and reaching the admin panel

The README gives Docker as the preferred path for development instances, and the compose file carries a blunt header comment: "This compose setup is only meant for local development of Misago itself. This is not for running your Misago site in docker." The Dockerfile repeats the warning and points at a separate misago-docker project for production. Read that before you build anything you intend to expose to the internet.

Start by cloning the repository and running the bundled dev utility. According to the README, this builds the containers, installs Python dependencies and initializes the database.

./dev init
docker compose up

After the server starts, the README says to visit http://127.0.0.1:8000/ for the forum and http://127.0.0.1:8000/admincp/ for the Admin Control Panel, logging in with the username Admin and the password password. Those credentials come from the SUPERUSER_USERNAME, SUPERUSER_EMAIL and SUPERUSER_PASSWORD environment variables in docker-compose.yaml. The compose file maps port 8000 with a fallback, ${MISAGO_DEVSERVER_PORT:-8000}:8000, so you can move the host port if 8000 is taken.

If you would rather not use the dev script, the README documents the manual sequence: build the containers, run migrations, create a superuser, then start the server.

docker compose build
docker compose run --rm misago python manage.py migrate
docker compose run --rm misago python manage.py createsuperuser
docker compose up

For frontend work, package.json defines the asset tasks. The README describes npm run build as the production build that bundles and minifies JavaScript, CSS and images into misago/static/misago, and npm run start as a quicker non-minified build that rebuilds when less or js files change. The README warns that no test suite exists for the source JavaScript files, so changes there carry more risk than changes elsewhere.

Where Misago will cost you time

The API is the biggest open question. The README lists "Replacing current API with GraphQL API for easier integrations and extending" among features that will follow in future releases, while requirements.txt already pulls in ariadne and ariadne-django. If you build an integration against the JSON API today, you are building against something the project has publicly said it intends to replace. That is not a reason to avoid Misago, but it is a reason to keep the integration thin.

The frontend warning is the second cost. The README states that "special care should be taken when changing source JavaScript files as no test suite for those exists." A React codebase with no test suite means every theme change is verified by hand. If your plan involves deep frontend customization, budget for that.

Production deployment is the third. Neither the Dockerfile nor docker-compose.yaml is meant for it, and both say so. The compose file also runs the Django development server via python manage.py runserver, which is not a production WSGI setup. You will need to supply your own serving stack, and the repository does not document one here.

Finally, the beta label is not decoration. A project that describes itself as perpetual beta can change behavior between releases, and the release history shows gaps: 0.39.4 in August 2025, then 0.39.5 and 0.39.6 in mid-2026. If your forum is load-bearing for a business, plan upgrades as events to test rather than background chores.

Misago compared with a Django forum plugin

The realistic alternative for a Django shop is not another standalone forum product. It is a forum plugin that mounts inside the Django project you already run, sharing its settings module, its deployment and its user table. That approach wins on operational simplicity: one process tree, one database migration history, one admin.

Misago takes the opposite stance. It ships its own project layout, its own manage.py, its own devproject settings package and its own Docker workflow. The payoff is that everything in the README's feature list is integrated with everything else. Permissions key off ranks, roles and categories together. The moderation queue, the ban system and the read tracker share the same user model. A plugin bolted onto an existing site tends to grow these features one at a time, and the seams show in exactly the places forums get painful: who can see an unapproved reply, and who can move a thread between categories without losing read state.

The trade is control. With Misago you adopt its opinions about user accounts, its admin panel and its upgrade cadence. If your site's identity model is unusual, the OAuth2 client and JSON API are the sanctioned integration points, and the README does not describe a supported way to graft Misago's forum tables onto a foreign user model.

Licence and the maintenance you are signing up for

Misago is GPL-2.0. setup.py declares license="GPLv2" and the classifier "License :: OSI Approved :: GNU General Public License v2 (GPLv2)." The practical point for a self-hosted forum is that running it does not oblige you to publish anything, but distributing a modified Misago, or shipping a derivative work, brings the GPL's source obligations into play. That is a general property of the licence, not legal advice, and if you plan to redistribute a customized Misago you should have someone qualified read the terms.

Maintenance looks current. The repository is not archived, and the last push was on 2026-09-23, days before this writing. Releases are less regular than that suggests: 0.39.4 landed on 2025-08-09, 0.39.5 on 2026-05-29 and 0.39.6 on 2026-06-19. So the codebase moves between releases while tagged versions arrive in bursts. Pin a release tag rather than tracking main if you want reproducible deploys.

Upgrade cost is dominated by Django. requirements.txt pins django==5.2.15, so a Misago upgrade may pull a Django major or minor with it. The repository ships pytest.ini and a coverage badge, which means the Python side has a test suite to lean on, but the README's own note about untested JavaScript means frontend regressions are caught by eye. Before upgrading, check whether your custom theme touches files under frontend, and rebuild assets with npm run build afterward.

Editorial conclusion

Adopt Misago if you want a Django-native forum with moderation, permissions and GDPR controls already in the box, and you accept beta status plus a Docker-based workflow. Do not adopt it if you need a stable API contract, since the README says the current API is to be replaced with GraphQL, or if you want a turnkey production image, because the repository's Dockerfile and docker-compose.yaml are explicitly for local development only. Verify first that your Python version matches the 3.12 requirement in setup.py and the Dockerfile, then run ./dev init and confirm the admin account works at /admincp/ before planning anything else.

Frequently asked questions

Official sources

1. License: GPL-2.0
2. Project website
3. rafalp/Misago on GitHub
4. README
5. Releases