PICOM(1) User Commands PICOM(1)
NAME
picom - a compositor for X11
SYNOPSIS
picom [OPTIONS]
DESCRIPTION
picom is a compositor based on Dana Jansens' version of xcompmgr (which
itself was written by Keith Packard). It includes some improvements
over the original xcompmgr, like window frame opacity and inactive
window transparency.
OPTIONS
-h, --help
Get the usage text embedded in program code, which may be more
up-to-date than this man page.
-r, --shadow-radius=RADIUS
The blur radius for shadows, in pixels. (defaults to 12)
-o, --shadow-opacity=OPACITY
The opacity of shadows. (0.0 - 1.0, defaults to 0.75)
-l, --shadow-offset-x=OFFSET
The left offset for shadows, in pixels. (defaults to -15)
-t, --shadow-offset-y=OFFSET
The top offset for shadows, in pixels. (defaults to -15)
-I, --fade-in-step=OPACITY_STEP
Opacity change between steps while fading in. (0.01 - 1.0, defaults
to 0.028)
-O, --fade-out-step=OPACITY_STEP
Opacity change between steps while fading out. (0.01 - 1.0,
defaults to 0.03)
-D, --fade-delta=MILLISECONDS
The time between steps in fade step, in milliseconds. (> 0,
defaults to 10)
-c, --shadow
Enabled client-side shadows on windows. Note desktop windows
(windows with _NET_WM_WINDOW_TYPE_DESKTOP) never get shadow, unless
explicitly requested using the wintypes option.
-f, --fading
Fade windows in/out when opening/closing and when opacity changes,
unless --no-fading-openclose is used.
-F
Equals to -f. Deprecated.
-i, --inactive-opacity=OPACITY
Opacity of inactive windows. (0.1 - 1.0, defaults to 1.0)
-e, --frame-opacity=OPACITY
Opacity of window titlebars and borders. (0.1 - 1.0, disabled by
default)
-b, --daemon
Daemonize process. Fork to background after initialization. This
option can only be set from the command line, setting this in the
configuration file will have no effect.
--log-level
Set the log level. Possible values are "TRACE", "DEBUG", "INFO",
"WARN", "ERROR", in increasing level of importance. Case doesn’t
matter. If using the "TRACE" log level, it’s better to log into a
file using --log-file, since it can generate a huge stream of logs.
--log-file
Set the log file. If --log-file is never specified, logs will be
written to stderr. Otherwise, logs will to written to the given
file, though some of the early logs might still be written to the
stderr. When setting this option from the config file, it is
recommended to use an absolute path.
--experimental-backends
Use the new, reimplemented version of the backends. The new
backends are HIGHLY UNSTABLE at this point, you have been warned.
This option is not available in the config file.
--show-all-xerrors
Show all X errors (for debugging).
--config PATH
Look for configuration file at the path. See CONFIGURATION FILES
section below for where picom looks for a configuration file by
default. Use /dev/null to avoid loading configuration file.
--write-pid-path PATH
Write process ID to a file. it is recommended to use an absolute
path.
--shadow-color STRING
Color of shadow, as a hex string (#000000)
--shadow-red VALUE
Red color value of shadow (0.0 - 1.0, defaults to 0).
--shadow-green VALUE
Green color value of shadow (0.0 - 1.0, defaults to 0).
--shadow-blue VALUE
Blue color value of shadow (0.0 - 1.0, defaults to 0).
--inactive-opacity-override
Let inactive opacity set by -i override the _NET_WM_WINDOW_OPACITY
values of windows.
--active-opacity OPACITY
Default opacity for active windows. (0.0 - 1.0, defaults to 1.0)
--inactive-dim VALUE
Dim inactive windows. (0.0 - 1.0, defaults to 0.0)
--corner-radius VALUE
Sets the radius of rounded window corners. When > 0, the compositor
will round the corners of windows. Does not interact well with
--transparent-clipping. (defaults to 0).
--rounded-corners-exclude CONDITION
Exclude conditions for rounded corners.
--mark-wmwin-focused
Try to detect WM windows (a non-override-redirect window with no
child that has WM_STATE) and mark them as active.
--mark-ovredir-focused
Mark override-redirect windows that doesn’t have a child window
with WM_STATE focused.
--no-fading-openclose
Do not fade on window open/close.
--no-fading-destroyed-argb
Do not fade destroyed ARGB windows with WM frame. Workaround of
bugs in Openbox, Fluxbox, etc.
--shadow-ignore-shaped
Do not paint shadows on shaped windows. Note shaped windows here
means windows setting its shape through X Shape extension. Those
using ARGB background is beyond our control. Deprecated, use
--shadow-exclude 'bounding_shaped' or --shadow-exclude
'bounding_shaped && !rounded_corners' instead.
--detect-rounded-corners
Try to detect windows with rounded corners and don’t consider them
shaped windows. The accuracy is not very high, unfortunately.
--detect-client-opacity
Detect _NET_WM_WINDOW_OPACITY on client windows, useful for window
managers not passing _NET_WM_WINDOW_OPACITY of client windows to
frame windows.
--vsync, --no-vsync
Enable/disable VSync.
--use-ewmh-active-win
Use EWMH _NET_ACTIVE_WINDOW to determine currently focused window,
rather than listening to FocusIn/FocusOut event. Might have more
accuracy, provided that the WM supports it.
--unredir-if-possible
Unredirect all windows if a full-screen opaque window is detected,
to maximize performance for full-screen windows. Known to cause
flickering when redirecting/unredirecting windows.
--unredir-if-possible-delay MILLISECONDS
Delay before unredirecting the window, in milliseconds. Defaults to
0.
--unredir-if-possible-exclude CONDITION
Conditions of windows that shouldn’t be considered full-screen for
unredirecting screen.
--shadow-exclude CONDITION
Specify a list of conditions of windows that should have no shadow.
--clip-shadow-above CONDITION
Specify a list of conditions of windows that should have no shadow
painted over, such as a dock window.
--fade-exclude CONDITION
Specify a list of conditions of windows that should not be faded.
--focus-exclude CONDITION
Specify a list of conditions of windows that should always be
considered focused.
--inactive-dim-fixed
Use fixed inactive dim value, instead of adjusting according to
window opacity.
--detect-transient
Use WM_TRANSIENT_FOR to group windows, and consider windows in the
same group focused at the same time.
--detect-client-leader
Use WM_CLIENT_LEADER to group windows, and consider windows in the
same group focused at the same time. This usually means windows
from the same application will be considered focused or unfocused
at the same time.WM_TRANSIENT_FOR has higher priority if
--detect-transient is enabled, too.
--blur-method, --blur-size, --blur-deviation, --blur-strength
Parameters for background blurring, see the BLUR section for more
information.
--blur-background
Blur background of semi-transparent / ARGB windows. Bad in
performance, with driver-dependent behavior. The name of the switch
may change without prior notifications.
--blur-background-frame
Blur background of windows when the window frame is not opaque.
Implies --blur-background. Bad in performance, with
driver-dependent behavior. The name may change.
--blur-background-fixed
Use fixed blur strength rather than adjusting according to window
opacity.
--blur-kern MATRIX
Specify the blur convolution kernel, with the following format:
WIDTH,HEIGHT,ELE1,ELE2,ELE3,ELE4,ELE5...
In other words, the matrix is formatted as a list of comma
separated numbers. The first two numbers must be integers, which
specify the width and height of the matrix. They must be odd
numbers. Then, the following width * height - 1 numbers specifies
the numbers in the matrix, row by row, excluding the center
element.
The elements are finite floating point numbers. The decimal pointer
has to be . (a period), scientific notation is not supported.
The element in the center will either be 1.0 or varying based on
opacity, depending on whether you have --blur-background-fixed. Yet
the automatic adjustment of blur factor may not work well with a
custom blur kernel.
A 7x7 Gaussian blur kernel (sigma = 0.84089642) looks like:
--blur-kern '7,7,0.000003,0.000102,0.000849,0.001723,0.000849,0.000102,0.000003,0.000102,0.003494,0.029143,0.059106,0.029143,0.003494,0.000102,0.000849,0.029143,0.243117,0.493069,0.243117,0.029143,0.000849,0.001723,0.059106,0.493069,0.493069,0.059106,0.001723,0.000849,0.029143,0.243117,0.493069,0.243117,0.029143,0.000849,0.000102,0.003494,0.029143,0.059106,0.029143,0.003494,0.000102,0.000003,0.000102,0.000849,0.001723,0.000849,0.000102,0.000003'
May also be one of the predefined kernels: 3x3box (default),
5x5box, 7x7box, 3x3gaussian, 5x5gaussian, 7x7gaussian, 9x9gaussian,
11x11gaussian. All Gaussian kernels are generated with sigma =
0.84089642 . If you find yourself needing to generate custom blur
kernels, you might want to try the new blur configuration supported
by the experimental backends (See BLUR and
--experimental-backends).
--blur-background-exclude CONDITION
Exclude conditions for background blur.
--resize-damage INTEGER
Resize damaged region by a specific number of pixels. A positive
value enlarges it while a negative one shrinks it. If the value is
positive, those additional pixels will not be actually painted to
screen, only used in blur calculation, and such. (Due to technical
limitations, with --use-damage, those pixels will still be
incorrectly painted to screen.) Primarily used to fix the line
corruption issues of blur, in which case you should use the blur
radius value here (e.g. with a 3x3 kernel, you should use
--resize-damage 1, with a 5x5 one you use --resize-damage 2, and so
on). May or may not work with --glx-no-stencil. Shrinking doesn’t
function correctly.
--invert-color-include CONDITION
Specify a list of conditions of windows that should be painted with
inverted color. Resource-hogging, and is not well tested.
--opacity-rule OPACITY:'CONDITION'
Specify a list of opacity rules, in the format PERCENT:PATTERN,
like 50:name *= "Firefox". picom-trans is recommended over this.
Note we don’t make any guarantee about possible conflicts with
other programs that set _NET_WM_WINDOW_OPACITY on frame or client
windows.
--shadow-exclude-reg GEOMETRY
Specify a X geometry that describes the region in which shadow
should not be painted in, such as a dock window region. Use
--shadow-exclude-reg x10+0-0, for example, if the 10 pixels on the
bottom of the screen should not have shadows painted on.
--xinerama-shadow-crop
Crop shadow of a window fully on a particular Xinerama screen to
the screen.
--backend BACKEND
Specify the backend to use: xrender, glx, or xr_glx_hybrid.
xrender is the default one.
• xrender backend performs all rendering operations with X Render
extension. It is what xcompmgr uses, and is generally a safe
fallback when you encounter rendering artifacts or instability.
• glx (OpenGL) backend performs all rendering operations with
OpenGL. It is more friendly to some VSync methods, and has
significantly superior performance on color inversion
(--invert-color-include) or blur (--blur-background). It
requires proper OpenGL 2.0 support from your driver and
hardware. You may wish to look at the GLX performance
optimization options below. --xrender-sync-fence might be
needed on some systems to avoid delay in changes of screen
contents.
• xr_glx_hybrid backend renders the updated screen contents with
X Render and presents it on the screen with GLX. It attempts to
address the rendering issues some users encountered with GLX
backend and enables the better VSync of GLX backends.
--vsync-use-glfinish might fix some rendering issues with this
backend.
--glx-no-stencil
GLX backend: Avoid using stencil buffer, useful if you don’t have a
stencil buffer. Might cause incorrect opacity when rendering
transparent content (but never practically happened) and may not
work with --blur-background. My tests show a 15% performance boost.
Recommended.
--glx-no-rebind-pixmap
GLX backend: Avoid rebinding pixmap on window damage. Probably
could improve performance on rapid window content changes, but is
known to break things on some drivers (LLVMpipe, xf86-video-intel,
etc.). Recommended if it works.
--no-use-damage
Disable the use of damage information. This cause the whole screen
to be redrawn every time, instead of the part of the screen has
actually changed. Potentially degrades the performance, but might
fix some artifacts.
--xrender-sync-fence
Use X Sync fence to sync clients' draw calls, to make sure all draw
calls are finished before picom starts drawing. Needed on
nvidia-drivers with GLX backend for some users.
--glx-fshader-win SHADER
GLX backend: Use specified GLSL fragment shader for rendering
window contents. See compton-default-fshader-win.glsl and
compton-fake-transparency-fshader-win.glsl in the source tree for
examples.
--force-win-blend
Force all windows to be painted with blending. Useful if you have a
--glx-fshader-win that could turn opaque pixels transparent.
--dbus
Enable remote control via D-Bus. See the D-BUS API section below
for more details.
--benchmark CYCLES
Benchmark mode. Repeatedly paint until reaching the specified
cycles.
--benchmark-wid WINDOW_ID
Specify window ID to repaint in benchmark mode. If omitted or is 0,
the whole screen is repainted.
--no-ewmh-fullscreen
Do not use EWMH to detect fullscreen windows. Reverts to checking
if a window is fullscreen based only on its size and coordinates.
--max-brightness
Dimming bright windows so their brightness doesn’t exceed this set
value. Brightness of a window is estimated by averaging all pixels
in the window, so this could comes with a performance hit. Setting
this to 1.0 disables this behaviour. Requires --use-damage to be
disabled. (default: 1.0)
--transparent-clipping
Make transparent windows clip other windows like non-transparent
windows do, instead of blending on top of them.
FORMAT OF CONDITIONS
Some options accept a condition string to match certain windows. A
condition string is formed by one or more conditions, joined by logical
operators.
A condition with "exists" operator looks like this:
<NEGATION> <TARGET> <CLIENT/FRAME> [<INDEX>] : <FORMAT> <TYPE>
With equals operator it looks like:
<NEGATION> <TARGET> <CLIENT/FRAME> [<INDEX>] : <FORMAT> <TYPE> <NEGATION> <OP QUALIFIER> <MATCH TYPE> = <PATTERN>
With greater-than/less-than operators it looks like:
<NEGATION> <TARGET> <CLIENT/FRAME> [<INDEX>] : <FORMAT> <TYPE> <NEGATION> <OPERATOR> <PATTERN>
NEGATION (optional) is one or more exclamation marks;
TARGET is either a predefined target name, or the name of a window
property to match. Supported predefined targets are id, x, y, x2 (x +
widthb), y2 (like x2), width, height, widthb (width + 2 *
border_width), heightb (like widthb), border_width, fullscreen,
override_redirect, argb (whether the window has an ARGB visual),
focused, wmwin (whether the window looks like a WM window, i.e. has no
child window with WM_STATE and is not override-redirected),
bounding_shaped, rounded_corners (requires --detect-rounded-corners),
client (ID of client window), window_type (window type in string),
leader (ID of window leader), name, class_g (= WM_CLASS[1]), class_i (=
WM_CLASS[0]), and role.
CLIENT/FRAME is a single @ if the window attribute should be be looked
up on client window, nothing if on frame window;
INDEX (optional) is the index number of the property to look up. For
example, [2] means look at the third value in the property. If not
specified, the first value (index [0]) is used implicitly. Use the
special value [*] to perform matching against all available property
values using logical OR. Do not specify it for predefined targets.
FORMAT (optional) specifies the format of the property, 8, 16, or 32.
On absence we use format X reports. Do not specify it for predefined or
string targets.
TYPE is a single character representing the type of the property to
match for: c for CARDINAL, a for ATOM, w for WINDOW, d for DRAWABLE, s
for STRING (and any other string types, such as UTF8_STRING). Do not
specify it for predefined targets.
OP QUALIFIER (optional), applicable only for equals operator, could be
? (ignore-case).
MATCH TYPE (optional), applicable only for equals operator, could be
nothing (exact match), * (match anywhere), ^ (match from start), %
(wildcard), or ~ (PCRE regular expression).
OPERATOR is one of = (equals), <, >, <=, =>, or nothing (exists).
Exists operator checks whether a property exists on a window (but for
predefined targets, exists means != 0 then).
PATTERN is either an integer or a string enclosed by single or double
quotes. Python-3-style escape sequences and raw string are supported in
the string format.
Supported logical operators are && (and) and || (or). && has higher
precedence than ||, left-to-right associativity. Use parentheses to
change precedence.
Examples:
# If the window is focused
focused
focused = 1
# If the window is not override-redirected
!override_redirect
override_redirect = false
override_redirect != true
override_redirect != 1
# If the window is a menu
window_type *= "menu"
_NET_WM_WINDOW_TYPE@:a *= "MENU"
# If the window is marked hidden: _NET_WM_STATE contains _NET_WM_STATE_HIDDEN
_NET_WM_STATE@[*]:a = "_NET_WM_STATE_HIDDEN"
# If the window is marked sticky: _NET_WM_STATE contains an atom that contains
# "sticky", ignore case
_NET_WM_STATE@[*]:a *?= "sticky"
# If the window name contains "Firefox", ignore case
name *?= "Firefox"
_NET_WM_NAME@:s *?= "Firefox"
# If the window name ends with "Firefox"
name %= "*Firefox"
name ~= "Firefox$"
# If the window has a property _COMPTON_SHADOW with value 0, type CARDINAL,
# format 32, value 0, on its frame window
_COMPTON_SHADOW:32c = 0
# If the third value of _NET_FRAME_EXTENTS is less than 20, or there's no
# _NET_FRAME_EXTENTS property on client window
_NET_FRAME_EXTENTS@[2]:32c < 20 || !_NET_FRAME_EXTENTS@:32c
# The pattern here will be parsed as "dd4"
name = "\x64\x64\o64"
# The pattern here will be parsed as "\x64\x64\x64"
name = r"\x64\x64\o64"
LEGACY FORMAT OF CONDITIONS
This is the old condition format we once used. Support of this format
might be removed in the future.
condition = TARGET:TYPE[FLAGS]:PATTERN
TARGET is one of "n" (window name), "i" (window class instance), "g"
(window general class), and "r" (window role).
TYPE is one of "e" (exact match), "a" (match anywhere), "s" (match from
start), "w" (wildcard), and "p" (PCRE regular expressions, if compiled
with the support).
FLAGS could be a series of flags. Currently the only defined flag is
"i" (ignore case).
PATTERN is the actual pattern string.
CONFIGURATION FILES
picom could read from a configuration file if libconfig support is
compiled in. If --config is not used, picom will seek for a
configuration file in $XDG_CONFIG_HOME/picom.conf
(~/.config/picom.conf, usually), then
$XDG_CONFIG_HOME/picom/picom.conf, then $XDG_CONFIG_DIRS/picom.conf
(often /etc/xdg/picom.conf), then $XDG_CONFIG_DIRS/picom/picom.conf.
picom uses general libconfig configuration file format. A sample
configuration file is available as picom.sample.conf in the source
tree. Most of commandline switches can be used as options in
configuration file as well. For example, --vsync option documented
above can be set in the configuration file using `vsync = `. Command
line options will always overwrite the settings in the configuration
file.
Window-type-specific settings are exposed only in configuration file
and has the following format:
wintypes:
{
WINDOW_TYPE = { fade = BOOL; shadow = BOOL; opacity = FLOAT; focus = BOOL; blur-background = BOOL; full-shadow = BOOL; clip-shadow-above = BOOL; redir-ignore = BOOL; };
};
WINDOW_TYPE is one of the 15 window types defined in EWMH standard:
"unknown", "desktop", "dock", "toolbar", "menu", "utility", "splash",
"dialog", "normal", "dropdown_menu", "popup_menu", "tooltip",
"notification", "combo", and "dnd".
Following per window-type options are available:
fade, shadow
Controls window-type-specific shadow and fade settings.
opacity
Controls default opacity of the window type.
focus
Controls whether the window of this type is to be always
considered focused. (By default, all window types except
"normal" and "dialog" has this on.)
blur-background
Controls wether the window of this type will have its
transparent background blurred.
full-shadow
Controls whether shadow is drawn under the parts of the window
that you normally won’t be able to see. Useful when the window
has parts of it transparent, and you want shadows in those
areas.
clip-shadow-above
Controls wether shadows that would have been drawn above the
window should be clipped. Useful for dock windows that should
have no shadow painted on top.
redir-ignore
Controls whether this type of windows should cause screen to
become redirected again after been unredirected. If you have
--unredir-if-possible set, and doesn’t want certain window to
cause unnecessary screen redirection, you can set this to true.
BLUR
You can configure how the window background is blurred using a blur
section in your configuration file. Here is an example:
blur:
{
method = "gaussian";
size = 10;
deviation = 5.0;
};
Available options of the blur section are:
method
A string. Controls the blur method. Corresponds to the
--blur-method command line option. Available choices are: none
to disable blurring; gaussian for gaussian blur; box for box
blur; kernel for convolution blur with a custom kernel;
dual_kawase for dual-filter kawase blur. Note: gaussian, box
and dual_kawase blur methods are only supported by the
experimental backends. (default: none)
size
An integer. The size of the blur kernel, required by gaussian
and box blur methods. For the kernel method, the size is
included in the kernel. Corresponds to the --blur-size command
line option (default: 3).
deviation
A floating point number. The standard deviation for the
gaussian blur method. Corresponds to the --blur-deviation
command line option (default: 0.84089642).
strength
An integer in the range 0-20. The strength of the dual_kawase
blur method. Corresponds to the --blur-strength command line
option. If set to zero, the value requested by --blur-size is
approximated (default: 5).
kernel
A string. The kernel to use for the kernel blur method,
specified in the same format as the --blur-kerns option.
Corresponds to the --blur-kerns command line option.
SIGNALS
• picom reinitializes itself upon receiving SIGUSR1.
D-BUS API
It’s possible to control picom via D-Bus messages, by running picom
with --dbus and send messages to com.github.chjj.compton.<DISPLAY>.
<DISPLAY> is the display used by picom, with all non-alphanumeric
characters transformed to underscores. For DISPLAY=:0.0 you should use
com.github.chjj.compton._0_0, for example.
The D-Bus methods and signals are not yet stable, thus undocumented
right now.
EXAMPLES
• Disable configuration file parsing:
$ picom --config /dev/null
• Run picom with client-side shadow and fading:
$ picom -cf
• Same thing as above, plus making inactive windows 80% transparent,
making frame 80% transparent, don’t fade on window open/close, and
fork to background:
$ picom -bcf -i 0.8 -e 0.8 --no-fading-openclose
• Draw white shadows:
$ picom -c --shadow-red 1 --shadow-green 1 --shadow-blue 1
• Avoid drawing shadows on wbar window:
$ picom -c --shadow-exclude 'class_g = "wbar"'
• Enable VSync with GLX backend:
$ picom --backend glx --vsync
BUGS
Please submit bug reports to https://github.com/yshui/picom.
Out dated information in this man page is considered a bug.
RESOURCES
Homepage: https://github.com/yshui/picom
SEE ALSO
xcompmgr(1), picom-trans(1)
picom v9 02/06/2022 PICOM(1)
Generated by dwww version 1.14 on Fri Mar 28 12:21:56 CET 2025.