> ## 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.

# Integrating niri

> Essential information for integrating niri in a Linux distribution

This page contains various bits of information helpful for integrating niri in a distribution.

<Info>
  For creating a niri package, see the [Packaging](/development/packaging-niri) page.
</Info>

## Configuration

Niri will load configuration from `$XDG_CONFIG_HOME/niri/config.kdl` or `~/.config/niri/config.kdl`, falling back to `/etc/niri/config.kdl`.

If both of these files are missing, niri will create `$XDG_CONFIG_HOME/niri/config.kdl` with the contents of [the default configuration file](https://github.com/niri-wm/niri/blob/main/resources/default-config.kdl), which are embedded into the niri binary at build time.

### Distribution Defaults

You can customize your distribution defaults by creating `/etc/niri/config.kdl`.

<Warning>
  When `/etc/niri/config.kdl` is present, niri will **not** automatically create a config at `~/.config/niri/`, so you'll need to direct your users how to do it themselves.
</Warning>

<Note>
  Keep in mind that we update the default config in new releases, so if you have a custom `/etc/niri/config.kdl`, you likely want to inspect and apply the relevant changes too.
</Note>

### Configuration Overrides

The default configuration locations can be overridden with the `NIRI_CONFIG` environment variable.

<Info>
  **Since: next release** - You can also change the configuration path at runtime via the niri IPC or using the command:

  ```bash theme={null}
  niri msg action load-config-file --path <path-to-config.kdl>
  ```
</Info>

<Info>
  **Since: 25.11** - You can split the niri config file into multiple files using [`include`](/configuration/include).
</Info>

## Xwayland

Xwayland is required for running X11 apps and games, and also the Orca screen reader.

<Info>
  **Since: 25.08** - Niri integrates with [xwayland-satellite](https://github.com/Supreeeme/xwayland-satellite) out of the box.
</Info>

### xwayland-satellite Integration

The integration requires xwayland-satellite >= 0.7 available in `$PATH`.

<Tip>
  Please consider making niri depend on (or at least recommend) the xwayland-satellite package.
</Tip>

<Warning>
  If you had a custom config which manually started `xwayland-satellite` and set `$DISPLAY`, you should remove those customizations for the automatic integration to work.
</Warning>

You can change the path where niri looks for xwayland-satellite using the [`xwayland-satellite` top-level option](/configuration/miscellaneous#xwayland-satellite).

## Keyboard Layout

<Info>
  **Since: 25.08** - By default (unless [manually configured](/configuration/input#layout) otherwise), niri reads keyboard layout settings from systemd-localed at `org.freedesktop.locale1` over D-Bus.
</Info>

Make sure your system installer sets the keyboard layout via systemd-localed, and niri should pick it up.

## Autostart

Niri works with the normal systemd autostart. The default [niri.service](https://github.com/niri-wm/niri/blob/main/resources/niri.service) brings up `graphical-session.target` as well as `xdg-desktop-autostart.target`.

### Autostart Methods

To make a program run at niri startup without editing the niri config, you can use one of these methods:

<CardGroup cols={2}>
  <Card title="Desktop Files" icon="file">
    Link its .desktop file to `~/.config/autostart/`
  </Card>

  <Card title="systemd Services" icon="gear">
    Use a .service file with `WantedBy=graphical-session.target`
  </Card>
</CardGroup>

<Info>
  See the [example systemd setup](/integration/example-systemd-setup) page for detailed examples.
</Info>

If this is inconvenient, you can also add [`spawn-at-startup`](/configuration/miscellaneous#spawn-at-startup) lines in the niri config.

## Screen Readers

<Info>
  **Since: 25.08** - Niri works with the [Orca](https://orca.gnome.org) screen reader.
</Info>

Please see the [Accessibility](/features/accessibility) page for details and advice for accessibility-focused distributions.

## Desktop Components

### Essential Components

You very likely want to run at least:

* Notification daemon
* Portals
* Authentication agent

<Info>
  This is detailed on the [Important Software](/important-software) page.
</Info>

### Shell Components

On top of that, you may want to preconfigure some desktop shell components to make the experience less barebones.

#### Waybar

Niri's default config spawns [Waybar](https://github.com/Alexays/Waybar), which is a good starting point.

<Tip>
  You may want to consider changing its default configuration to be less of a kitchen sink, and adding the `niri/workspaces` module.
</Tip>

#### Background and Screen Locker

You will probably also want:

* **Desktop background tool**: [swaybg](https://github.com/swaywm/swaybg) or [awww (which used to be swww)](https://codeberg.org/LGFae/awww/)
* **Screen locker**: [hyprlock](https://github.com/hyprwm/hyprlock/) (a nicer alternative to the default `swaylock`)

### Complete Desktop Environments

Alternatively, some desktop environments and shells work with niri, and can give a more cohesive experience in one package:

<CardGroup cols={2}>
  <Card title="LXQt" icon="desktop" href="https://lxqt-project.org/wiki/Wayland-Session">
    Officially supports niri. See their wiki for setup details.
  </Card>

  <Card title="XFCE" icon="desktop" href="https://wiki.xfce.org/releng/wayland_roadmap#component_specific_status">
    Many components work on Wayland, including niri.
  </Card>

  <Card title="Quickshell Desktops" icon="desktop">
    Complete shells like [DankMaterialShell](https://github.com/AvengeMedia/DankMaterialShell) and [Noctalia](https://github.com/noctalia-dev/noctalia-shell)
  </Card>

  <Card title="COSMIC" icon="desktop" href="https://github.com/Drakulix/cosmic-ext-extra-sessions">
    Run a COSMIC session with niri using cosmic-ext-extra-sessions
  </Card>
</CardGroup>