twyg is compatible with Python 2.5, 2.6 and 2.7.

When used as a standalone command line program, the Cairo graphics library and the Pycairo Python bindings need to be installed for graphics rendering. Python 2.5 requires the simplejson Python module as well.

There are no prerequisites if it is used as a NodeBox1 library (see NodeBox1 setup).


If you wish to install twyg automatically with pip, you don’t need to download anything. Just proceed to the Install dependencies section.

If you want to do a manual install, you can download the latest distribution package from the Python Package Index (PyPi). Alternatively, you can download the latest development version as a ZIP file from the project’s GitHub page, or clone the repository if you are familiar with git.

You can also download a version of this documentation suitable for offline viewing here.


The installation package contains example data files and some useful scripts that won’t be installed when using the automatic installation method with pip. You might want to download the package as well to get those files.

Install dependencies

Below are platform specific instructions on installing the dependencies required by twyg.

Mac OS X

1. Install MacPorts

The easiest way to install the dependent libraries on Mac OS X is to use MacPorts. If you already have MacPorts on your system, just proceed with the following step. Otherwise, follow these instructions to install MacPorts first.

2. Install dependencies

The following command will install cairo and the Pycairo Python bindings. It will install Python 2.7 as well, if it’s not already installed (that will take a while):

sudo port install py27-cairo

If you wish to do an automatic install, you’ll need to install pip as well:

sudo port install py27-pip

After the above commands have successfully completed, make Python 2.7 the default installation:

sudo port select --set python python27


If you wish to use an earlier Python version, change all occurences of 27 to 26 or 25 in the above commands.


Install Cairo and Pycairo with your distribution’s package manager.

For example, on Debian issue the following command:

sudo apt-get install python-cairo

On Fedora:

sudo yum install pycairo

The exacts commands might vary depending on your distribution.

Optionally, install pip as well if you wish to intall twyg with the automatic method.


Install the python-cairo package with the Cygwin setup tool.

If you wish to do the automatic setup, install python_setuptools as well, then issue the following command from the Cygwin shell:

easy_install pip


If you’re using 64-bit Cygwin, the pip tool might just exit without doing anything. If this is the case, install the binutils package to fix the issue.



Install twyg

1. Automatic method

To install twyg automatically with pip, issue the following command:

sudo pip install twyg

2. Manual method

Alternatively, you can do a manual install if you have downloaded the distribution package:

tar xzf twyg-<version>.tgz
cd twyg-<version>
python build
sudo python install

NodeBox1 setup

Download the distribution package and extract its contents somewhere. Copy the twyg subfolder from the folder you extracted the package to into ~/Library/Application\ Support/NodeBox .