Install

Installing with pip

Installing Catalyst via pip is slightly more involved than the average Python package.

There are two reasons for the additional complexity:

  1. Catalyst ships several C extensions that require access to the CPython C API. In order to build the C extensions, pip needs access to the CPython header files for your Python installation.
  2. Catalyst depends on numpy, the core library for numerical array computing in Python. Numpy depends on having the LAPACK linear algebra routines available.

Because LAPACK and the CPython headers are non-Python dependencies, the correct way to install them varies from platform to platform. If you’d rather use a single tool to install Python and non-Python dependencies, or if you’re already using Anaconda as your Python distribution, you can skip to the Installing with Conda section.

Once you’ve installed the necessary additional dependencies (see below for your particular platform), you should be able to simply run

$ pip install enigma-catalyst

If you use Python for anything other than Catalyst, we strongly recommend that you install in a virtualenv. The Hitchhiker’s Guide to Python provides an excellent tutorial on virtualenv. Here’s a summarized version:

$ virtualenv catalyst-venv
$ source ./catalyst-venv/bin/activate
$ pip install enigma-

Though not required by Catalyst directly, our example algorithms use matplotlib to visually display the results of the trading algorithms. If you wish to run any examples or use matplotlib during development, it can be installed using:

$ pip install matplotlib

GNU/Linux

On Debian-derived Linux distributions, you can acquire all the necessary binary dependencies from apt by running:

$ sudo apt-get install libatlas-base-dev python-dev gfortran pkg-config libfreetype6-dev

On recent RHEL-derived derived Linux distributions (e.g. Fedora), the following should be sufficient to acquire the necessary additional dependencies:

$ sudo dnf install atlas-devel gcc-c++ gcc-gfortran libgfortran python-devel redhat-rep-config

On Arch Linux, you can acquire the additional dependencies via pacman:

$ pacman -S lapack gcc gcc-fortran pkg-config

OSX

The version of Python shipped with OSX by default is generally out of date, and has a number of quirks because it’s used directly by the operating system. For these reasons, many developers choose to install and use a separate Python installation. The Hitchhiker’s Guide to Python provides an excellent guide to Installing Python on OSX, which explains how to install Python with the Homebrew manager.

Assuming you’ve installed Python with Homebrew, you’ll also likely need the following brew packages:

$ brew install freetype pkg-config gcc openssl

OSX + virtualenv + matplotlib

A note about using matplotlib in virtual enviroments on OSX: it may be necessary to run

echo "backend: TkAgg" > ~/.matplotlib/matplotlibrc

in order to override the default macosx backend for your system, which may not be accessible from inside the virtual environment. This will allow Catalyst to open matplotlib charts from within a virtual environment, which is useful for displaying the performance of your backtests. To learn more about matplotlib backends, please refer to the matplotlib backend documentation.

Windows

In Windows, you will need the Microsoft Visual C++ Compiler for Python 2.7. This package contains the compiler and the set of system headers necessary for producing binary wheels for Python 2.7 packages. If it’s not already in your system, download it and install it before proceeding to the next step.

For windows, the easiest and best supported way to install Catalyst is to use Conda.

Amazon Linux AMI

The packages pip and setuptools that come shipped by default are very outdated. Thus, you first need to run:

pip install --upgrade pip setuptools

The default installation is also missing the C and C++ compilers, which you install by:

sudo yum install gcc gcc-c++

Then you should follow the regular installation instructions outlined at the beginning of this page.

Troubleshooting pip Install

Issue:
Package enigma-catalyst cannot be found
Solution:

Make sure you have the most up-to-date version of pip installed, by running:

pip install --upgrade pip

On Windows, the recommended command is:

python -m pip install --upgrade pip
Issue:

Package enigma-catalyst cannot still be found, even after upgrading pip (see above), with an error similar to:

Downloading/unpacking enigma-catalyst
Could not find a version that satisfies the requirement enigma-catalyst (from versions: 0.1.dev9, 0.2.dev2, 0.1.dev4, 0.1.dev5, 0.1.dev3, 0.2.dev1, 0.1.dev8, 0.1.dev6)
Cleaning up...
No distributions matching the version for enigma-catalyst
Solution:

In some systems (this error has been reported in Ubuntu), pip is configured to only find stable versions by default. Since Catalyst is in alpha version, pip cannot find a matching version that satisfies the installation requirements. The solution is to include the –pre flag to include pre-release and development versions:

pip install --pre enigma-catalyst
Issue:
Package enigma-catalyst fails to install because of outdated setuptools
Solution:

Upgrade to the most up-to-date setuptools package by running:

pip install --upgrade pip setuptools
Issue:
Missing required packages
Solution:

Download requirements.txt (click on the Raw button and Right click -> Save As...) and use it to install all the required dependencies by running:

pip install -r requirements.txt
Issue:
Installation fails with error: fatal error: Python.h: No such file or directory
Solution:

Some systems (this issue has been reported in Ubuntu) require python-dev for the proper build and installation of package dependencies. The solution is to install python-dev, which is independent of the virtual environment. In Ubuntu, you would need to run:

sudo apt-get install python-dev

Installing with conda

Another way to install Catalyst is via the conda package manager, which comes as part of Continuum Analytics’ Anaconda distribution.

The primary advantage of using Conda over pip is that conda natively understands the complex binary dependencies of packages like numpy and scipy. This means that conda can install Catalyst and its dependencies without requiring the use of a second tool to acquire Catalyst’s non-Python dependencies.

For instructions on how to install conda, see the Conda Installation Documentation. Alternatively, you can install MiniConda, which is a smaller footprint (fewer packages and smaller size) than its big brother Anaconda, but it still contains all the main packages needed. To install MiniConda, you can follow these steps:

  1. Download MiniConda. Select Python 2.7 for your Operating System.
  2. Install MiniConda. See the Installation Instructions if you need help.
  3. Ensure the correct installation by running conda list in a Terminal window, which should print the list of packages installed with Conda.

Once either Conda or MiniConda has been set up you can install Catalyst:

  1. Download the file python2.7-environment.yml.

  2. Open a Terminal window and enter [cd/dir] into the directory where you saved the above python2.7-environment.yml file.

  3. Install using this file. This step can take about 5-10 minutes to install.

    conda env create -f python2.7-environment.yml

  4. Activate the environment (which you need to do every time you start a new session to run Catalyst):

    Linux or OSX:

    source activate catalyst

    Windows:

    activate catalyst

Congratulations! You now have Catalyst installed.

Troubleshooting conda Install

If the command conda env create -f python2.7-environment.yml in step 3 above failed for any reason, you can try setting up the environment manually with the following steps:

  1. Create the environment:

    conda create --name catalyst python=2.7 scipy

  2. Activate the environment:

    Linux or OSX:

    source activate catalyst

    Windows:

    activate catalyst

  3. Install the Catalyst inside the environment:

    pip install enigma-catalyst matplotlib

Getting Help

If after following the instructions above, and going through the Troubleshooting sections, you still experience problems installing Catalyst, you can seek additional help through the following channels:

  • Join our Discord community, and head over the #catalyst_dev channel where many other users (as well as the project developers) hang out, and can assist you with your particular issue. The more descriptive and the more information you can provide, the easiest will be for others to help you out.
  • Report the problem you are experiencing on our GitHub repository following the guidelines provided therein. Before you do so, take a moment to browse through all previous reported issues in the likely case that someone else experienced that same issue before, and you get a hint on how to solve it.