How do I read this LilyPond file?

By opening it in the LilyPond application and typesetting it to a PDF.

Where do I find the LilyPond application?

LilyPond is free under the GNU General Public License ((To learn more about the General Public License and the philosophy behind it, visit the Free Software Foundation at  You can find installers for Mac OS, Windows and Unix/Linux at

  1. Click on the link for your operating system.
  2. Follow the instructions for “Compiling a file”, to make sure everything works.
  3. Take note of the instructions for “Running on the command-line”.  You don’t need them right now, but you eventually will.

LilyPond is working, now what?

If you found a fragment of LilyPond source on a website, create a new “.ly” file, paste the text into it, and compile it.

If you have a single “.ly” file, that is easy to compile too.

If you downloaded the source for anything involving multiple movements or multiple instruments, it is probably stored in many pieces.  Let’s look at the score for an entire opera.

Downloading the source

Let’s take another look at the version of “King Arthur” by Henry Purcell on ChoralWiki.  There are four independent collections of .pdf files:

  1. Conductor’s score
  2. Vocal score with keyboard reduction of violins and continuo
  3. Collection of the instrumental scores
  4. Urtext version

However, the “LilyPond” links all download the same thing: “”.  Download one of these, extract it, and you’ll find an assortment of files and folders – 693 in total ((There is at least one file per instrument per movement, and a number of other supporting files and folders.)).

Typesetting the source

Fortunately one of the the files is called “Readme”.  Open it in a text editor (Notepad on Windows, or TextEdit on Mac OS) for some helpful information on the copyist.

However, for now let’s open a file in LilyPond, like “”.  Typeset it… and you probably receive errors like this:

 Processing `~/Music/Arthur/'
~/Music/Arthur/commons/Couverture.ily:27:11: error: GUILE signaled an error for the expression beginning here
           (ly:export (string-append "version " (lilypond-version)))
~/Music/Arthur/commons/Couverture.ily:27:10: error: not a markup

          #(ly:export (string-append "version " (lilypond-version)))
~/Music/Arthur/ error: unknown escaped string: `\markuplines'

  \markuplines { \wordwrap-lines { \table-of-contents }}
~/Music/Arthur/ error: syntax error, unexpected STRING

  \markuplines { \wordwrap-lines { \table-of-contents }}
~/Music/Arthur/ error: unknown escaped string: `\wordwrap-lines'
  \markuplines { 
                 \wordwrap-lines { \table-of-contents }}
~/Music/Arthur/ error: unknown escaped string: `\table-of-contents'
  \markuplines { \wordwrap-lines { 
                                   \table-of-contents }}
~/Music/Arthur/ error: errors found, ignoring music expression
               { \wordwrap-lines { \table-of-contents }}
Unbound variable: ly:export
fatal error: failed files: "~/Music/Arthur/"

What went wrong?  As of September 2012, the source files were written for LilyPond 2.14, while the latest stable version is 2.16.  It doesn’t like the 2.14 source, which must be updated.

When the LilyPond developers decide that one of their old ideas was bad, they change it.  This makes the program better, but often breaks compatibility with older files.  Fortunately they provided an automatic updater.

Unfortunately, you must run the automatic updater from the command-line.  Did you take note of the bit about Running on the command-line for your operating system?  You need it now.

Updating source from the command line

On Windows, you will need to open a new Command Prompt.  On Mac OS, open the Terminal application.

Command-line tools are powerful, and can permanently damage your system if misused. Make sure you only run parts of LilyPond, and that you only run them on “.ly” and “.ily” files.

You will now need to run “convert-ly”, from whichever folder it was installed to, and run it on the folder containing the “King Arthur” source files ((For more information on “convert-ly” and why it is needed, read Updating files with convert-ly in the LilyPond documentation.)).

There is a separate compatibility problem in one of the subfolders: “commons/Couverture.ily”.  You will need to run “convert-ly” on this one, too.

On Mac OS, you can almost avoid this step.  The Mac OS LilyPond application has an “Update syntax” option in the “Compile” menu.  This will allow you to fix the “.ly” files, which is enough to generate PDFs.  But, you still see errors due to “Couverture.ily”, and there is no way to fix that from within the LilyPond application.

Was that really worthwhile?

Well, we already have a nice-looking flute duet, and we can generate PDFs for every part and the score just as easily.  It’s about to get even better, too.

First line of the sheet music for the flute duet in act 2 of "King Arthur" by Henry Purcell.

Did LilyPond create this PDF for you?

Where did this French come from?  Wasn’t Purcell English?

The copyist for this version of “King Arthur” was French, and wrote the cues and titles in French.  However, he kindly provided a way to replace all the text with English.  Remember when we opened the “Readme” file?  It contains this section.

In order to have an English version, just replace, in the
Language.ily file, the line 

  \include "commons/Language-fr.ily"


  \include "commons/Language-en.ily"

For any other language, please build your native catalogue by copying




where LL corresponds to your language, and translate all variables' value.
You can then generate your own booklets after having adapted Language.ily
according to you needs.

Open that one file, change one line, and any further PDFs you create will be in English.  The power of LilyPond makes this sort of substitution easy.

Are there substitute parts, like the substitute language?

Sometimes a generous copyist will provide some.  There are none for Purcell, but in the next section we’ll learn how to create our own parts to suit the instruments available.

More LilyPond

  1. What is a LilyPond file?
  2. How do I read this LilyPond file?
  3. How do I edit a LilyPond file?
  4. How do I transpose a LilyPond part?
  5. Can I import a LilyPond file into my graphical notation editor?

Leave a Reply

Your e-mail address will not be published or shared with third parties.

First comments from new name/e-mail combinations will be held in moderation.