[ << Running lilypond ]	[Top][Contents][Index]	[ Updating files with convert-ly >> ]
[ < Invoking lilypond ]	[ Up : Command-line usage ]	[ Advanced command-line options for LilyPond > ]

---

Basic command-line options for LilyPond

Please bear in mind that option arguments with spaces in it must be quoted. For example, to write LilyPond’s output to a directory called ‘foo bar’, a user must add -o "foo bar" (or --output="foo bar") to the command-line arguments of lilypond. Double quotes around such arguments work with virtually all command-line interpreters on both Windows and Unix-like operating systems (including macOS).

The following options are supported.

-d, --define-default=var[=val]

See Advanced command-line options for LilyPond.

-e, --evaluate=expr

Evaluate the Scheme expression expr before parsing any .ly files. Multiple -e options may be given, they are evaluated sequentially.

The expression is evaluated in the guile-user module, so if you want to use a definition like (define-public a 42) as expr, use

lilypond -e "(define-public a 42)"

on the command line, and include

#(use-modules (guile-user))

at the top of the .ly file.

-E, --eps

Generate EPS files.

This option is equivalent to specifying -dseparate-page-formats=eps -dtall-page-formats=eps.

-f, --format=format

The format of the (main) output file or files. Possible values for format are ps, pdf, png or svg.

Example: lilypond -fpng foo.ly

SVG internally uses a specific backend, and therefore cannot be obtained in the same run as other formats; using -fsvg or --svg is actually equivalent to using the -dbackend=svg option. See Advanced command-line options for LilyPond.

-h, --help

Show a summary of usage.

-H, --header=field

Dump a header field to file BASENAME.field.

As an example, let’s assume that you have an input file foo.ly containing

\header { title = "bar" }
\score { c1 }

The command

lilypond -H title foo.ly

then creates a plain text file foo.title containing the string bar.

-i, --init=file

Set init file to file (default: init.ly).

-I, --include=directory

Append directory to the search path for input files with relative paths. By default, only the current working directory gets searched.

Multiple -I options may be given. The search starts in the current working directory, and if the file to be included is not found the search continues in the directory given by the first -I option, then the directory in the second -I option, and so on.

Note: Using the tilde character (~) with the -I switch may produce unexpected results in some shells.

Windows users need to include a trailing slash for the directory’s path.

-j, --jail=user,group,jail,dir

[This option is only available if your operating system supports the chroot functionality. In particular, Windows doesn’t support it.]

Run lilypond in a chroot jail.

The --jail option can be used for security when LilyPond formatting is being provided via a web server, or whenever LilyPond executes commands sent by external sources (see Advanced command-line options for LilyPond). Because LilyPond provides the ability to run Guile programs, it is essential in such scenarios to run it in a sandboxed way so that the file being compiled does not wreak havoc on the system, for example with

% too dangerous to write correctly
#(s ystem "rm -rf /")
% malicious but not destructive
{ c4^$(ly:gulp-file "/etc/passwd") }

--jail is one way to achieve sandboxing. Another one is running LilyPond in a Docker container.

The --jail option works by changing the root of lilypond to jail just before starting the actual compilation process. The user and group are then changed to match those provided, and the current directory is changed to dir. This setup guarantees that it is not possible (at least in theory) to escape from the jail. Note that for --jail to work, lilypond must be run as root, which is usually accomplished in a safe way using sudo.

Setting up a jail can be a relatively complex matter, as we must be sure that LilyPond is able to find whatever it needs to compile the source inside the jail itself. A typical chroot jail comprises the following steps:

Setting up a separate filesystem

A separate filesystem should be created for LilyPond, so that it can be mounted with safe options such as noexec, nodev, and nosuid. In this way, it is impossible to run executables or to write directly to a device from LilyPond. If you do not want to create a separate partition, just create a file of reasonable size and use it to mount a loop device. A separate filesystem also guarantees that LilyPond cannot write more space than it is allowed.

Setting up a separate user

A separate user and group (say, lily/lily) with low privileges should be used to run LilyPond inside the jail. There should be a single directory writable by this user, which should be passed in dir.

Preparing the jail

LilyPond needs to read a number of files while running. All these files are to be copied into the jail, under the same path they appear in the real root filesystem. The entire content of the LilyPond installation (e.g., /usr/share/lilypond) should be copied.

If problems arise, the simplest way to trace them down is to run LilyPond using strace, which allows you to determine which files are missing.

Running LilyPond

In a jail mounted with noexec it is impossible to execute any external program. Therefore LilyPond must be run with a backend that does not require any such program. As we have already mentioned, it must be run with supernotation privileges (which, of course, it loses immediately), possibly using sudo. It is also good practice to limit the number of seconds of CPU time LilyPond can use (e.g., using ulimit -t), and, if your operating system supports it, the amount of memory that can be allocated. See LilyPond in chroot jail for more.

-l, --loglevel=level

Set the verbosity of the console output to level. Possible values are:

NONE

No output at all, not even error messages.

ERROR

Only error messages, no warnings or progress messages.

WARN

Warnings and error messages, no progress.

BASIC

Basic progress messages (success), warnings and errors.

PROGRESS

All progress messages, warnings and errors.

INFO

Progress messages, warnings, errors and further execution information. This is the default.

DEBUG

All possible messages, including verbose debug output.

-o, --output=file

-o, --output=folder

Set the default output file to file or, if a folder with that name exists, direct the output to folder, taking the file name from the input file. The appropriate suffix is added (e.g., .pdf for PDF) in both cases.

-O, --pspdfopt=key ¶

Set the PS/PDF output optimization to key. Possible values are:

size

Generate a very small PS/EPS/PDF document. This is the default.

Using this value is equivalent to setting LilyPond’s Scheme command-line options -dmusic-font-encodings="#f" and -dgs-never-embed-fonts="#f".

TeX

Produce files that are optimized for inclusion in pdfTeX, LuaTeX, or XeTeX documents.

Using this value is equivalent to setting LilyPond’s Scheme command-line options -dmusic-font-encodings="#t" and -dgs-never-embed-fonts="#f".

TeX-GS

If you want to include more than one PDF generated by LilyPond in a TeX document, use this option and postprocess the PDF generated by TeX with Ghostscript.

Using this value is equivalent to setting LilyPond’s Scheme command-line options -dmusic-font-encodings="#t" and -dgs-never-embed-fonts="#t".

--ps

Generate PostScript. This option is equivalent to -fps.

--png

Generate pictures of each page, in PNG format. This option is equivalent to -fpng.

The resolution of the image may be set to N DPI with

-dresolution=N

--pdf

Generate PDF. This is the default, being equivalent to -fpdf.

-s, --silent

Show no progress, only error messages. This is equivalent to -lERROR.

--svg

Generate SVG files for each page. This option is equivalent to -fsvg.

-v, --version

Show version information.

-V, --verbose

Be verbose: show full paths of all files read, give timing information, etc. It is equivalent to -lDEBUG.

-w, --warranty

Show the warranty with which GNU LilyPond comes. (It comes with NO WARRANTY!)