Install

One path for both plugins: build the picom fork, build the two plugins against it, and add a few lines to picom.conf and the i3 config.

Read What is checked first: this runs every day on one machine, and much less has been tried elsewhere. The code was written with AI; see a note before you read on.

What you need

  • X11 and a stock i3.
  • A GPU with OpenGL and EGL, for picom's egl backend. glx works too, and draws the same; egl is the one used and measured, because it can give picom's GPU work priority over the programs' drawing.
  • picom's build tools and libraries: meson, ninja and the libraries listed in picom's README. For the man page, asciidoctor.
  • For the plugins: make, pkg-config, a C compiler that knows C23 (GCC 14 or clang 18 and later), and the headers of xcb, xcb-damage, xcb-randr, xcb-xfixes, xcb-sync and pixman.

Clone the three repositories side by side, in one directory. Each block below starts in that directory.

1. The picom fork

The winanim branch: picom's development branch with the plugin API and the other changes on top.

git clone --branch winanim https://github.com/JornC/picom.git
cd picom
meson setup --buildtype=release build
ninja -C build
sudo ninja -C build install

This installs picom under /usr/local, next to your distribution's picom; /usr/local/bin comes first on most systems. Add -Dwith_docs=true to meson setup for the man page.

Arch's own picom package adds one small patch from picom, for a black screen with the glx backend on some GPUs. If you see that, apply it before you build, in the picom directory: curl -L https://github.com/yshui/picom/commit/676196359c15bb654696b05700330685db914710.patch | patch -Np1

2. ws-direction

git clone https://github.com/JornC/picom-ws-direction-plugin.git
cd picom-ws-direction-plugin
make PICOM_API_CFLAGS=-I../picom/include
make install PICOM_API_CFLAGS=-I../picom/include

This puts the plugin in ~/.config/picom/plugins/, the styles in ~/.config/picom/include/ws-direction/, the ws-direction command in ~/.local/bin/ and its man page in ~/.local/share/man/man1/. picom finds the plugin and the styles there by name. make uninstall takes them away again.

3. win-cause

git clone https://github.com/JornC/picom-win-cause-plugin.git
cd picom-win-cause-plugin
make PICOM_API_CFLAGS=-I../picom/include
make install PICOM_API_CFLAGS=-I../picom/include

The same places: the plugin in ~/.config/picom/plugins/, the styles in ~/.config/picom/include/win-cause/, and the win-cause command in ~/.local/bin/.

4. picom.conf

A workspace style, the overview, and the tile style for windows:

# egl asks the GPU to put picom's frames before the programs' drawing.
backend = "egl";
vsync = true;
# Keep picom compositing over fullscreen windows: otherwise
# it drops the pictures of hidden windows that styles draw.
unredir-if-possible = false;

plugins = ["ws-direction.so", "win-cause.so"];
rules = ({
  match = "!override_redirect && window_type = 'normal'";
  @include "ws-direction/slide.conf"
}, {
  match = "!override_redirect && window_type = 'normal'";
  @include "ws-direction/wall.conf"
}, {
  match = "!override_redirect && window_type = 'normal'";
  @include "win-cause/tile.conf"
}, {
  match = "!override_redirect && window_type = 'normal' && !I3_FLOATING_WINDOW@";
  @include "win-cause/tile-geometry.conf"
});

To try another style, change its name and save; picom reloads by itself. The styles are on the Workspaces and Windows pages.

5. The i3 config

Start picom and bind the overview:

# Start picom, then fill in the pictures of hidden workspaces.
exec_always --no-startup-id picom -b && ws-direction warm

# The overview: $mod+Tab opens it, the arrows move,
# Return, Escape or $mod+Tab close it, a click picks a window.
set $overview exec --no-startup-id ws-direction overview
bindsym $mod+Tab mode "overview"; $overview open --wait && i3-msg -q mode default
mode "overview" {
    bindsym Left workspace prev_on_output
    bindsym Up workspace prev_on_output
    bindsym Right workspace next_on_output
    bindsym Down workspace next_on_output
    bindsym Return mode "default"; $overview close
    bindsym Escape mode "default"; $overview close
    bindsym $mod+Tab mode "default"; $overview close
}

i3 must find ws-direction and win-cause on its PATH. ~/.local/bin is often not on the PATH of a window manager that a display manager starts; then give the full path.

6. NVIDIA: turn OpenGL flipping off

nvidia-settings -n -a AllowFlipping=0

With two monitors at different rates on one X screen (here 175 Hz and 60 Hz), the driver's OpenGL flipping made picom's frames wait for the 60 Hz monitor, whatever picom's own vsync setting was. With flipping off, frames came at 175 Hz again, and late frames fell from about 26% to 10%. The numbers are under Under the hood.

It is a driver setting for every OpenGL program, not only picom, and -n doesn't save it, so run it each time before picom starts. Check for tearing on every monitor, and in fullscreen games. My i3 line, used instead of the first picom line above, also syncs picom to the fast monitor (DFP-1, as nvidia-settings names it):

exec_always --no-startup-id sh -c 'nvidia-settings -n -a AllowFlipping=0 >/dev/null 2>&1; pgrep -x picom >/dev/null || __GL_SYNC_DISPLAY_DEVICE=DFP-1 picom -b'

With one monitor, or all monitors at one rate, this may not matter. That hasn't been measured.

Check that it works

  • picom --diagnostics lists ws-pass, ws-unfold and ws-fold under "Custom animation triggers" when picom loaded ws-direction.
  • ws-direction --version prints the version, and shows that the command is on your PATH.
  • Start picom with WS_DIRECTION_LOG=/path/to/file in its environment, and ws-direction writes every switch it sees there, and why.
  • A plugin that can't start says why on picom's standard error, in a line that starts with its name.

What is checked

  • In daily use: my machine. Arch Linux, NVIDIA, stock i3, two monitors, egl, built with my own Arch package from the same code.
  • The commands on this page come from picom's README, the plugins' Makefiles and READMEs, and my package recipe. The build steps were run on local clones of the same branches, and the picom.conf above loads in the built picom with both plugins. They were not yet run from a fresh clone of the public repositories.
  • Not tried: other distributions, AMD and Intel GPUs, and window managers other than i3.

If something doesn't work, an issue on the plugin's repository helps, with what you ran and what it said.