Download and Installation for Euterpea 2

Last modified: Jun 16, 2019 @ 10:24 am

Haskell Platform 8.6.3 users: you may need to use cabal v2-update instead of the old cabal update command before you install Euterpea. If the update is successful you will see a message explaining how to roll back to older versions. Using cabal install Euterpea should then work as normal.

Windows Lilypond users: there are known compatibility problems between Lilypond and recent versions of Haskell Platform, including 8.4.3 and later versions. It results in errors relating to pthread.dll See the Windows section of the troubleshooting page for more details.

Current Hackage versions: Euterpea 2.0.7, HSoM 1.0.0
Current development GitHub versions: Euterpea 2.0.8 (newer), HSoM 1.0.0 (same as Hackage).

These instructions are for Euterpea version 2 and the Haskell School of Music companion library, called HSoM. On this page, you will find information and instructions on:

Supported Operating Systems

Euterpea is actively developed and tested with the following operating systems:

  • Windows 10
  • Mac OSX 10.13 (High Sierra)

Euterpea will also work with:

  • Windows 7 to 8.1.
  • Mac OSX 10.10-10.12. Sometimes versions as far back as 10.8 will also work, but not always – it’s hit and miss.
  • The more popular Linux distributions. However, success is not guaranteed on arbitrary Linux machines due to the sheer number of different varieties available.

Euterpea and HSoM are NOT guaranteed to work if you are using any the following:

  • extremely old hardware or operating systems (such as Windows XP, >10 year old Mac laptops, etc.)
  • arbitrary Linux distributions (NixOS is known to be problematic due to its restrictions on older package versions)
  • custom Haskell installations, such as those using newer versions of GHC than what Haskell Platform supports
  • versions of Haskell Platform other than those recommended further down this page
  • package managers other than Cabal (the Stack and Homebrew package managers are not actively supported)

Current versions:

Bug reporting:

Installing Haskell Platform

Recommended versions by operating system:

  • Windows: 
    • Windows 10 Creators Update and later: any version of Haskell Platform 8.2.1 to Haskell Platform 8.4.3. Core 64-bit is is the minimal requirement and recommended for most users. If you want to use other audio or graphics libraries beyond Euterpea/HSoM, then the full version is recommended (for example, if you need the networks package then you should use the full version). Versions earlier than 8.2 are not recommended, but if you must use an older one, you must use the 32-bit version of it for Euterpea’s MIDI playback to work.
    • Older Windows versions (10 prior to Creators Update, 7, 8, etc.) may need to use 32-bit 8.0.2 in order for Euterpea’s MIDI playback to work.
  • Mac: Haskell Platform 8.4.3 core or full.
  • Linux: Haskell Platform 8.4.3  core or full. Euterpea and HSoM require ALSA and are unfortunately not guaranteed to install successfully on all flavors of Linux.

Regarding Haskell Platform 8.6.3: Euterpea 2.0.6 has been made compatible with platform 8.6.3, but the setup can be bumpy due to issues surrounding cabal’s process of fetching an up-to-date list of packages from Haskell on some operating systems. For the simplest setup, please use 8.4.3 for now if you don’t have a specific reason to upgrade to 8.6.3.

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.

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 Full or Core.
  2. Open a command prompt (or PowerShell) 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

Haskell Platform 8.6.3 users: you may need to use the command cabal v2-update to fetch the most recent list of packages from Hackage.

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 PowerShell) or terminal within the folder where Euterpea.cabal is located.
  4. Run the following:
    cabal update
    cabal install

Haskell Platform 8.6.3 users: you may need to use the command cabal v2-update to fetch the most recent list of packages from Hackage.

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. Open a command prompt (or PowerShell) or terminal and run the following: cabal install HSoM

If you need the most recent development (unstable) version of HSoM instead of the stable Hackage release, you can download it from GitHub and use the same approach as described in the section on installing the development version of Euterpea.

Mac users: if you are using HSoM’s MUIs, you must compile your code to executable. See the section further down on “Testing HSoM’s MUIs” for more information on how to do this.

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, first try compiling to executable as described below (mainly an issue for Mac users), and then look at the troubleshooting section at the bottom of the page.

Compiling to Executable

On newer Macs, MUIs will not work from the GHCi interpreter. Failure cases range from unresponsive windows to threading errors. However, if this happens to you, you will still be able to run MUIs successfully by compiling your code to executable. Windows users can also benefit from compiling to executable with some MUIs because it can help speed up execution between frames, which is useful for interactive programs.

The easiest way to try compiling a MUI to executable the first time is to use one of the MUI example that comes included with HSoM. We’ll use bifurcate here.

First, create a file called Bifurcate.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 Bifurcate.lhs

and then run it with this.


Mac and Linux users: you will need to have a synthesizer running first before starting ./Bifurcate or you will see no MIDI output device options and may get errors. 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.

Mac users with older OSX versions and/or older versions of Haskell Platform: if the steps above still don’t work for you, then try running this:
cabal install GLUT --ghc-options="-optl-Wl,-framework,GLUT" --reinstall --jobs=1 --force-reinstalls

 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.


