LilyPond Notation Reference: 4.2.1 The \layout block

### 4.2.1 The `\layout` block

While the `\paper` block contains settings that relate to the page formatting of the whole document, the `\layout` block contains settings for score-specific layout. To set score layout options globally, enter them in a toplevel `\layout` block. To set layout options for an individual score, enter them in a `\layout` block inside the `\score` block, after the music. Settings that can appear in a `\layout` block include:

- the `layout-set-staff-size` scheme function,
- context modifications in `\context` blocks, and
- `\paper` variables that affect score layout.

The `layout-set-staff-size` function is discussed in the next section, Setting the staff size. Context modifications are discussed in a separate chapter; see Modifying context plug-ins and Changing context default settings.

The `\paper` variables that can appear in a `\layout` block, with default values taken from the `\paper` block are:

- `line-width`, `ragged-right` and `ragged-last` (see `\paper` variables for widths and margins)
- `indent` and `short-indent` (see `\paper` variables for shifts and indents)
- `system-count` (see `\paper` variables for line breaking)

Here is an example `\layout` block:

>     \layout {
>       indent = 2\cm
>       \context {
>         \StaffGroup
>         \override StaffGrouper.staff-staff-spacing.basic-distance = #8
>       }
>       \context {
>         \Voice
>         \override TextScript.padding = #1
>         \override Glissando.thickness = #3
>       }
>     }

Multiple `\layout` blocks can be entered as toplevel expressions. This can, for example, be useful if different settings are stored in separate files and included optionally. Internally, when a `\layout` block is evaluated, a copy of the current `\layout` configuration is made, then any changes defined within the block are applied and the result is saved as the new current configuration. From the user’s perspective the `\layout` blocks are combined, but in conflicting situations (when the same property is changed in different blocks) the later definitions take precedence.

For example, if this block:

>     \layout {
>       \context {
>         \Voice
>         \override TextScript.color = #magenta
>         \override Glissando.thickness = #1.5
>       }
>     }

is placed after the one from the preceding example the `padding` and `color` overrides for `TextScript` are combined, but the later `thickness` override for `Glissando` replaces (or hides) the earlier one.

`\layout` blocks may be assigned to variables for reuse later, but the way this works is slightly but significantly different from writing them literally.

If a variable is defined like this:

>     layoutVariable = \layout {
>       \context {
>         \Voice
>         \override NoteHead.font-size = #4
>       }
>     }

it will hold the current `\layout` configuration with the `NoteHead.font-size` override added, but this combination is not saved as the new current configuration. Be aware that the ‘current configuration’ is read when the variable is defined and not when it is used, so the content of the variable is dependent on its position in the source.

The variable can then be used inside another `\layout` block, for example:

>     \layout {
>       \layoutVariable
>       \context {
>         \Voice
>         \override NoteHead.color = #red
>       }
>     }

A `\layout` block containing a variable, as in the example above, does not copy the current configuration but instead uses the content of `\layoutVariable` as the base configuration for the further additions. This means that any changes defined between the definition and the use of the variable are lost.

If `layoutVariable` is defined (or `\include`d) immediately before being used, its content is just the current configuration plus the overrides defined within it. So in the example above showing the use of `\layoutVariable` the final `\layout` block would consist of:

>       TextScript.padding = #1
>       TextScript.color = #magenta
>       Glissando.thickness = #1.5
>       NoteHead.font-size = #4
>       NoteHead.color = #red

plus the `indent` and the `StaffGrouper` overrides.

But if the variable had already been defined before the first `\layout` block the current configuration would now contain only

>       NoteHead.font-size = #4 % (written in the variable definition)
>       NoteHead.color = #red % (added after the use of the variable)

If carefully planned, `\layout` variables can be a valuable tool to structure the layout design of sources, and also to reset the `\layout` configuration to a known state.

#### See also

Notation Reference: Changing context default settings.

Snippets: Spacing.

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