Evennia: the Python framework for building MUD and text multiplayer games

What Evennia handles so your game code does not have to

Evennia solves the infrastructure problem that every online text game developer hits before writing a single room description or command parser. Multiplayer text games require persistent network connections, a command dispatch system, database persistence for game objects, session tracking across reconnects, and a way for players to connect through either a traditional MUD client or a web browser. Writing that layer from scratch is months of work before your actual game starts.

Evennia provides all of it as a Python library. Game creators write normal Python modules that the server imports at runtime. There is no special language or domain-specific scripting system to learn: it is standard Python code throughout. The project supports the major text game variants, covering the conventions of MUD, MUSH, MUX, MUCK and MOO formats, but it does not enforce any particular one of them.

No style, genre or mechanic is imposed: combat rules, room layouts, player advancement and dialogue trees are all yours to design and implement from blank Python files. The framework supplies the server infrastructure, not the content. That combination is the main appeal for a developer who already knows what game they want to build, and the main limitation for anyone expecting a usable starting point with rooms or characters already in place.

Django and Twisted as two coordinated processes sharing a database

Evennia runs two distinct processes that coordinate through a shared database. Twisted handles the asynchronous network layer, keeping alive the persistent connections that text game players expect: telnet on port 4000 for traditional clients, and WebSocket connections for the browser-based web client. Django handles the web application side: the game website that Evennia creates automatically, the administration interface, and the ORM that persists every game object.

This division has a practical consequence. A slow Django page request does not interrupt active player connections on the Twisted side, because the two processes do not share a thread pool. The Twisted process handles the time-sensitive game loop on its own schedule.

The classifiers in pyproject.toml list both "Framework :: Django" and "Framework :: Twisted", confirming that neither is optional at the architecture level. The browser client at port 4001 connects to the same game server via WebSocket that a telnet client reaches on port 4000. From the game's perspective, the transport is different but the player is the same entity. Splitting the network and web layers this way is an architectural choice with a cost: operating two coordinated processes is more to monitor and debug than a single server.

Four commands from pip install to a running game on two ports

Evennia is published on PyPI. Installing it takes one command:

pip install evennia

On Windows, the README specifies that users should run `py -m evennia` once after installation to set up the Windows launcher. The Python version note in the same section is discussed below.

After installation, four commands produce a running game server:

evennia --init mygame
cd mygame
evennia migrate
evennia start

The `--init` command creates the mygame directory with the game's Python package structure, a settings module, and default configuration. The migrate step applies Django's database migrations, setting up the tables that both the framework and your game modules will use. Once evennia start completes, browsing to `http://localhost:4001` opens the web client. Pointing a third-party MUD client at `localhost` port `4000` reaches the same game world through the telnet interface. The README lists the server management subcommands as start, stop and reload, all accessed through the evennia command in the same game directory.

The README Windows note says 3.11 but pyproject.toml requires 3.12

Reading the README Windows installation note alongside pyproject.toml reveals a conflict that is easy to miss. The README advises Windows users with multiple Python versions to prefer `py -3.11` when creating virtual environments, rather than calling `python` directly. But pyproject.toml sets requires-python = ">=3.12". The classifiers in the same file list Python 3.12, 3.13 and 3.14. Python 3.11 appears nowhere in them.

This is not a subtle difference. The documentation points to a version that the package metadata does not support. A pip resolver that enforces the requires-python constraint will reject an attempt to install evennia into a Python 3.11 environment. Whether that failure is immediate or delayed depends on the resolver and the platform configuration, and the README gives no warning.

For a reliable setup, create the virtual environment with Python 3.12 or higher and ignore the 3.11 reference in the Windows section. The README does not explain the discrepancy, and pyproject.toml is the authoritative source for what pip enforces at install time.

For developers who want to pin Python at an exact version, the pyproject.toml classifier list is the authoritative source: 3.12, 3.13 and 3.14 are the versions the project explicitly targets.

Running in Docker with three mapped ports and a mounted game directory