(Mac) Trying to run a program using HSoM’s MUIs crashes with the error: GLUT Fatal Error: internal error: NSInternalInconsistencyException, reason: nextEventMatchingMask should only be called from the Main Thread!

This is due to trying to using HSoM’s MUIs in a multithreaded situation. While such applications often are successful on Windows, on Mac they experience problems with the GLUT library. While this can limit performance, the only safe way to run a MUI-using program on Mac is to stick to a single thread compile with either ghc YourProgram.lhs or ghc -O2 YourProgram.lhs. Avoid using fork operations in any code involving MUIs and do not compile with either the -rtsopts or
-threaded flags.

(Windows) Euterpea’s play function causes one or more instances of the following error message: addLibrarySearchPath: D:\GitHub\haskell-platform\build\ghc-bindist\local\mingw\lib (Win32 error 3): The system cannot find the path specified.

This is due to a problem with the compiled binaries in a now outdated release of Haskell Platform 8.4.3 and 8.4.2. Uninstall Haskell Platform, re-download Haskell Platform 8.4.3 to get the corrected binaries, and then re-install. There is a thread on the issue on Haskell Platform’s GitHub issues page:

(Windows) Trying to start GHCi, WinGHCI, or running GHC fails with errors related to pthread.dll, such as: user specified .o/.so/.DLL could not be loaded (addDLL: pthread or dependencies not loaded. (Win32 error 193))

If you have Lilypond installed, this is unfortunately a known incompatibility with recent versions of Haskell Platform right now. There are only three ways to solve it for now:

Option 1: Remove Lilypond’s bin folder from your PATH environment variable. If you have a user path and a system path, you must remove Lilypond-related entries from BOTH, not just the user’s path. You may need to reboot for GHCi to work again. You should still be able to run the GUI for Lilypond by making a desktop shortcuts directly to Lilypad.exe. If using from command line, calling the executables with the full path to the containing folder. Unless you used a custom installation location, the Lilypad, lilypond, midi2ly, and other programs that come with Lilypond will be located in this folder:
C:\Program Files (x86)\LilyPond\usr\bin

Option 2: Use Haskell Platform 8.0.2a (core or full).

Option 3: Uninstall Lilypond. This is only recommended if it’s an old installation and you don’t plan on using it anymore. Otherwise, try option 1 first.

If you are getting errors related to pthread.dll without ever having had a Lilypond installation, please report the problem on Euterpea2’s Issues page on GitHub.

(Haskell Platform 8.4.2) Installing Euterpea and/or HSoM fails with errors related to HCodecs.

Euterpea briefly experienced problems with platform version 8.4.2, but changes were pushed to both Hackage and GitHub to correct the issue. To get these changes, you need to run cabal update before running cabal install Euterpea.

(Mac) Trying to install Euterpea or HSoM gives the error: unknown argument: ‘-no-pie’

Your xcode version is out of date. If you have a recent version of OSX, run xcode-select --install to update it. If you have an old version of OSX and can’t update xcode, an alternate solution is described here.

(Mac) HSoM’s MUIs crash or the windows hang and are unresponsive.

If you are trying to run them from GHCi, try compiling to executable as described in the “Testing HSoM’s MUIs” section further up on this page. If compiling to executable fails as well, try running the following: cabal install GLUT --ghc-options="-optl-Wl,-framework,GLUT" --reinstall --jobs=1 --force-reinstalls. You may need to reinstall HSoM with cabal install HSoM again afterwards. If you still have problems, please report the problems with a complete transcript and OS version information on HSoM’s GitHub issues page.

(Mac) Installing Euterpea fails with the error “xcrun: error: invalid active developer path (…)”

This indicates missing command line tools that Haskell Platform depends on. To install these, run:
xcode-select --install

(Windows 10) GHCi crashes/disappears when opening  a Haskell source file (.hs/.lhs) by double-clicking it.

This is a known issue with GHCi and the initial realize of the Windows 10 Creators Update. Please run Windows Update, restart, and see if the problem persists. If it does, the best workarounds are to either run GHCi from within a command prompt (or PowerShell) and load the file manually or use WinGHCi as the default program to open source files.

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.

Although this issue has been fixed on more recent versions of OSX and Haskell Platform, OSX 10.11 users with some older 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 can happen with the 64-bit versions of Haskell Platform on pre-creators update Windows 10 and on any version of Windows with Haskell Platform 8.0.1 or earlier. For older versions of Windows and/or older 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.

(Windows 10 Creators Update) Double-clicking to open hs/lhs files with GHCi crashes with an error.

When the creator’s update was initially released, it broke the double-click-to-open functionality for hs/lhs files and GHCi. This seems to have been resolved on most machines with some later incremental Windows updates, so please run Windows Update to make sure your machine is up-to-date. If you still have problems, you should still be able to run ghc and ghci manually from a command prompt or Power Shell – if you can’t, then there is a problem with your Haskell Platform installation and you should uninstall and reinstall. Another workaround is to use WinGHCi as the default program for opening Haskell source files.

(Linux) Euterpea installation fails with a PortMidi-related error: “missing C library: asound”

This is a missing dependency problem. Try running apt-get install libasound2-dev.


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. Do not use pull requests to report bugs or suggest fixes.