Installation

Important

If you are converting an existing game from a previous Evennia version, you will need to upgrade.

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.

If you are converting an existing game, please follow the upgrade instructions.

Requirements

  • Evennia requires Python 3.10, 3.11 or 3.12 (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 py command instead of python to have Windows automatically use the latest.

  • Don’t install Evennia as administrator or superuser.

  • If you run into trouble, see installation troubleshooting.

Install with pip

Important

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!

You re recommended to setup a light-weight Python virtualenv first.

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

Note

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:

evennia start

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:

evennia restart

And, to do a full stop and restart (with disconnecting players) use:

evennia reboot

A full stop of the server (use evennia start to restart) is achieved with:

evennia stop

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:

evennia --log

or just:

evennia -l

Press Ctrl-C (Cmd-C for Mac) to stop viewing the live log.

You may also begin viewing the real-time log immediately by adding -l/--log to evennia commands, such as when starting the server:

evennia start -l

Server Configuration

Your server’s configuration file is mygame/server/conf/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:

evennia connections

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.”

See here for more instructions and please check out the index beforehand to make sure you don’t pick a game name that is already taken — be nice!

Next Steps

You are good to go!

Next, why not head over to the Starting Tutorial to learn how to begin making your new game!