The evennia/evennia Docker image exposes ports 4000, 4001 and 4002. The Dockerfile documents the run command for a game hosted in the current directory:

docker run -it --rm -p 4000:4000 -p 4001:4001 -p 4002:4002 -v $PWD:/usr/src/game evennia/evennia

The -v flag mounts your game directory into the container at /usr/src/game. The Dockerfile notes that on operating systems without $PWD support, you should substitute the full absolute path to your game directory. From the resulting container shell, the evennia command is available and initialization follows the same steps as a local install.

A second mode runs Evennia as the container's main process instead of dropping into a shell. Pass `evennia start -l` as arguments at the end of the docker run command. The -l flag keeps the process in the foreground. Without it, the Dockerfile warns, the container exits immediately because Docker sees no foreground process to keep alive.

For development on Evennia's own framework code, the Dockerfile describes an additional mount: adding -v /path/to/evennia:/usr/src/evennia alongside the game directory mount gives the container access to an editable Evennia checkout.

Where Evennia stops and your work begins

Evennia is explicit about where its responsibility ends. Installing and starting the server produces an empty world that accepts connections through both ports but contains no rooms, no characters, no commands beyond a minimal set, and no game mechanics. You write those in Python, importing your modules directly into the running server.

The README directs new developers toward an introduction document, an overview called Evennia in Pictures, and a Beginner Tutorial, all hosted at evennia.com. None of these ship inside the installed package. The repository holds a docs/ directory with framework documentation, not a sample game. The mygame directory that evennia --init creates contains configuration and a Python package scaffold: the content of your game starts empty.

This matters most for developers evaluating whether Evennia fits their project. If you want a starting point with pre-built rooms, character types, or a working quest system to extend, that work is ahead of you regardless of how complete the networking layer is. Evennia occupies a different position: it is for developers who know what game they want to build and who would rather spend time on game design than on socket management and ORM setup.

An alternative framing is to compare Evennia against writing the infrastructure yourself in Python. On that comparison, Evennia wins on time. Against a game-specific engine that ships world content, it competes on flexibility rather than out-of-the-box completeness.

The Makefile testing targets and what Production/Stable means for game modules

The repository ships a Makefile that documents the testing workflow directly. Running `make test` initializes a test game directory at .test_game_dir, applies migrations, and runs the full test suite with `evennia test --keepdb`. The keepdb flag skips rebuilding the test database on each run, which speeds up repeated test passes during development. A parallel variant `make testp` runs the same suite with `--parallel 4`. For a targeted run, the TESTS variable accepts a dotted module path: `make tests=evennia.path test`.

The repository root holds CHANGELOG.md, INSTALL.md, SECURITY.md, CONTRIBUTING.md and CODE_OF_CONDUCT.md. No GitHub releases are present on the repository, which means version 6.1.0 comes from pyproject.toml and the CHANGELOG is the record of what changed between versions. The pyproject.toml file marks the development status as "5 - Production/Stable" and lists the maintainer as Griatch, with contact information given there.

That stability label applies to the Evennia framework, not to your game modules. Because Evennia imports your Python modules at runtime, instability in your modules shows up inside a running Evennia process. The test infrastructure in the Makefile targets Evennia's own test suite, not any game you build on top of it. Testing your own game code requires setting up a separate test configuration in your mygame directory, because the Makefile's targets only cover the framework package.

Editorial conclusion

Evennia is a reasonable choice for a Python developer who wants to build an online text game without writing the networking layer, session management and web client from scratch. It is the wrong choice if you need a framework that ships with genre rules, default content or a working world to extend, since all of that is yours to build in Python. Before starting, resolve the Python version discrepancy: the README's Windows note names 3.11 but pyproject.toml sets the floor at 3.12, so start with Python 3.12 and verify pip resolves cleanly. After that, read the Beginner Tutorial at evennia.com to see how much game-specific code a functional room and command system requires.

Frequently asked questions

Official sources

1. evennia/evennia on GitHub
2. Issues
3. License: BSD-3-Clause
4. Project website
5. README