Getting Started

John Steensen edited this page Jan 22, 2017 · 99 revisions
Clone this wiki locally

This will help you download, install and start Evennia for the first time.

Note: You don't need to make anything visible to the 'net in order to run and test out Evennia. Apart from installing and updating you don't even need to have an internet connection. Of course you'll probably want to put your game online once it matures enough, but until then it works fine to develop and play around completely in the sanctity and isolation of your local machine.

Quick start

For you who already know what you are doing, here's the brief rundown of getting a vanilla Evennia install running. If you are a complete newcomer you should probably jump on to the more detailed instructions.

  1. Download and install Python, GIT and python-virtualenv. Start a Console/Terminal.
  2. cd to some place you want to do your development (like a folder /home/anna/mud-devel/ on Linux or a folder in your personal user directory on Windows).
  3. virtualenv pyenv
  4. source pyenv/bin/activate (Linux, Mac), pyenv\Scripts\activate (Windows)
  5. git clone
  6. pip install -e evennia
  7. evennia --init mygame
  8. cd mygame
  9. evennia migrate
  10. evennia start (make sure to make a superuser when asked) Evennia should now be running and you can connect to it by pointing a web browser to http://localhost:8000 or a MUD telnet client to localhost:4000 (or if your OS does not recognize localhost).

There is also a video tutorial on installing Evennia made by one of our devs, check it out!

Read on for more detailed instructions.


As far as operating systems go, any system with Python support should work.

  • Linux/Unix
  • Windows (2000, XP, Vista, Win7, Win8, Win10)
  • Mac OSX (>=10.5 recommended)

Need to be installed manually (details below):

  • Python (v2.7+, not supporting v3.x).
    • Pip. Python installer, included with Python 2.7.9+ but can also be installed separately.
    • virtualenv for making isolated Python environments. Installed with pip.
  • GIT - version control software for getting and updating Evennia itself

Installed automatically:

  • Twisted (v16.0+)
  • Django (v1.9+, be warned that latest dev version is usually untested with Evennia)
    • Pillow (Python Image Library). This is often distributed with Django. As a backup you can also try the older PIL, on which Pillow is based.

Optional install:

  • PyPy (v1.7+)
    • Optional faster implementation of Python. See here for how to run Evennia under PyPy.

Step 1: Installing pre-requisites

Generally, you only need to "manually" download and install Python and GIT, the rest is handled by Python's installers.


Most Linux systems already have Python installed out of the box. Starting with Python 2.7.9 and later, pip, the python install manager, is packaged with Python, otherwise you may need to install it separately. You may also need the Python-dev environment depending on your setup. Most Linux users have the gcc compiler out of the box, but it can be missing sometimes, especially on server installs. In Debian-derived systems (Ubuntu, Mint etc) this should cover all the bases:

sudo apt-get install python python-dev git python-pip python-virtualenv gcc

If you don't have root access, these are standard packages you should easily be able to request your sysadmin to install for you. If you plan on using mysql as your database, you should install python-mysqldb as well.

Note: You should not be root after this step, running as root is a security risk.

cd /path/to/my/evenniafolder/
virtualenv pyenv

Note: If your computer has Python3 configured as default Python interpreter, you need to install Python2.7+ as well, and make sure virtualenv uses it with the -p flag; for example virtualenv -p /usr/bin/python2.7 pyenv.

Using a virtualenv is a standard Python practice. A new folder pyenv will appear. This folder will hold a self-contained setup of Python packages without interfering with default Python packages on your system. This will also sidestep the problem of many Linux distributions often lagging behind on Python package versions. Activate the virtual environment:

source pyenv/bin/activate

The text (pyenv) should appear next to your prompt to show the virtual environment is active (use deactivate to turn it off).

We need to activate the virtual environment like this every time we start a new terminal in order to have access to the Evennia-related environment.

We don't have to remain "inside" the pyenv folder. As long as the environment is active we don't need to care about the pyenv folder at all. So you could install Evennia at any location you prefer, but here we'll put it in the same folder as the virtualenv folder:

git clone     

A new folder evennia will appear next to the pyenv one. We will point to this folder to install Evennia itself inside our active virtual environment:

pip install -e evennia

The -e flag installs Evennia via soft-linking so that it immediately updates when you update the git repository. In the future, you can just cd to the evennia directory and use git pull to get the latest updates.

Evennia and all its dependencies are now installed.

Linux troubleshooting

If you get an error at this step when compiling Twisted (especially with lines mentioning failing to include Python.h) then try sudo apt-get install python-setuptools. Once installed, run pip install -e evennia again.

