Homunculus aims to provide a unified interface to deploy python web applications on standartized environments.

Developers of WSGI-Applications specify the needed infrastructure in a config file, and then create packages. These packages can then be run, without further configuration, on every homunculus server. The necessary infrastructure will be provided automatically. Locally, they can be run with the homunculus development server.

Things that can be specified as infrastructuctural dependency include

  • MySQL databases
  • SQLite databases
  • Memcached
  • python libraries
  • Static served files
  • Media directories (i.e., public directories that the application can write to)


Let's assume, you develop a WSGI application that uses Flask and MySQL. In your project's root directory, put a file named config.json with this content:

    "application": "yourapp",
    "version": "6",
    "dependencies": [
    "features": {
        "mysql": true

In we put some application logic:

from MySQLdb import connect
from flask import Flask, g
from homunculus_instancetools import config

application = Flask(__name__)
application.config['PROPAGATE_EXCEPTIONS'] = True

def index():
    cursor = g.connection.cursor()
    cursor.execute('select name from widgets')
    names = [name for name, in cursor.fetchall()]
    return u"These are your widgets: %s" % ', '.join(names)

def connect_db():
    g.connection = connect(**config['mysql']['credentials'])

def setup_database():
    cursor = connect(**config['mysql']['credentials']).cursor()

    # check if setup is necessary
    cursor.execute("show tables like 'name'")
    if cursor.fetchall():

    # set up widget table
    cursor.execute("create table widgets (name varchar(50))")
    cursor.execute("insert into widgets (name) values ('Flux Compensator')")

Run your application locally by cd'ing into the applications directory, and running: --mysql=mysql://user:pass@host/dbname

Watch the output by opening http://localhost:8080 with your browser.

Project Structure

Homunculus is divided into subprojects


homunculus_cli provides the command line tools necessary for the development and packaging of web applications with homunculus. If you want to develop WSGI applications, this is what you need.

See for details


homunculus_server provides the server side interface to deploy and run python web applicationss. If you want to serve WSGI-applications, this is what you need.

See for details


homunculus_instancetools provides the interface for applications running inside homunculus to access their configuration. Homunculus servers install this package automatically, so you don't need to install it yourself.

See for details