3.4.1 Including LilyPond files

A large project may be split up into separate files. To refer to another file, use

\include "otherfile.ly"

The line \include "otherfile.ly" is equivalent to pasting the contents of otherfile.ly into the current file at the place where the \include appears. For example, in a large project you might write separate files for each instrument part and create a “full score” file which brings together the individual instrument files. Normally the included file will define a number of variables which then become available for use in the full score file. Tagged sections can be marked in included files to assist in making them usable in different places in a score, see Different editions from one source.

Files in the current working directory may be referenced by specifying just the file name after the \include command. Files in other locations may be included by giving either a full path reference or a relative path reference (but use the UNIX forward slash, /, rather than the DOS/Windows back slash, \, as the directory separator.) For example, if stuff.ly is located one directory higher than the current working directory, use

\include "../stuff.ly"

or if the included orchestral parts files are all located in a subdirectory called parts within the current directory, use

\include "parts/VI.ly"
\include "parts/VII.ly"
… etc

Files which are to be included can also contain \include statements of their own. These second-level \include statements are then interpreted relatively to the path of the file containing that command, which is convenient for multiple files located in the same subdirectory. For example, a general library, ‘libA’, may itself use subfiles which are \included by the entry file of that library, like this:

libA/
  libA.ly
  A1.ly
  A2.ly
  …

then the entry file, libA.ly, will contain

\include "A1.ly"
\include "A2.ly"
…

Any .ly file can then include the entire library simply with

\include "~/libA/libA.ly"

However, that behavior can be changed globally by passing the command-line option -drelative-includes=#f, or by adding #(ly:set-option 'relative-includes #f) at the top of the main input file. In that case, each file will be included relatively to the location of the main file, regardless of where its \include statement is located. Complex file structures, that require to \include both files relative to the main directory and files relative to some other directory, may even be devised by setting relative-includes to #f or #t at appropriate places in the files.

Files can also be included from a directory in a search path specified as an option when invoking LilyPond from the command line. The included files are then specified using just their file name. For example, to compile main.ly which includes files located in a subdirectory called parts by this method, change to the directory containing main.ly and enter

lilypond --include=parts main.ly

and in main.ly write

\include "VI.ly"
\include "VII.ly"
… etc

Files which are to be included in many scores may be placed in the LilyPond directory ../ly. (The location of this directory is installation-dependent – see Other sources of information). These files can then be included simply by naming them on an \include statement. This is how the language-dependent files like english.ly are included.

LilyPond includes a number of files by default when you start the program. These includes are not apparent to the user, but the files may be identified by running lilypond --verbose from the command line. This will display a list of paths and files that LilyPond uses, along with much other information. Alternatively, the more important of these files are discussed in Other sources of information. These files may be edited, but changes to them will be lost on installing a new version of LilyPond.

Some simple examples of using \include are shown in Scores and parts.

See also

Learning Manual: Other sources of information, Scores and parts.

Known issues and warnings

If an included file is given a name which is the same as one in LilyPond’s installation files, LilyPond’s file from the installation files takes precedence.