Installation

Important

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.

Requirements

  • Evennia requires Python 3.10 or 3.11 (recommended). Any OS that supports Python should work.

    • Windows: In the installer, make sure you 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.

    • Windows: If you want to use Python 3.11, you must also install the Windows SDK. Run the linked installer. Click the Individual Components tab at the top, then search and checkbox the latest Windows 10 SDK (also for older/newer Windows versions). Then click Install. If you have trouble, use Python 3.10 for now (2022).

  • Don’t install Evennia as administrator or superuser.

  • If you run into trouble, see installation troubleshooting.

Install with pip

Important

Using a light-weight Python virtual environment is optional, but highly recommended in order to keep your Evennia installation independent from the system libraries. 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, you - 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

pip install --upgrade evennia

Note

Windows users only - You now need to 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’s active whenever you need to use the evennia command later.

Initialize a new game

We will create a new “game dir” for you do create your game in. 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.

evennia --init mygame

This will create a new folder mygame (or whatever you chose) in your current location. This contains empty templates and all the default settings needed to start the server.

Start the new game

cd mygame 
evennia migrate

This will create the default database (Sqlite3). The database file ends up as mygame/server/evennia.db3. If you ever want to start from a fresh database, just delete this file and re-run evennia migrate again.

evennia start

Set your user-name and password when prompted. This will be the “god user” or “super user” in-game. The email is optional.

You can also automate the creation of the super user.

If all went well, the server is now up and running. Point a legacy MUD/telnet client to localhost:4000 or a web browser at http://localhost:4001 to play your new (if empty) game!

Log in as a new account or use the superuser you just created.

Restarting and stopping

You can restart the server without disconnecting players:

evennia restart

To do a full stop and restart (will disconnect players):

evennia reboot

Full stop of the server (use evennia start to restart):

evennia stop

See Server start-stop-reload page for more details.

See server logs

Log files are in mygame/server/logs. You can tail them live with

evennia --log

or

evennia -l

Stop viewing the log by pressing Ctrl-C (Cmd-C for Mac).

You can start viewing the log immediately by adding -l/--log to evennia commands, such as

evennia start -l

Server configuration

The server configuration file is mygame/server/settings.py. It’s empty by default. Copy and change only the settings you want from the default settings file. See the Settings documentation for more info.

Register with the Evennia Game Index (optional)

You can let the world know that you are working on a new Evennia-based game by registering your server with the Evennia game index.

evennia connections

Just follow the prompts. You don’t have to be open for players to do this - you just 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!

The Next steps

You are good to go!

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