Download and Installation for Euterpea 2

Last modified: Apr 17, 2017 @ 7:30 pm

These instructions are for Euterpea version 2 and the Haskell School of Music companion library, HSoM. Euterpea requires Haskell Platform, and HSoM requires Euterpea. The recommended installation process is described on this page. Please note that GitHub versions of the libraries are a work in progress and subject to change over time.

Current versions:

Please use the issue feature on GitHub to check for bug fixes and to report any new problems:

Installing Haskell Platform

Recommended versions by operating system:

If you have older versions of Haskell Platform installed, it is recommended that you uninstall them first before installing a newer version. Windows users should also delete the “ghc” and “cabal” directories from their AppData folders if possible (you may need to enable viewing hidden folders to do this). Mac users can run sudo uninstall-hs and follow the directions given.

Euterpea and HSoM are not guaranteed to work with custom Haskell installations, versions of Haskell Platform other than those listed above, and package managers other than Cabal. Stack and Homebrew are not actively supported.

Antivirus notes: some antivirus software will attempt to block the download and/or installation of newer Haskell Platform versions even though it is safe. Avast is particularly aggressive about this and will even delete the downloaded installer when you try to run it. If you experience problems like this, disable your antivirus before downloading and installing Haskell Platform. You may also need to leave your antivirus off while you install Euterpea and HSoM to avoid further problems. Remember to re-enable your antivirus software after you’re done!


Installing Euterpea 2

The most recent, stable version of Euterpea 2 is available on Hackage. To install it:

  1. Follow the steps above to install Haskell Platform Core.
  2. Open a command prompt or terminal and run the following to install from Hackage (you do not need to manually download anything; it will be done automatically):
cabal update
cabal install Euterpea

Note: cabal may prompt you to install another newer version of itself with “cabal install cabal-install” – you do not need to do this unless you want to, and doing so only installs a newer version of cabal, not whichever other library you are trying to install. If you update cabal, it is important that you still run the commands as shown above to install Euterpea itself.


OPTIONAL: Obtaining the Development Version from GitHub

More recent, development versions of Euterpea exist on GitHub. These are works in progress that are updated frequently and are not guaranteed to be stable.

Most users should use the Hackage version that you get from the instructions in the previous section. If you successfully installed Euterpea from Hackage and don’t specifically want the development version, you are done and can move on to the section for “Installing HSoM” if you want that library too.

If, however, you wish to install the newest development version from GitHub rather than using the most recent stable version on Hackage, you can do so as follows:

  1. Follow the instructions above for installing Haskell Platform.
  2. Download and unzip Euterpea 2 from GitHub.
  3. Open a command prompt or terminal within the folder where Euterpea.cabal is located.
  4. Run the following:
    cabal update
    cabal install

Note: do NOT include “Euterpea” at the end of the installation command if you want the GitHub version (otherwise you will end up with the Hackage version!). If you already installed Euterpea or an earlier version, you may be warned that you are reinstalling and may be prompted to add extra flags such as –reinstall and/or –force-reinstalls. If these prompts occur, you can force cabal to overwrite your old installation with: cabal install –reinstall –force-reinstalls

Installing HSoM

  1. Follow the steps above to install Haskell Platform and Euterpea
  2. Download and unzip HSoM from github.
  3. Open a command prompt or terminal within the folder where HSoM.cabal is located.
  4. MAC USERS ONLY: run the following command.
    cabal install GLUT --ghc-options="-optl-Wl,-framework,GLUT" --reinstall --jobs=1 --force-reinstalls
  5. All users: run the following.
    cabal install

Updating Euterpea/HSoM

Note that reinstallations can break dependencies in other libraries. If you have both Euterpea and HSoM installed, you must update Euterpea first before updating HSoM. After that, you must update any other libraries you have that depend on Euterpea/HSoM (if you have any).

If a new version has been released on Hackage, you can update your installations by opening a terminal/command prompt and running the following:

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

