The easiest way to install Fuel is using the Python package manager pip. Fuel isn’t listed yet on the Python Package Index (PyPI), so you will have to grab it directly from GitHub.

$ pip install git+git://

This will give you the cutting-edge development version. The latest stable release is in the stable branch and can be installed as follows.

$ pip install git+git://

If you don’t have administrative rights, add the --user switch to the install commands to install the packages in your home folder. If you want to update Fuel, simply repeat the first command with the --upgrade switch added to pull the latest version from GitHub.


Pip may try to install or update NumPy and SciPy if they are not present or outdated. However, pip’s versions might not be linked to an optimized BLAS implementation. To prevent this from happening make sure you update NumPy and SciPy using your system’s package manager (e.g. apt-get or yum), or use a Python distribution like Anaconda, before installing Fuel. You can also pass the --no-deps switch and install all the requirements manually.

If the installation crashes with ImportError: No module named numpy.distutils.core, install NumPy and try again again.


Fuel’s requirements are

  • PyYAML, to parse the configuration file
  • six, to support both Python 2 and 3 with a single codebase
  • h5py and PyTables for the HDF5 storage back-end
  • pillow, providing PIL for image preprocessing
  • Cython, for fast extensions
  • pyzmq, to efficiently send data across processes
  • picklable_itertools, for supporting iterator serialization
  • SciPy, to read from MATLAB’s .mat format
  • requests, to download canonical datasets

nose2 is an optional requirement, used to run the tests.


If you want to work on Fuel’s development, your first step is to fork Fuel on GitHub. You will now want to install your fork of Fuel in editable mode. To install in your home directory, use the following command, replacing USER with your own GitHub user name:

$ pip install -e[test,docs] --src=$HOME

As with the usual installation, you can use --user or --no-deps if you need to. You can now make changes in the fuel directory created by pip, push to your repository and make a pull request.

If you had already cloned the GitHub repository, you can use the following command from the folder you cloned Fuel to:

$ pip install -e file:.#egg=fuel[test,docs]

Fuel contains Cython extensions, which need to be recompiled if you update the Cython .pyx files. Each time these files are modified, you should run:

$ python build_ext --inplace


If you want to build a local copy of the documentation, you can follow the instructions in the documentation development guidelines.