Download and Installation

Last updated: 31-Dec-2015

The instructions on this page are for Euterpea 1.1.1. Information on more recent versions of Euterpea is now on

The best platform on which to run Haskell and Euterpea is Windows or Mac. The installation instructions for Linux are more complicated, but for most flavours of Linux, you should be fine with the instructions below. Please send any questions, comments, and bug reports to Donya Quick (

Installing Haskell Platform

You should install the Haskell Platform. This also contains Cabal, a package management tool for Haskell. You will need Cabal for installing and updating Euterpea. Each version of Haskell Platform comes with a different version of GHC (Glasgow Haskell Compiler) and Cabal.

Windows users: please use 32-bit versions of Haskell Platform. The 64-bit versions of 7.10.2 and 7.10.3 are problematic when trying to use Euterpea’s “play” function from GHCi.

Download the Haskell Platform installer for your operating system and set it up per the instructions. Once Haskell Platform is installed, you can check the versions you have installed by running the following in a command prompt or terminal:

ghc --version
cabal --version

Note to Windows users: If you have installed previous versions of GHC or the Haskell Platform, it is best to first remove them, preferably through the uninstall option for these applications, but if necessary, manually remove things such as:

C:\Program Files\Haskell
C:\Program Files\Haskell Platform
C:\Documents and Settings\username\Application Data\ghc
C:\Documents and Settings\username\Application Data\cabal

You might want to search for anything with “ghc” or “cabal” in the name and get rid of it. You should also reboot after removing these items.

Path Environment

Windows users can skip this step since the PATH environment has already been set by the Haskell Platform installation.

Linux and OS X users should set ~/.cabal/bin to your PATH environment by entering the following command at the command prompt:

export PATH=~/.cabal/bin:$PATH

You can also set it permanently by modifying the file ~/.bashrc or ~/.profile (depending on which system you use) to include the above line. Otherwise, you’ll have to enter the above command every time you want to use any binary command installed by cabal. If the ~/.cabal/bin directory does not exist on your installation, try ~/Library/Haskell/bin instead for the instructions above.

Installing Euterpea

Note: if you experience an error related to CCA when installing Euterpea, check the solutions at the bottom of the page HERE and then try the “cabal install Euterpea” step again.


Open a command prompt and run:

cabal update
cabal install Euterpea

Windows 10 users: you may also need to install Coolsoft’s Virtual MIDI Synthesizer as a substitute for the default Windows synthesizer in order to use Euterpea’s “play” function.

Mac OS*

*Note: we haven’t done a full test on Mac OS yet. These instructions may or may not be helpful to you.

Open a terminal and run:

cabal update
cabal install Euterpea

Everything might work as this point, if not continue…


You may need to set up some midi tools to get everything working properly. We used virtual Midi Keyboard, but there are plenty others that will work. You will be working with the Audio Midi Setup Tool that is part of the Mac OS. You can see the setup in the picture below. You need to connect your Midi sequencer (vmkb) to the IAC Driver and you should be all set.

Mac Midi Setup

Using GUIs

To use a GUI in Euterpea on a Mac, you will need to define a “main” function and compile using ghc. If you would really like to use ghci with a GUI program in Euterpea, you need to take some extra steps. The following instructions are outdate but may be of some help.

You will have to use the “EnableGUI trick” to run GUI programs in GHCi for Euterpea. First, compile EnableGUI.hs to binary from the Examples zip file:

ghc -c -fffi EnableGUI.hs

Note: on some systems it is necessary to include a -framework option, like this:

ghc -framework ApplicationServices -c -fffi EnableGUI.hs

Then run your Euterpea GUI programs in ghci like this:

ghci UIExamples.hs EnableGUI
*UIExamples> :m +EnableGUI
*UIExamples EnableGUI> enableGUI >> main


Open a terminal and run:

sudo apt-get install libasound2-dev
cabal update
cabal install Euterpea


The simplest way to use midi is to generate a composition and save it to a midi file using the “writeMidi” function. You can then either play it locally on your own machine or using an online midi interface.(CS431/432 students will need to use the online version until the Zoo has the proper software to play locally). As an example

writeMidi “test.midi” (c 4 qn)

If you would like to do interactive midi work (i.e use the “play” function) , you will need to setup TiMidity. The following italicized instructions are somewhat outdated, but may give you a hint for how to proceed.

Open a terminal and run:

sudo apt-get install timidity

First of all, we recommend using TiMidity and either Freepats or PersonalCopy for MIDI support. Before you attempt source compilation, you might want to check if your distribution already includes them as one of the pre-built packages for download. (sudo apt-get install timidity)

To install PersonalCopy and have Timidity depend on it, follow these steps:

wget # this can take a while to download.
sudo mkdir /etc/sounds
gunzip Unison.sf2.gz
mv Unison.sf2 /etc/sounds
sudo sh -c "echo soundfont /etc/sounds/Unison.sf2 > /etc/timidity/timidity.cfg"
sudo service timidity restart

Next, you’ll need to make sure that timidity is the default MIDI-Through port. The easiest way to do this is to remove the default dummy port:

sudo rmmod snd_seq_dummy

(If you want to make this change permanent, you can run

sudo sh -c "echo blacklist snd_seq_dummy > /etc/modprobe.d/blacklist-seq-dummy.conf"

which will create a configuration file that tells modprobe (the linux device driver loader) not to load snd_seq_dummy. It can be easily reversed by just deleting the file.)

Then, while Euterpea programs are running, you must have timidity running in the background, which you can achieve by first running
timidity -iA -Os &
before running the Euterpea program.

Testing Installation Success

Assuming that the installation succeeds, you can run some EuterpeaExamples we have provided. Simply download and unzip the folder. Then open a command promt/terminal and navigate to the Examples folder you just downloaded. You can use the command ‘ghci’ to run these programs.

‘ghci’ is the command to start GHC interactively as an interpreter, where you may enter Haskell commands and load programs. For example, after starting ghci, to play one of the music values defined within the Examples folder:

:load EuterpeaExamples.lhs
play childSong6

If your MIDI device is working properly, you should hear a melody, otherwise please see the below notes for your particular operating system or check the troubleshooting FAQ at the bottom of this page. Alternativly, write your midi to a file and then play it outside of Euterpea.

:load EuterpeaExamples.lhs
writeMidi childSong6

…and use an online midi interface to play the file.

Updating Euterpea

From time to time we suggest that you update to newer versions of Euterpea, which is still evolving. To do this, open a command prompt/terminal and do the following:

cabal update
cabal install Euterpea --reinstall --force-reinstalls

Troubleshooting FAQ

The instructions say to open a “command prompt” or “terminal” but I don’t know how.

  • On Windows 8, from the desktop, hover your mouse over the lower left corner until the start box appears and right click. Select “Command Prompt (Admin)”.
  • On Windows Vista or Windows 7 machines, click on the Start button, and look for the Command Prompt icon (usually under All Programs | Accessories). Right click on the icon, and then click “Run as administrator”.
  • On other Windows platforms, just click on the Command Prompt icon (usually under All Programs | Accessories), or execute “cmd.exe“.
  • On a Mac, open the “Terminal” application.

I followed the advice for my specific operating system, but I still can’t get MIDI output to work properly.

Make sure timidity or simplesynth are running in the background if you’re using those programs. Alternatively, instead of (for example) doing “play childSong6“, use “test childSong6” instead. This will write the MIDI output to a file named “test.mid“, and you can then play it with timidity (Linux) or Quicktime (Mac). Or, if you have an external MIDI device, you can connect it to your computer and have MIDI signals sent to it.

The “cabal install Euterpea” appeared to succeed, but the Euterpea package can’t be found with “import Euterpea.”

Turn off any antivirus software and try the installation again. Some antivirus programs may silently block actions required for a successful installation when running “cabal install” – even in administrator mode on Windows. In some cases the installation may appear to succeed when it is actually incomplete. Recent versions of Avast are very problematic for this. If you are using Avast, turn it off completely during the time that you are attempting to install Euterpea.

Running Euterpea examples with the 64-bit version of Haskell Platform results in segfaults.

Uninstall Haskell Platform, delete any directories it leaves behind (usually called things like “ghc”, “cabal”, or “haskell”). Follow the setup instructions again but use the 32-bit version of Haskell Platform. The 64-bit version of Haskell Platform has known compatibility problems with some Mac OS versions.

A call to “caball install” fails unexpectedly partway through the installation with no error beyond “some packages failed to install” when installing either Euterpea or a new version of cabal.

If the installation requires downloading additional packages, a timeout can cause the installation to abort unexpectedly.  Check your Internet connection and try the same command again.

Doing “cabal install Euterpea” fails with a CCA-related error stating that ccap can’t be found.

Sometimes when Haskell Platoform is installed, some directories that should be added to the system path aren’t. Search your hard drive for “ccap” – it is an executable file that can appear in various places depending on the OS. Once you find the ccap file, add its directory to your system path. If there is no ccap file anywhere on your machine, you can try cabal install CCA --reinstall to reinstall CCA.

Doing “cabal install Euterpea” fails because CCA failed to install.

If you are using CCA-0.1.4, run “cabal update” to get the most recent version of the CCA library, which is CCA-0.1.5, and then try installing Euterpea again.

If instead cabal is trying to install CCA-, try installing the previous version:

cabal install CCA-0.1.5

If you had older versions of CCA installed, you may need to force reinstallation:

cabal install CCA-0.1.5 --reinstall --force-reinstalls

When playing a Music value, Euterpea plays some instruments, but others are silent.

This is an issue with your synthesizer, not Euterpea. Some synthesizers do not have patches for all of the general MIDI instruments. Try using a different synthesizer or a different set of virtual instruments.

(Windows 10) Calling the “play” function on any Music value or trying to send MIDI messages to the default Windows synthesizer gives “host error” messages with no sound.

First, make sure your sound device is enabled. If you can hear sound from other programs but not from Euterpea, the easiest fix is to install the Coolsoft Virtual MIDI Synthesizer. Please see the Midi on Windows page for more information.

(Windows) Calling the “play” function on any Music value crashes GHCi. 

This happens with the 64-bit version of Haskell Platform 7.10.3. Please use the 32-bit version on Windows if you want to work within GHCi. Alternatively, try compiling your program to an executable with GHC.

Trying to run a MUI (musical user interface using the UISF library) gives errors relating to GLFW and pixel formats.

This is a problem that appears sometimes with very old hardware and out-dated graphics drivers. Try updating the graphics drivers on your machine. If you have a graphics chip on your motherboard in addition to a graphics card, make sure you update the drivers for both.

Comments are closed.