Under some not-updated Linux distributions you may run into errors with a too-old setuptools or missing functools. If so, update your environment with pip install --upgrade pip wheel setuptools. Then try pip install evennia again.

Some versions of Ubuntu 16 features an issue where you can't start the server but get an error saying "Twisted requires zope.interface 3.6.0 or later: no module named zope.interface.". This even though a much later version of zope.interface is clearly installed in the virtualenv (as verified with pip list). This appears to be due to a bug in the zope installer; it fails to install an empty file. To fix this, issue the following command: touch pyenv/local/lib/python2.7/site-packages/zope/ That creates the file and things should then work correctly.

Another issue on Ubuntu 16 (reported by one user) is an install error on installing Twisted; Command "python egg_info" failed with error code 1 in /tmp/pip-build-vnIFTg/twisted/ with errors like distutils.errors.DistutilsError: Could not find suitable distribution for Requirement.parse('incremental>=16.10.1'). This appears possible to solve by simply updating Ubuntu with sudo apt-get update && sudo apt-get dist-upgrade.

Users of Fedora (notably Fedora 24) has reported gcc error saying the directory /usr/lib/rpm/redhat/redhat-hardened-cc1 is missing, despite gcc itself being installed. The confirmed work-around seems to be to install the redhat-rpm-config package with e.g. sudo dnf install redhat-rpm-config.

Linux on Cloud9

If you are interested in running Evennia in the online dev environment Cloud9, you can spin it up through their normal online setup using the Evennia Linux install instructions. The one extra thing you will have to do is update mygame/server/conf/ and add WEBSERVER_PORTS = [(8080, 5001)]. This will then let you access the web server and do everything else as normal.


Users of recent MacOSX have Python 2.7 installed from the onset (this discusses how you may upgrade it). GIT can be obtained with git-osx-installer or otherwise via MacPorts as described here.

If your Python version is lower than 2.7.9 you will need to install pip manually:

sudo easy_install pip

From there on, use pip to get virtualenv and set things up the same way as described for Linux above.


Windows users should first and foremost recognize that the Evennia server is run from the command line, something which some might not be familiar with (based on the questions we have received). In the Windows launch menu, just start All Programs -> Accessories -> command prompt and you will get the Windows command line interface. There are plenty of online tutorials on using the Windows command line, one example is found here.

  • Install Python from the Python homepage here. You will need to be a Windows Administrator to install packages. You want Python version 2.7+ (Evennia does not support Python3), ideally 2.7.9 or later. When installing, make sure to checkmark all install options, especially the one about making Python available on the path (this allows you to just write python in any console without first finding where the python program actually sits on your hard drive).
  • You need to also get GIT and install it. You can use the default install options but when you get asked to "Adjust your PATH environment", you should select the second option "Use Git from the Windows Command Prompt", which gives you more freedom as to where you can use the program.
  • Finally you should install the Microsoft Visual C++ compiler for Python in order to compile the Twisted module we'll install below.

Next cd to a place where you want to set up your mud development, for example in a new directory mud-dev in your personal user folder. If you installed Python 2.7.9 or later, the pip program will be available to you (otherwise it can be downloaded separately with easy_install pip as Administrator in a Console). We will here install it all in a separate folder.

cd path\to\my\mud-dev
pip install virtualenv
virtualenv pyenv

Note: If your computer has Python3 configured as default Python interpreter, you need to install Python2.7+ as well, and make sure virtualenv uses it with the -p flag; for example virtualenv -p C:\Python27\python.exe pyenv.

Note: If you run virtualenv pyenv and get a 'virtualenv' is not recognized as an internal or external command, operable program or batch file. error, you can mkdir pyenv then python -m virtualenv . as a workaround.

A new folder pyenv will be created in your current directory. This is where we will install all our Python packages. We need to activate this "virtual environment" so that Python and pip knows to install things here:


If the prompt changes to show (pyenv) then the virtual environment is active (you can turn it off with the single command deactivate later if you want). We must activate pyenv like this every time we start a new Console in order to have access to the Python environment. Once active we don't have to care about the pyenv folder itself though - we can put our other files wherever we want. In this example we'll install everything in the same place though, right next to the pyenv folder.

git clone     

A new folder evennia appeared (next to the pyenv one). We will point to this folder to install Evennia into our active virtual environment:

pip install -e evennia

The -e flag installs Evennia via linking so that it immediately updates when you update the git repository. In the future, just cd to the evennia folder and do git pull to get the latest updates.

Evennia and all its dependencies are now installed.

Windows troubleshooting