To update an installation from GitHub (applicable to HSoM and the development version of Euterpea):

  1. Download and unzip the new version from GitHub. Alternatively, you can use GitHub’s desktop or command line programs to automatically update your copy of the repository.
  2. Open a command prompt or terminal.
  3. Run the following, where MyFolder is the location of the .cabal file for the library you are installing:
    cabal update
    cd MyFolder
    cabal install –reinstall –force-reinstalls


Setting up MIDI

Euterpea’s play function and HSoM’s MUIs may not work out of the box depending on how your system is configured. See the page on Setting up MIDI for more information (some machines may require the use of playDev instead of play). If everything is set up correctly, you should hear a single tone by opening GHCi and running the following:

import Euterpea
play $ c 4 qn


 Testing HSoM’s MUIs

Open GHCi and run the following:

import HSoM.Examples.MUIExamples2

A window should open with various sliders and a list of MIDI output devices. You should hear notes generated automatically every second or so when the program first starts. If you hear nothing and/or if there are no MIDI output devices listed, try for Setting up MIDI. If you experience other problems, look at the troubleshooting section at the bottom of the page.

Mac/OSX users: on some Macs, MUIs will not work and the window will appear and you may hear sound, but you will not be able to operate any of the GUI elements like sliders and buttons. Unfortunately you will not be able to run programs directly from the interpreter. To run a MUI, create a file called Main.lhs with the following code:

> module Main where
> import HSoM.Examples.MUIExamples2
> main = bifurcate

Then, run compile this program to executable from a terminal with:

ghc Main.lhs

and then run it with this. Note: you will need to have a synthesizer like SimpleSynth running first and you may also need to Ctrl+C out of the application from the terminal when you’re done; the red “close” button doesn’t always show up.


You can actually use any file name you want and this will work as long as your module name is Main. If you compile Foo.lhs this way it will produce an executable called Foo.

 Using Euterpea and HSoM

Once installed, you can import Euterpea and HSoM as libraries into your own Haskell source files. For example:

module MyModule where
import Euterpea
import HSoM

Any basic text editor can be used to create and modify Haskell source files, which have the extensions hs and lhs. A variety of editors preferred by Haskell coders exists on HaskellWiki. The hs format treats lines as code (as shown above) unless they are specifically denoted as comments with “–” for single lines or “{-” and “-}” to enclose multi-line comments. In contrast, lines of code in lhs files are denoted with a “>” at the start of each line and comments are written as regular text. In lhs format, the lines of code above would be:

> module MyModule where
> import Euterpea
> import HSoM

This is a comment. Comments must be separated from code lines by a blank line.

To load a source file, you can either double-click the file to load it in GHCi. Alternatively, from the command line, you can cd to the directory where your source file is and run:

:load MyModule

To compile Euterpea-based code with GHC, your hs/lhs file can have any name, but the module name at the top of the file must be Main and should have a main function to execute called main. We recommend compiling with one of the following sets of flags, for single threaded and multithreaded programs respectively:

ghc -O2 MyModule.lhs
ghc -O2 -threaded -rtsopts MyModule.lhs

NOTE: as of May 2016 we are aware of some situations in which recursive AudSF functions in Euterpea compile incorrectly using the -O2 flag for additional compiler optimizations. Currently the best solution is to compile without the -O2 flag (which is just “ghc MyModule.lhs”). If you are using Euterpea’s signal processing framework and observe results that seem incorrect, please try recompiling without optimization. 

See the Haskell School of Music textbook and the Examples page for more examples of using the Euterpea and HSoM libraries.


After installing Haskell Platform, “cabal” is an unrecognized command.

Locate your cabal\bin (Windows) or cabal/bin (Linux and Mac) folder and add it to your system’s PATH environment variable. The PATH is a collection of folder names that your computer checks when looking for programs invoked by commands. Steps for editing the PATH differ by operating system; look up the procedure that is appropriate for your computer. Note that the procedure on more recent builds of Windows 10 is different from previous versions of Windows. For Mac and Linux users, make sure you permanently edit the path (typically requires editing a file), otherwise cabal will fall out of scope again the next time you open a terminal.

