> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/niri-wm/niri/llms.txt
> Use this file to discover all available pages before exploring further.

# Include Files

> Split your niri configuration across multiple files

<Info>
  Available since version 25.11
</Info>

You can include other files at the top level of the config.

```kdl theme={null}
// Some settings...

include "colors.kdl"

// Some more settings...
```

Included files have the same structure as the main config file. Settings from included files will be merged with the settings from the main config file.

Included config files can in turn include more files. All included files are watched for changes, and the config live-reloads when any of them change.

<Warning>
  Includes work only at the top level of the config:

  ```kdl theme={null}
  // All good: include at the top level.
  include "something.kdl"

  layout {
      // NOT allowed: include inside some other section.
      include "other.kdl"
  }
  ```
</Warning>

## Positionality

Includes are *positional*. They will override options set *prior* to them. Window rules from included files will be inserted at the position of the `include` line.

### Example: Overriding Settings

```kdl theme={null}
// colors.kdl
layout {
    border {
        active-color "green"
    }
}

overview {
    backdrop-color "green"
}
```

```kdl theme={null}
// config.kdl
layout {
    border {
        active-color "red"
    }
}

// This overrides the border color and the backdrop color to green.
include "colors.kdl"

// This sets the overview backdrop color to red again.
overview {
    backdrop-color "red"
}
```

The end result:

* The border color is green (from `colors.kdl`)
* The overview backdrop color is red (it was set *after* `colors.kdl`)

### Example: Window Rules Position

```kdl theme={null}
// rules.kdl
window-rule {
    match app-id="Alacritty"
    open-maximized false
}
```

```kdl theme={null}
// config.kdl
window-rule {
    open-maximized true
}

// Window rules get inserted at this position.
include "rules.kdl"

window-rule {
    match app-id="firefox$"
    open-maximized true
}
```

This is equivalent to:

```kdl theme={null}
window-rule {
    open-maximized true
}

// Included from rules.kdl.
window-rule {
    match app-id="Alacritty"
    open-maximized false
}

window-rule {
    match app-id="firefox$"
    open-maximized true
}
```

## Optional Includes

<Info>
  Available since next release
</Info>

By default, including a nonexistent file will cause an error. You can allow nonexistent includes by setting `optional=true`:

```kdl theme={null}
// Won't fail if this file doesn't exist.
include optional=true "optional-config.kdl"

// Regular include, will fail if the file doesn't exist.
include "required-config.kdl"
```

<Note>
  When an optional include file is missing, niri will emit a warning in the logs on every config reload. This reminds you that the file is missing while still loading the config successfully.

  The optional file is still watched for changes, so if you create it later, the config will automatically reload and apply the new settings.
</Note>

<Warning>
  Note that `optional` only affects whether a missing file causes an error. If the file exists but contains invalid syntax or other errors, those errors will still cause a parsing failure.
</Warning>

## Merging Behavior

Most config sections are merged between includes, meaning that you can set only a few properties, and only those properties will change.

### Standard Merging

```kdl theme={null}
// colors.kdl
layout {
    // Does not affect gaps, border width, etc.
    // Only changes colors as written.
    focus-ring {
        active-color "blue"
    }

    border {
        active-color "green"
    }
}
```

```kdl theme={null}
// config.kdl
include "colors.kdl"

layout {
    // Does not set border and focus-ring colors,
    // so colors from colors.kdl are used.
    gaps 8

    border {
        width 8
    }
}
```

### Multipart Sections

Multipart sections like `window-rule`, `output`, or `workspace` are inserted as is without merging:

```kdl theme={null}
// laptop.kdl
output "eDP-1" {
    // ...
}
```

```kdl theme={null}
// config.kdl
output "DP-2" {
    // ...
}

include "laptop.kdl"

// End result: both DP-2 and eDP-1 settings.
```

### Binds

`binds` will override previously-defined conflicting keys:

```kdl theme={null}
// binds.kdl
binds {
    Mod+T { spawn "alacritty"; }
}
```

```kdl theme={null}
// config.kdl
include "binds.kdl"

binds {
    // Overrides Mod+T from binds.kdl.
    Mod+T { spawn "foot"; }
}
```

### Flags

Most flags can be disabled with `false`:

```kdl theme={null}
// csd.kdl

// Write "false" to explicitly disable.
prefer-no-csd false
```

```kdl theme={null}
// config.kdl

// Enable prefer-no-csd in the main config.
prefer-no-csd

// Including csd.kdl will disable it again.
include "csd.kdl"
```

### Non-merging Sections

Some sections where the contents represent a combined structure are not merged. Examples are `struts`, `preset-column-widths`, individual subsections in `animations`, pointing device sections in `input`.

```kdl theme={null}
// struts.kdl
layout {
    struts {
        left 64
        right 64
    }
}
```

```kdl theme={null}
// config.kdl
layout {
    struts {
        top 64
        bottom 64
    }
}

include "struts.kdl"

// Struts are not merged.
// End result is only left and right struts.
```

## Border Special Case

<Warning>
  There's one special case that differs between the main config and included configs.

  Writing `layout { border {} }` in an included config does nothing (since no properties are changed). However, writing the same in the main config will *enable* the border, i.e. it's equivalent to `layout { border { on; } }`.
</Warning>

So, if you want to move your layout configuration from the main config to a separate file, remember to add `on` to the border section:

```kdl theme={null}
// separate.kdl
layout {
    border {
        // Add this line:
        on

        width 4
        active-color "#ffc87f"
        inactive-color "#505050"
    }
}
```

<Note>
  The reason for this special case is historical: back when borders were added, there were no `on` flags, so writing the `border {}` section would enable the border, with an explicit `off` to disable it. Many people likely have this part of the default config embedded in their configs now, so changing how it works would cause confusion.
</Note>

## Use Cases

### Separate Color Schemes

```kdl theme={null}
// colors-dark.kdl
layout {
    border {
        active-color "#7fc8ff"
        inactive-color "#505050"
    }
    focus-ring {
        active-color "#7fc8ff"
    }
}
```

### Shared Bindings

```kdl theme={null}
// binds-common.kdl
binds {
    Mod+T { spawn "alacritty"; }
    Mod+Q { close-window; }
    // ... more common binds
}
```

### Device-Specific Settings

```kdl theme={null}
// laptop.kdl
output "eDP-1" {
    mode "1920x1080@60"
    scale 1.5
}

input {
    touchpad {
        tap
        natural-scroll
    }
}
```