If you are using an older version of Twisted than 16.x or if you are using an older version of Evennia with the latest version of Twisted you may get an error at startup. The error is due to the Twisted executable changing names on Windows from to twistd.exe. If you don't want to reinstall evennia anew you can instead edit evennia\evennia\server\twistd.bat. This is a file containing a single line of text. Change the single occurrence of to instead read twistd.exe. Save. Evennia should now start correctly.

Some Windows users get an error installing the Twisted 'wheel' at this point. A wheel is a pre-compiled binary package for Python. A common reason for this error is that you are using a 32-bit version of Python, but Twisted has not yet uploaded the latest 32-bit wheel. Easiest way to fix this is to install a slightly older Twisted version. So if, say, version 16.1 failed, install 16.0 manually with pip install twisted==16.0. If that doesn't work either, you could also try to get a 64-bit version of Python. If so, you should deactivate the virtualenv, delete the pyenv folder and recreate it anew as above.

Step 2: Setting up your game

You have now installed the Evennia library. As long as we have activated the virtual environment where Evennia is installed, you will now have access to the evennia command in the terminal. Next we'll initialize your own game project. You could, again, create this wherever you wanted, but here we'll create it alongside our pyenv and evennia folders (don't put it inside the evennia folder you cloned from us - best to keep your work separate). You can name your game whatever you want, in the Evennia documentation assume it's called "mygame".

evennia --init mygame

A new folder mygame will appear and informative text is echoed to you. The mygame folder (or whatever you chose to name it) is where you will create everything unique to your game.

Note that mygame is not under any form of version control at this point. If you want this (highly recommended once you start development in earnest), you can check out our guide.

The server settings file is created for you as mygame/server/conf/ If you want to customize Evennia's database settings you can do this now. If you are not sure you don't need to change anything; Evennia will start with sane defaults.

cd mygame
evennia migrate

You will see the game database being created.

If you are converting from an existing Evennia database you might get questions about removing certain models - answer "yes" to those questions.

Step 3: Starting and Stopping the Server

Every time you start a new terminal/console session you must reactivate your virtualenv again with

    source pyenv/bin/activate (Unix/Mac) 
    pyenv\Scripts\activate (Windows)

You should see (pyenv) on the command line. You know you are not in the virtualenv if the evennia command is not found.

Next, to start the server, make sure you're in your mygame directory and run

     evennia start

You will be asked to create a superuser, make sure to do so. The superuser you register becomes your superuser (owner) account in the game. You will be asked for email address and password. The email address does not have to exist (evennia does not check it by default).

After entering the superuser information, the server and portal will start for the first time. Evennia will quickly run some first-time configurations (notably pre-create an in-game Character with the same name as your superuser), restart once and then be running.

To stop Evennia later, do:

 evennia stop

See the Start Stop Reload wiki page for more info. Use evennia -h to get help on more launch options. You can for example start the server in interactive mode using evennia -i start - it will then run as a foreground process you can stop with Ctrl-C.

Step 4: Connecting to the server

The Evennia server is now up and running. You should be able to login with any traditional mud client or telnet client using the name and password you specified when syncing the database. If you are just testing the server out on your local machine, the server name will most likely be localhost whereas the port used by default is 4000. If localhost is not recognized (can happen on Windows), use instead.

If the defaults are not changed, Evennia will also start its own Twisted-based web server on port 8000. Point your web browser to http://localhost:8000/. The admin interface allows you to edit the game database online and you can connect directly to the game by use of our web client.

Welcome to Evennia! Why not try building something next?

Optional: Running under PyPy

Note: This is currently not working with latest Evennia under Linux. More testing is needed.

PyPy is a fast alternative implementation of standard Python. Evennia under PyPy generally takes longer to start but may run faster once its up (just how much is currently untested so feel free to report your findings).

You first need to download and install PyPy. If you are on a Debian-derived system you can install it like this:

sudo apt-get install pypy pypy-dev

If PyPy is not available as a package for your system, see the PyPy homepage for instructions.

Next you should create a new, separate virtual environment for your pypy-powered server and make sure it uses the pypy interpreter instead of the normal cPython one:

virtualenv pypyenv --python=/usr/bin/pypy

Replace /usr/bin/pypy with the full path to the installed PyPy binary on your system.

Next, activate the new virtual environment and install with pip install -e evennia as normal. PyPy-enhanced versions of the dependencies will be installed wherever applicable. Use an existing game folder or create a new one as needed. Start Evennia as normal with evennia start.

Inside the game you can do the following (as superuser) to test that PyPy is working:

 @py import __pypy__

If this works Evennia is running under pypy. If you get an ImportError there was some problem and normal cPython is still being used.