LilyPond Notation Reference: 4.1.1 The \paper block

### 4.1.1 The `\paper` block

`\paper` blocks may be placed in three different places to form a descending hierarchy of `\paper` blocks:

- At the top of the input file, before all `\book`, `\bookpart`, and `\score` blocks.
- Within a `\book` block but outside all the `\bookpart` and `\score` blocks within that book.
- Within a `\bookpart` block but outside all `\score` blocks within that bookpart.

A `\paper` block cannot be placed within a `\score` block.

The values of the fields filter down this hierarchy, with the values set higher in the hierarchy persisting unless they are overridden by a value set lower in the hierarchy.

Several `\paper` blocks can appear at each of the levels, for example as parts of several `\include`d files. If so, the fields at each level are merged, with values encountered last taking precedence if duplicated fields appear.

Settings that can appear in a `\paper` block include:

- the `set-paper-size` scheme function,
- `\paper` variables used for customizing page layout, and
- markup definitions used for customizing the layout of headers, footers, and titles.

The `set-paper-size` function is discussed in the next section, Paper size and automatic scaling. The `\paper` variables that deal with page layout are discussed in later sections. The markup definitions that deal with headers, footers, and titles are discussed in Custom titles headers and footers.

Most `\paper` variables will only work in a `\paper` block. The few that will also work in a `\layout` block are listed in The `\layout` block.

Except when specified otherwise, all `\paper` variables that correspond to distances on the page are measured in millimeters, unless a different unit is specified by the user. For example, the following declaration sets `top-margin` to ten millimeters:

>     \paper {
>       top-margin = 10
>     }

To set it to `0.5` inches, use the `\in` unit suffix:

>     \paper {
>       top-margin = 0.5\in
>     }

The available unit suffixes are `\mm`, `\cm`, `\in`, `\pt`, and `\bp`. These units are simple values for converting from millimeters; they are defined in ‘`ly/paper-defaults-init.ly`’. For the sake of clarity, when using millimeters, the `\mm` is typically included in the code, even though it is not technically necessary.

It is also possible to define `\paper` values using Scheme. The Scheme equivalent of the above example is:

>     \paper {
>       #(define top-margin (* 0.5 in))
>     }

#### See also

Notation Reference: Paper size and automatic scaling, Custom titles headers and footers, The `\layout` block.

Installed Files: ‘`ly/paper-defaults-init.ly`’.

#### LilyPond — Notation Reference v2.24.4 (stable-branch).