OSX 10.11 and later users with some recent (but not the latest) versions of Haskell Platform may also need to first disable rootless by running:

sudo nvram boot-args=”rootless 0″

and then rebooting. See this thread for more information. If you already tried installing Haskell Platform without trying the fix above and the installation failed, you should fully uninstall it, disable rootless as above, and then reinstall. To uninstall Haskell Platform, run the following (and any additional commands you are prompted for):

sudo uninstall-hs

After installing Haskell Platform, cabal is in scope but ghc/ghci are not.

The executables for GHC and GHCi may have been installed to another location. Search for them and manually add the appropriate folders to your PATH as in the troubleshooting item above.

The “cabal install” step 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.

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 during the download can cause the installation to abort unexpectedly.  Check your Internet connection, verify that is up and running, and try again. Sometimes the hackage website experiences problems/downtime, in which case you may need to wait a while to install Euterpea with cabal.

The “play” function produces no sound from within GHCi.

Check that your sound device is enabled and that the volume is set correctly. On Mac and Linux, you need to have a synthesizer running before GHCi is started. Follow the instructions for Setting up MIDI, restart GHCi, and then try again. Windows users: play is not guaranteed to work with GHCi on 64-bit versions of Haskell Platform.

The “play” function gives a “No MIDI output device found” error.

This means there are no active MIDI output devices on your system. Use the “devices” function in GHCi to list available output devices. On Mac and Linux, you need to have a synthesizer running before GHCi is started. Follow the instructions for Setting up MIDI, restart GHCi, and then try again.

When playing a Music value, Euterpea plays some instruments, but others are silent despite appearing in MIDI file output with velocities >0.

This is likely 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. It may also be an issue with what channel MIDI messages are being sent to if you are using a custom channel assignment function.

(Windows) 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, close all other applications, and restart GHCi. Some programs will “grab” audio and MIDI devices in an exclusive way and will note release them for other applications to use (recent versions of Chrome are particularly bad for this!). On some Windows 10 installations, primarily those upgraded from older version of Windows, the default MIDI synthesizer may not work correctly; 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 versions of Haskell Platform. 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 one one of HSoM’s MUIs results in a GLUT-related error.

Some machines end up with out-dated versions of glut.dll, which is a file needed to run MUIs and other programs using the UISF library, and others may lack it altogether. Haskell Platform comes with an appropriate version of glut.dll, but it doesn’t always end up in the system path. There are two options: (1) copy Haskell Platform’s glut.dll and replace older versions on your machine or (2) add the location of Haskell Platform’s glut.dll to your system’s path variable.

(Mac) Trying to run a MUI with MIDI output crashes with a pattern matching exception.

This is a known bug that will hopefully be fixed soon, and it is due to trying to list MIDI output devices when there are none available. The fix is to make sure you have a synthesizer (like SimpleSynth) or other MIDI output device active before starting the program. Also, make sure you compile your program with ghc using the instructions under “testing MUIs” further up on this page.

The installation fails with errors relating to PMMsg.

You have tried to install an out-dated version of Euterpea. If you were trying to install from Hackage, please run “cabal update” and try again. If you are using a manual download, make sure you have the most recent version from either Hackage or GitHub.

(Windows) After installing Haskell Platform, “cabal user-config init” doesn’t work.

Try running “cabal update” first, which will also tell you where the config file is.


If you experienced an installation problem that does not fall into the categories listed above or the recommended solutions did not work for you, please report the details of your operating system, which versions of GHC and cabal you are using, what led to the problem, and any error messages that were produced on the issues page for Euterpea 2 or the issues page for HSoM depending on which library caused the problem. Command prompt / terminal transcripts in their entirety showing the failed installation from “cabal install” onward and including the results of running “ghc –version” and “cabal –version” are the best way to send this documentation.