If you are converting an existing game from a previous Evennia version, see here.
The fastest way to install Evennia is to use the
pip installer that comes with Python (read on).
You can also clone Evennia from github or use docker. Some users have also experimented with installing Evennia on Android.
Evennia requires Python 3.10 or 3.11 (recommended). Any OS that supports Python should work.
Windows: In the installer, make sure to select
add python to path. If you have multiple versions of Python installed, use
pycommand instead of
pythonto have Windows automatically use the latest.
Don’t install Evennia as administrator or superuser.
If you run into trouble, see installation troubleshooting.
You are recommended to setup a light-weight Python virtualenv to install Evennia in. Using a virtualenv is standard practice in Python and allows you to install what you want in isolation from other programs. The virtualenv system is a part of Python and will make your life easier!
Evennia is managed from the terminal (console/Command Prompt on Windows). Once you have Python installed—and after activating your virtualenv if you are using one—install Evennia with:
pip install evennia
Optional: If you use a contrib that warns you that it needs additional packages, you can install all extra dependencies with:
pip install evennia[extra]
To update Evennia later, do the following:
pip install --upgrade evennia
Windows users only -
You now must run
python -m evennia once. This should permanently make the
evennia command available in your environment.
Once installed, make sure the
evennia command works. Use
evennia -h for usage help. If you are using a virtualenv, make sure it is active whenever you need to use the
evennia command later.
Initialize a New Game¶
We will create a new “game dir” in which to create your game. Here, and in the rest of the Evennia documentation, we refer to this game dir as
mygame, but you should, of course, name your game whatever you like. To create the new
mygame folder—or whatever you choose—in your current location:
evennia --init mygame
The resultant folder contains all the empty templates and default settings needed to start the Evennia server.
Start the New Game¶
First, create the default database (Sqlite3):
cd mygame evennia migrate
The resulting database file is created in
mygame/server/evennia.db3. If you ever want to start from a fresh database, just delete this file and re-run the
evennia migrate command.
Next, start the Evennia server with:
When prompted, enter a username and password for the in-game “god” or “superuser.” Providing an email address is optional.
You can also automate creation of the superuser.
If all went well, your new Evennia server is now up and running! To play your new—albeit empty—game, point a legacy MUD/telnet client to
localhost:4000 or a web browser to http://localhost:4001. You may log in as a new account or use the superuser account you created above.
Restarting and Stopping¶
You can restart the server (without disconnecting players) by issuing:
And, to do a full stop and restart (with disconnecting players) use:
A full stop of the server (use
evennia start to restart) is achieved with:
See the Server start-stop-reload documentation page for details.
View Server Logs¶
Log files are located in
mygame/server/logs. You can tail the logging in real-time with:
Cmd-C for Mac) to stop viewing the live log.
You may also begin viewing the real-time log immediately by adding
evennia commands, such as when starting the server:
evennia start -l
Your server’s configuration file is
mygame/server/settings.py. It’s empty by default. Copy and paste only the settings you want/need from the default settings file to your server’s
settings.py. See the Settings documentation for more information before configuring your server at this time.
Register with the Evennia Game Index (optional)¶
To let the world know that you are working on a new Evennia-based game, you may register your server with the Evennia game index by issuing:
Then, just follow the prompts. You don’t have to be open for players to do this — simply mark your game as closed and “pre-alpha.”
You are good to go!
Next, why not head over to the Starting Tutorial to learn how to begin making your new game!