Installation

Compile-Time Dependencies

The following libraries must be installed before building Jay. They are linked at build time.

One-liner install commands:

Arch Linux:

~$ sudo pacman -S libinput mesa systemd-libs pango fontconfig

Fedora:

~$ sudo dnf install libinput-devel mesa-libgbm-devel systemd-devel pango-devel fontconfig-devel

Debian / Ubuntu:

~$ sudo apt install libinput-dev libgbm-dev libudev-dev libpango1.0-dev libfontconfig-dev

You also need a C compiler (GCC or Clang) and the latest stable version of Rust. Install Rust with rustup:

~$ curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

Runtime Dependencies

These libraries are loaded dynamically at runtime. Jay requires at least one working renderer – without one, no GPU can be initialized and nothing will be displayed.

For Vulkan, you also need the driver for your GPU:

Optional Runtime Dependencies

• Linux 6.7 or later – required for explicit sync (needed for Nvidia GPUs).
• Xwayland – required for running X11 applications.
• PipeWire – required for screen sharing.
• logind (part of systemd) – required when running Jay from a virtual terminal or display manager.

Building

AUR (Arch Linux)

Arch Linux users can install Jay from the AUR. Two packages are available:

• jay – builds the latest released version.
• jay-git – builds from the latest commit on the master branch.

Install with your preferred AUR helper, for example:

~$ yay -S jay

The AUR packages handle all compile-time dependencies automatically.

From crates.io (recommended)

~$ cargo install --locked jay-compositor

This installs the jay binary to ~/.cargo/bin/jay.

From git (latest development version)

~$ cargo install --locked --git https://github.com/mahkoh/jay.git jay-compositor

From a local clone

~$ git clone https://github.com/mahkoh/jay.git
~$ cd jay
~$ cargo build --release

The binary is then available at ./target/release/jay.

CAP_SYS_NICE (Optional)

Granting CAP_SYS_NICE to the Jay binary can improve responsiveness when the CPU or GPU are under heavy load:

~$ sudo setcap cap_sys_nice=p $(which jay)

When this capability is available, Jay will elevate its scheduler to SCHED_RR (real-time round-robin) and create Vulkan queues with the highest available priority. Both of these help Jay maintain smooth frame delivery under contention.

Jay drops all capabilities almost immediately after startup. A dedicated thread retains CAP_SYS_NICE solely for creating elevated Vulkan queues later.

Note

You need to re-run the setcap command each time you update the Jay binary.

SCHED_RR and config.so

SCHED_RR and config.so are mutually exclusive: running untrusted code at real-time priority would be a security risk. Jay enforces this as follows:

• If config.so exists in the config directory, Jay skips the SCHED_RR elevation (elevated Vulkan queues are still created).
• If Jay has already elevated to SCHED_RR, it refuses to load config.so.

You can also skip SCHED_RR explicitly by setting JAY_NO_REALTIME=1:

~$ JAY_NO_REALTIME=1 jay run

This still allows elevated Vulkan queues and does not affect config.so loading.

The mutual exclusion can be overridden at compile time by building Jay with JAY_ALLOW_REALTIME_CONFIG_SO=1.

Recommended Applications

The following applications work well with Jay:

• Alacritty – the default terminal emulator in the built-in configuration.
• bemenu – the default application launcher in the built-in configuration.
• xdg-desktop-portal-gtk4 – a file-picker portal with thumbnail support. Used automatically when installed.
• wl-tray-bridge – shows D-Bus StatusNotifierItem applications as tray icons.
• mako – a notification daemon. Launched automatically by the default configuration.
• window-to-tray – run most Wayland applications as tray applications (e.g. window-to-tray pavucontrol-qt).