Configuring the picom compositor on Debian GNU/Linux

Summary

Compton is no longer maintained, and since we are told to migrate to picom^[1] [see also deprecated], I am leaving this migration document.

Until the configuration becomes stable, I will rewrite the content as I learn more. If you check back occasionally, the content might have changed. (Actually, I might run out of energy before researching exactly what the configuration file should look like, so I'll start by summarizing the points to look into and publishing them as an open method.)

Introduction

There is a program called a composite manager^[2] that manages the appearance of windows. I'll leave the formal definition to others, but I use the tiling window manager i3wm^[3] and use a composite manager primarily to achieve better recognition through visual enhancements (effects). --- How much time you should spend on these settings depends on the person, so I would be grateful if useful settings were shared. I would be happy if publishing this document leads to more users, so if possible, I would appreciate it if you could publish your settings and write documentation as well.

The author of this document uses Debian GNU/Linux Sid. I hope this information will also be useful for people using i3wm etc. on Bullseye, the next release of Debian GNU/Linux, when they set up a composite manager. Of course, I will write about distribution-dependent parts as far as I notice them, so I believe I can provide information to people using other distributions as well.

Who is this article for?

People who need to configure the composite manager picom, especially those using Debian GNU/Linux bullseye or later.

How to read this document

Main Body

Configuration File Location

I decided to place the configuration file at ~/.config/picom/picom.conf, which is an XDG-compliant location. For other locations, please read the following "How to find it" section. If you are not particularly interested, skip "How to find it" and proceed to "Configuration file contents".

How to find it

You can skip this part.

Capture the startup log using something like strace picom 2> /tmp/picom.log.

openat(AT_FDCWD, "/home/yabuki/.config/picom.conf", O_RDONLY) = -1 ENOENT (No such file or directory)
openat(AT_FDCWD, "/home/yabuki/.config/picom/picom.conf", O_RDONLY) = -1 ENOENT (No such file or directory)
openat(AT_FDCWD, "/home/yabuki/.config/compton.conf", O_RDONLY) = -1 ENOENT (No such file or directory)
openat(AT_FDCWD, "/home/yabuki/.config/compton/compton.conf", O_RDONLY) = -1 ENOENT (No such file or directory)
openat(AT_FDCWD, "/home/yabuki/.compton.conf", O_RDONLY) = -1 ENOENT (No such file or directory)
openat(AT_FDCWD, "/etc/xdg/picom.conf", O_RDONLY) = -1 ENOENT (No such file or directory)
openat(AT_FDCWD, "/etc/xdg/picom/picom.conf", O_RDONLY) = -1 ENOENT (No such file or directory)
openat(AT_FDCWD, "/etc/xdg/compton.conf", O_RDONLY) = -1 ENOENT (No such file or directory)
openat(AT_FDCWD, "/etc/xdg/compton/compton.conf", O_RDONLY) = -1 ENOENT (No such file or directory)

Although you can load a configuration file with picom --config path/to/config_file_name, it reads them in the order listed above, so it doesn't hurt to know that order. It is also useful for checking the location of existing configuration files when migrating from compton.

Configuration file contents

Where I got stuck

The following error occurs. However, there is no such entry in ~/.config/picom/picom.conf.

[ 2021年07月08日 08:20:48.077 parse_config_libconfig WARN ] Option `no-dock-shadow` is deprecated, and will be removed. Please use the wintype option `shadow` of `dock` instead.
[ 2021年07月08日 08:20:48.077 parse_config_libconfig WARN ] Option `no-dnd-shadow` is deprecated, and will be removed. Please use the wintype option `shadow` of `dnd` instead.
[ 2021年07月08日 08:20:48.077 parse_config_libconfig WARN ] Option `menu-opacity` is deprecated, and will be removed.Please use the wintype option `opacity` of `popup_menu` and `dropdown_menu` instead.
[ 2021年07月08日 08:20:48.078 parse_config_libconfig WARN ] vsync option will take a boolean from now on. "none" is interpreted as "false" for compatibility, but this will stop working soon
[ 2021年07月08日 08:20:48.078 parse_config_libconfig WARN ] glx-swap-method has been deprecated since v6, your setting "undefined" should be replaced by `use-damage = true`.
[ 2021年07月08日 08:20:48.078 parse_config_libconfig WARN ] "clear-shadow" is removed as an option, and is always enabled now. Consider removing it from your config file
[ 2021年07月08日 08:20:48.078 parse_config_libconfig ERROR ] "paint-on-overlay" has been removed as an option, and the feature is enabled whenever possible
[ 2021年07月08日 08:20:48.078 main FATAL ERROR ] Failed to create new session.

• Since ~/.config/compton.conf exists, ~/.config/picom.conf is automatically generated and read before ~/.config/picom/picom.conf, causing errors in parts of the file you didn't set yourself.
  • If you get an error regarding a setting you didn't write, remember this.

Related Information

deprecated

• Details for the compton package in sid

  • This package is deprecated and will soon be removed, please switch to picom.

compton-conf

For compton, there is a configuration file setting tool written in Qt. Details for the compton-conf package in sid. There is also an l10n package. Details for the compton-conf-l10n package in sid. However, since it is unclear to what extent the compton configuration files can be migrated, it might ultimately be faster to write the configuration file yourself. Since I have little expertise, I cannot say for certain.

Reference Documents

• yshui/picom: A lightweight compositor for X11
  • Official repository
• picom - Debian Package Tracker
  • Debian package tracker
  • File: picom.sample.conf | Debian Sources
    • Configuration file sample (accessed 2021-07-07)
• Picom - ArchWiki
  • A very helpful resource available in Japanese.
• 【Linux】コンポジットマネージャをComptonからPicomに移行する - 一応理系男子
  • This is a prior document. I felt I could contribute further as there were several points of interest, which led me to write this article.

compton related

• Details for the compton-conf package in sid
• Details for the compton-conf-l10n package in sid

Acknowledgements

Final Words

Subject	Date
Date article was written	2021-07-07
Date article was modified	2024-10-23

The above information was provided by the author to help judge the freshness of this article.

For detailed change history, please refer to GitHub - yabuki/friendly-potato: zenn-contents.

If you find typos or other issues in the article, I would appreciate a pull request. Whether it is accepted will be determined based on the diff and the description provided in the pull request.

脚注

1. In the official documentation, picom is consistently written as picom and not Picom, so I will use picom throughout this document.

2. In English-speaking circles, it seems to be called a compositor. See also picom - Debian Package Tracker. However, such notations also exist. They are similar but slightly different. Compositing window manager - Wikipedia

3. i3 - improved tiling wm is sometimes referred to as i3wm. While the official name of i3 seems to be i3, the term i3wm is also widely used, so I will use the i3wm notation in this document.