This installation guide covers HyperKitty, the web user interface to access GNU Mailman v3 Archives. To install GNU Mailman follow the instructions in the documentation:

Install the code

Install the HyperKitty package and its dependencies with the following commands:

sudo python install

You will also need to install the Sass CSS processor using your package manager or the project’s installation documentation. You can either use the dart-sass version (dartsass) or the C/C++ version, called libsass (the binary is sassc). The configuration file in example_project/ defaults to the sassc version, but you just have to edit the COMPRESS_PRECOMPILERS mapping to switch to the dart-sass implementation, whose binary is called sass and which doesn’t recognize the short form of the -t/--style option.

We no longer recommend ruby-sass as there have been compatibility issues with recent versions.

Recent Debian and Ubuntu have a sassc package, which you can install with:

sudo apt-get install sassc

It is however recommended to use Virtualenv to install HyperKitty, even for a non-development setup (production). Check out the development documentation for details.

Setup your django project

You now have installed the necessary packages but you still need to setup the Django site (project). Example files are provided in the example_project subdirectory.

Change the database setting in example_project/ to your preferred database. Edit this file to reflect the correct database credentials, the configuration variable is DATABASES (at the top of the file).

Or better yet, instead of changing the file itself, copy the values you want to change to a file called and change them there. It will override the values in and will make future upgrades easier.


Detailed information on how to use different database engines can be found in the Django documentation.

Setting up the databases

The HyperKitty database is configured using the DATABASE setting in Django’s file, as usual. The database can be created with the following command:

django-admin migrate --pythonpath example_project --settings settings

HyperKitty also uses a fulltext search engine. Thanks to the Django-Haystack library, the search engine backend is pluggable, refer to the Haystack documentation on how to install and configure the fulltext search engine backend.

HyperKitty’s default configuration uses the Whoosh backend, so if you want to use that you just need to install the Whoosh Python library.

Importing the current archives

If you are currently running Mailman 2.1, you can run the hyperkitty_import management command to import existing archives into the mailman database. This command will import the Mbox files: if you’re installing HyperKitty on the machine which hosted the previous version of Mailman, those files are available locally and you can use them directly.

The command’s syntax is:

django-admin hyperkitty_import --pythonpath example_project --settings settings -l ADDRESS mbox_file [mbox_file ...]


  • ADDRESS is the fully-qualified list name (including the @ sign and the domain name)

  • The mbox_file arguments are the existing archives to import (in mbox format).

The archive mbox file for a list is usually available at the following location:


If the previous archives aren’t available locally, you need to download them from your current Mailman 2.1 installation. The file is not web-accessible.

Before importing an archive mbox, it is a good idea to check its integrity with the hyperkitty/contrib/check_hk_import script and with Mailman 2.1’s bin/cleanarch script.

After importing your existing archives, you must add them to the fulltext search engine with the following command:

django-admin update_index --pythonpath example_project --settings settings

Refer to the command’s documentation for available switches.

Running HyperKitty on Apache with mod_wsgi


This guide assumes that you know how to setup a VirtualHost with Apache. If you are using SQLite, the .db file as well as its folder need to be writable by the web server.

Edit example_project/apache.conf to point to your source code location.

Add following line to your apache/httpd configuration file:

Include "/{path-to-example_project}/apache.conf"

And reload Apache. We’re almost ready. But you need to collect the static files from HyperKitty (which resides somewhere on your pythonpath) to be able to serve them from the site directory. All you have to do is run:

django-admin collectstatic --pythonpath example_project --settings settings
django-admin compress --pythonpath example_project --settings settings


Your django-admin command may be called depending on your installation method.

These static files will be collected in the example_project/static directory and served by Apache. You should now be all set. Try accessing HyperKitty in your web browser.

Connecting to Mailman

To receive incoming emails from Mailman, you must install the mailman-hyperkitty module available on PyPI in Mailman’s virtualenv, and then add the following lines to mailman.cfg:

class: mailman_hyperkitty.Archiver
enable: yes
configuration: /path/to/example_project/mailman-hyperkitty.cfg

An example of the mailman-hyperkitty.cfg file is shipped with the mailman-hyperkitty package. You must set the URL to your HyperKitty installation in that file. It is also highly recommanded to change the API secret key and in the MAILMAN_ARCHIVER_KEY variable in (or

After having made these changes, you must restart Mailman. Check its log files to make sure the emails are correctly archived. You should not see “Broken archiver: hyperkitty” messages.


Make sure you installed the mailman_hyperkitty module in the same environment in which Mailman’s daemon is executed otherwise it will raise an exception.

Initial setup

After installing HyperKitty for the first time, you can populate the database with some data that may be useful, for example a set of thread categories to assign to your mailing-list threads. This can be done by running the following command:

django-admin loaddata --pythonpath example_project --settings settings first_start

Thread categories can be edited and added from the Django administration interface (append /admin to your base URL).

You must also make sure that Mailman has generated the databases files that Postfix (or another MTA) will use to lookup the lists. Otherwise SMTP delivery will fail, and that will also impact HyperKitty when it will try to validate email addresses on registration. You can force Mailman to generate those database files with the following command:

mailman aliases


You can add HTML snippets to every HyperKitty page by using Django’s TEMPLATE DIRS facility and overriding the following templates:

  • hyperkitty/headers.html: the content will appear before the </head> tag

  • hyperkitty/top.html: the content will appear before the <body> tag

  • hyperkitty/bottom.html: the content will appear before the </body> tag

By default, HyperKitty stores the email attachments in the database. If you would rather have them stored on the filesystem, you can set the HYPERKITTY_ATTACHMENT_FOLDER configuration value to a directory.

Make sure that the user running the Django process (for example, apache or www-data) has the permissions to write in this directory.

If you want to disable support for gravatars in Hyperkitty, you can set HYPERKITTY_ENABLE_GRAVATAR = False. This prevents loading and displaying gravatar images.


To upgrade an existing installation of HyperKitty, you need to update the code base and run the commands that will update the database schemas. Before updating any of those databases, it is recommended to shut down the webserver which serves HyperKitty (Apache HTTPd for example).

To update the HyperKitty database, run:

django-admin migrate --pythonpath example_project --settings settings

After this command complete, your database will be updated, you can start your webserver again.

Asynchronous tasks

There are a few tasks in HyperKitty that need to be run at regular intervals. The example_project directory contains an example crontab file that you can put in your /etc/cron.d directory.

To improve performance, HyperKitty uses a distributed task queue that offloads long operations to separate processes called “workers”. Those workers must be started with the following command:

django-admin qcluster --pythonpath example_project --settings settings

An example service file for systemd is provided in the example_project directory to start the workers at boot time, and manage them like an ordinary system service. The service file is called qcluster.service, make sure you edit the path to the project on the ExecStart line.


Some preliminary RPMs for Fedora 21 are available from the repository described in this repo file:

There are also RPMs for RHEL 7 available using this repo file:

The long-term plan is to submit HyperKitty and Mailman3 for inclusion into Fedora. At the moment, the packages are rather stable, but the dependencies can change. These packages have been tested on Fedora 21 and RHEL7 with the targeted SELinux policy set to enforcing.


HyperKitty is licensed under the GPL v3.0