COMPTON(1)
COMPTON(1) π β¨
LOCAL USER COMMANDS
okay bestie, sit DOWN, because we're about to talk about compton β a compositor for X11, and she is genuinely iconic. this is the manual page, but make it make sense. no cap, every single flag is still here, i'm just giving them the energy they deserve. π«Ά
NAME π
compton β a compositor for X11
SYNOPSIS πΈ
compton [OPTIONS]
that's it. that's the whole vibe. you give her options, she composites. π
WARNING β οΈπ
bestie. listen. this man page may be less up-to-date than the usage text in compton (compton -h). so if something here looks crusty and outdated, runcompton -hand trust that instead. the man page is the friend who texts back three days late. π
DESCRIPTION π¦
so compton is a compositor based on Dana Jansens' version of xcompmgr (which itself was written by Keith Packard). she's got some glow-ups over the original xcompmgr, like window frame opacity and inactive window transparency. it's giving vintage but make it cunty. π
β¨ OPTIONS β¨
every flag, every default, nothing skipped, periodt. π
-h,--helpβ get the usage text embedded in program code, which may be more up-to-date than this man page. (yes, again. it's really that girl. π)-d DISPLAYβ the display to be managed.-r,--shadow-radius=RADIUSβ the blur radius for shadows, in pixels. (defaults to12)-o,--shadow-opacity=OPACITYβ the opacity of shadows. (0.0-1.0, defaults to0.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β the opacity change between steps while fading in. (0.01-1.0, defaults to0.028)-O,--fade-out-step=OPACITY_STEPβ the opacity change between steps while fading out. (0.01-1.0, defaults to0.03)-D,--fade-delta=MILLISECONDSβ the time between steps in fade step, in milliseconds. (> 0, defaults to10)-m,--menu-opacity=OPACITYβ the default opacity for dropdown menus and popup menus. (0.0-1.0, defaults to1.0)-c,--shadowβ enables client-side shadows on windows. lowkey important: desktop windows (windows with_NET_WM_WINDOW_TYPE_DESKTOP) never get shadow. she's on a strict no-shadow diet. π-C,--no-dock-shadowβ avoid drawing shadows on dock/panel windows. your taskbar stays unbothered. β¨-z,--clear-shadowβ zero the part of the shadow's mask behind the window. heads up though: this may not work properly on ARGB windows with fully transparent areas. π«-f,--fadingβ fade windows in/out when opening/closing and when opacity changes, unless--no-fading-opencloseis used.-Fβ equals to-f. Deprecated. (she's retired but still showing up to the party π)-i,--inactive-opacity=OPACITYβ the opacity of inactive windows. (0.1-1.0, defaults to1.0)-e,--frame-opacity=OPACITYβ the opacity of window titlebars and borders. (0.1-1.0, disabled by default)-G,--no-dnd-shadowβ don't draw shadows on drag-and-drop windows. (don't drag them, don't shadow them π«)-b,--daemonβ daemonize process. forks to background after initialization. causes issues with certain (badly-written) drivers. you've been warned, bestie.-Sβ enable synchronous X operation (for debugging). π--show-all-xerrorsβ show all X errors (for debugging).--config PATHβ look for configuration file at the path. see the CONFIGURATION FILES section below for wherecomptonlooks for a configuration file by default. use/dev/nullto avoid loading configuration file. (bye config, blocked. β)--write-pid-path PATHβ write process ID to a file.--shadow-red VALUEβ red color value of shadow. (0.0-1.0, defaults to0)--shadow-green VALUEβ green color value of shadow. (0.0-1.0, defaults to0)--shadow-blue VALUEβ blue color value of shadow. (0.0-1.0, defaults to0)--inactive-opacity-overrideβ let inactive opacity set by-ioverride the windows'_NET_WM_OPACITYvalues.--active-opacity OPACITYβ default opacity for active windows. (0.0-1.0, defaults to1.0)--inactive-dim VALUEβ dim inactive windows. (0.0-1.0, defaults to0.0)--mark-wmwin-focusedβ try to detect WM windows (a non-override-redirect window with no child that hasWM_STATE) and mark them as active.--mark-ovredir-focusedβ mark override-redirect windows that doesn't have a child window withWM_STATEfocused.--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. (not her fault, she's just fixing their mess π«Ά)--shadow-ignore-shapedβ do not paint shadows on shaped windows. quick note: shaped windows here means windows setting its shape through the 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. (she's trying her best π)--detect-client-opacityβ detect_NET_WM_OPACITYon client windows, useful for window managers not passing_NET_WM_OPACITYof client windows to frame windows.--refresh-rate REFRESH_RATEβ specify refresh rate of the screen. if not specified or0,comptonwill try detecting this with the X RandR extension.--vsync VSYNC_METHODβ set VSync method. VSync methods currently available:none: No VSyncdrm: VSync withDRM_IOCTL_WAIT_VBLANK. may only work on some (DRI-based) drivers.opengl: try to VSync withSGI_video_syncOpenGL extension. only work on some drivers.opengl-oml: try to VSync withOML_sync_controlOpenGL extension. only work on some drivers.opengl-swc: try to VSync withSGI_swap_controlOpenGL extension. only work on some drivers. works only with GLX backend. known to be most effective on many drivers. does not guarantee to control paint timing.opengl-mswc: try to VSync withMESA_swap_controlOpenGL extension. basically the same asopengl-swcabove, except the extension we use.
(Note some VSync methods may not be enabled at compile time. π« )
--vsync-aggressiveβ attempt to send painting request before VBlank and doXFlush()during VBlank. reported to work pretty terribly. this switch may be lifted out at any moment. (she's on borrowed time, bestie β³)--alpha-step VALUEβ X Render backend: step for pregenerating alpha pictures. (0.01-1.0, defaults to0.03)--dbeβ enable DBE painting mode, intended to use with VSync to (hopefully) eliminate tearing. reported to have no effect, though. π--paint-on-overlayβ painting on X Composite overlay window instead of on root window.--sw-optiβ limitcomptonto repaint at most once every1 / refresh_ratesecond to boost performance. this should not be used with--vsync drm/opengl/opengl-omlas they essentially does--sw-opti's job already, unless you wish to specify a lower refresh rate than the actual value.--use-ewmh-active-winβ use EWMH_NET_ACTIVE_WINDOWto determine currently focused window, rather than listening to FocusIn/FocusOut event. might have more accuracy, provided that the WM supports it.--respect-prop-shadowβ respect_COMPTON_SHADOW. this a prototype-level feature, which you must not rely on. π§ (do not build your life on this, i'm so serious)--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.--paint-on-overlaymay make the flickering less obvious. π’--unredir-if-possible-delay MILLISECONDSβ delay before unredirecting the window, in milliseconds. defaults to0.--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.--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β useWM_TRANSIENT_FORto group windows, and consider windows in the same group focused at the same time.--detect-client-leaderβ useWM_CLIENT_LEADERto group windows, and consider windows in the same group focused at the same time.WM_TRANSIENT_FORhas higher priority if--detect-transientis enabled, too.--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. (again π)--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...
the element in the center must not be included, it will be forever 1.0 or changing 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 . you may use the accompanied compton-convgen.py to generate blur kernels. π§
--blur-background-exclude CONDITIONβ exclude conditions for background blur.--resize-damage INTEGERβ bestie, this one resizes the damaged region by a specific number of pixels β¨. Positive value = it grows, negative = it shrinks. And if the value is positive, those extra pixels are genuinely never painted to screen, they're only used for blur calculation and stuff like that. (But lowkey, because of technical limitations, if you're running--dbeor--glx-swap-method, those pixels WILL still get incorrectly painted to screen anyway, oops π.) Mainly this exists to fix the line corruption issues from blur β and in that case you should just use the blur radius value right here. So like, with a 3x3 kernel you'd use--resize-damage 1, with a 5x5 one you use--resize-damage 2, and so on and so forth π . May or may not work with--glx-no-stencil, no cap. Oh and also: shrinking doesn't function correctly π« .--invert-color-include CONDITIONβ give it a list of conditions for windows that should be painted with inverted color π. Heads up though: this is resource-hogging and not well tested. It's giving experimental, fr fr.--opacity-rule OPACITY:'CONDITION'β gives you a list of opacity rules, in the formatPERCENT:PATTERN, like50:name *= "Firefox". Honestlycompton-transis the recommended move over using this directly π. Also note: there's zero guarantee about possible conflicts with other programs that set_NET_WM_WINDOW_OPACITYon frame or client windows. Just so you know π.--shadow-exclude-reg GEOMETRYβ specify an X geometry describing the region where shadow should NOT be painted, like a dock window region πΈ. So for example use--shadow-exclude-reg x10+0-0if the 10 pixels on the bottom of the screen shouldn't have shadows painted on them. Iconic.--xinerama-shadow-cropβ crops the shadow of a window that's fully on a particular Xinerama screen to that screen βοΈ.--backend BACKENDβ pick your backend babe:xrender,glx, orxr_glx_hybrid. Default isxrenderπ«.xrenderbackend does ALL the rendering operations with the X Render extension. It's literally what xcompmgr uses, and it's generally the safe fallback when you run into rendering artifacts or instability π«Ά.glx(OpenGL) backend does all rendering operations with OpenGL. It's more friendly to some VSync methods, and it 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, no exceptions. You may want to look at the GLX performance optimization options below π. Also--xrender-syncand--xrender-sync-fencemight be needed on some systems to avoid delay in changes of screen contents.xr_glx_hybridbackend renders the updated screen contents with X Render and presents it on screen with GLX. It's trying to address the rendering issues some users hit with the GLX backend while still enabling the better VSync of GLX backends π .--vsync-use-glfinishmight fix some rendering issues with this backend.
--glx-no-stencilβ GLX backend: avoid using the stencil buffer, useful if you literally don't have a stencil buffer π. Might cause incorrect opacity when rendering transparent content (but, like, never practically happened) and may not work with--blur-background. My tests show a 15% performance boost. Recommended bestie, take the 15% β¨.--glx-copy-from-frontβ GLX backend: copy unmodified regions from the front buffer instead of redrawing them all π. My tests with nvidia-drivers show a 10% decrease in performance when the whole screen is modified, but a 20% increase when only 1/4 is. My tests on nouveau show terrible slowdown π. Useful with--glx-swap-methodas well.--glx-use-copysubbuffermesaβ GLX backend: useMESA_copy_sub_bufferto do partial screen update. My tests on nouveau show a 200% performance boost when only 1/4 of the screen is updated π₯. But may break VSync and it's not available on some drivers. It also overrides--glx-copy-from-front. Trade-offs, babe.--glx-no-rebind-pixmapβ GLX backend: avoid rebinding pixmap on window damage. It probably could improve performance on rapid window content changes, but it's known to break things on some drivers (LLVMpipe, xf86-video-intel, etc.) π. Recommended if it works for you π«Ά.--glx-swap-method undefined/exchange/copy/3/4/5/6/buffer-ageβ GLX backend: the GLX buffer swap method we assume. Could beundefined(0),copy(1),exchange(2), 3-6, orbuffer-age(-1) π«.undefinedis the slowest and the safest, and it's the default value.copyis fastest, but may fail on some drivers, and 2-6 are gradually slower but safer (6 is still faster than 0). Usually double buffer means 2, triple buffer means 3.buffer-agemeans auto-detect usingGLX_EXT_buffer_age, supported by some drivers. Useless with--glx-use-copysubbuffermesa. Partially breaks--resize-damage. Defaults toundefined. Periodt.--glx-use-gpushader4β GLX backend: useGL_EXT_gpu_shader4for some optimization on blur GLSL code β¨. My tests on GTX 670 show no noticeable effect. It's giving "sure, whatever" ngl.--xrender-syncβ attempts to synchronize client applications' draw calls withXSync(), used on GLX backend to ensure up-to-date window content is painted π.--xrender-sync-fenceβ additionally uses X Sync fence to sync clients' draw calls π. Needed on nvidia-drivers with GLX backend for some users. May be disabled at compile time withNO_XSYNC=1.--glx-fshader-win SHADERβ GLX backend: use the specified GLSL fragment shader for rendering window contents π. Go peepcompton-default-fshader-win.glslandcompton-fake-transparency-fshader-win.glslin the source tree for examples π.--force-win-blendβ force ALL windows to be painted with blending π . Useful if you have a--glx-fshader-winthat could turn opaque pixels transparent.--dbusβ enables remote control via D-Bus β¨. See the D-BUS API section below for more details.--benchmark CYCLESβ benchmark mode, bestie π. Repeatedly paints until reaching the specified cycles.--benchmark-wid WINDOW_IDβ specify the window ID to repaint in benchmark mode. If it's omitted or is 0, the whole screen gets repainted π₯οΈ.
π¦ FORMAT OF CONDITIONS π¦
Okay so 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 the exists operator looks like this:
<NEGATION> <TARGET> <CLIENT/FRAME> [<INDEX>] : <FORMAT> <TYPE>
With the 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>
Let's break it down, because it's giving anatomy class π§:
NEGATION(optional) is one or more exclamation marks β.TARGETis either a predefined target name, or the name of a window property to match. The supported predefined targets are:id,x,y,x2(x + widthb),y2,width,height,widthb(width + 2 * border_width),heightb,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 withWM_STATEand 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]), androleβ¨.CLIENT/FRAMEis a single@if the window attribute should be looked up on the client window, and nothing if it should be looked up on the frame window π.INDEX(optional) is the index number of the property to look up. So for example[2]means look at the third value in the property π«. Do NOT specify it for predefined targets, babe.FORMAT(optional) specifies the format of the property:8,16, or32. If it's absent we use the format X reports π. Do not specify it for predefined or string targets.TYPEis a single character representing the type of property to match for:cfor CARDINAL,afor ATOM,wfor WINDOW,dfor DRAWABLE,sfor STRING (and any other string types, such asUTF8_STRING) π. Do not specify it for predefined targets.OP QUALIFIER(optional), only applicable for the equals operator, could be?(ignore-case) π€.MATCH TYPE(optional), only applicable for the equals operator, could be nothing (exact match),*(match anywhere),^(match from start),%(wildcard), or~(PCRE regular expression) πΈ.OPERATORis one of=(equals),<,>,<=,=>, or nothing (exists). The exists operator checks whether a property exists on a window (but for predefined targets, exists means!= 0then) π.PATTERNis 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 β yes bestie, full math-class energy, we love to see it.
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 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 π°οΈ
Okay so this is the OLD condition format we once used π΅. Heads up: support of this format might be removed in the future π. Fair warning, bestie.
condition = TARGET:TYPE[FLAGS]:PATTERN
TARGETis one of"n"(window name),"i"(window class instance),"g"(window general class), and"r"(window role) π·οΈ.TYPEis one of"e"(exact match),"a"(match anywhere),"s"(match from start),"w"(wildcard), and"p"(PCRE regular expressions, if compiled with the support) π.FLAGScould be a series of flags. Currently the only defined flag is"i"(ignore case) π .PATTERNis the actual pattern string β¨.
π CONFIGURATION FILES π
ok so here's the tea, bestie: compton can read from a configuration file if libconfig support is compiled in π. And if you don't pass --config, it's gonna go hunting for one, in this exact order:
$XDG_CONFIG_HOME/compton.conf(which is~/.config/compton.conf, usually) π~/.compton.confcompton.confunder$XDG_CONFIG_DIRS(often/etc/xdg/compton.conf)
compton uses the general libconfig configuration file format, fr fr. There's a sample config hanging out as compton.sample.conf in the source tree if you wanna peek π.
Most commandline switches each could be replaced with an option in the configuration file β so like, everything documented above, basically, you can put it in the file instead. slay. β¨
Window-type-specific settings though? Those are exposed only in the configuration file, and they look like this:
wintypes:
{
WINDOW_TYPE = { fade = BOOL; shadow = BOOL; opacity = FLOAT; focus = BOOL; };
};
WINDOW_TYPE is one of the 15 window types defined in the EWMH standard, and I'm listing every single one because we don't skip: "unknown", "desktop", "dock", "toolbar", "menu", "utility", "splash", "dialog", "normal", "dropdown_menu", "popup_menu", "tooltip", "notify", "combo", and "dnd". π
A lil breakdown of what each field does:
fadeandshadowβ control the window-type-specific shadow and fade settings πopacityβ controls the default opacity of the window typefocusβ controls whether the window of this type is to be always considered focused. (And by default, all window types except"normal"and"dialog"have this one turned on, just so you know π«Ά)
π SIGNALS π
comptonreinitializes itself upon receivingSIGUSR1. that's it, that's the signal π
πΈ D-B-BUS API πΈ
wait no, it's D-Bus β typo, ignore me π. Anyway! It's possible to control compton via D-Bus messages, by running compton with --dbus and sending messages to com.github.chjj.compton.<DISPLAY>.
<DISPLAY> is the display used by compton, with all non-alphanumeric characters transformed to underscores. So like, for DISPLAY=:0.0 you should use com.github.chjj.compton._0_0, for example. iconic. π
β οΈ The D-Bus methods and signals are not yet stable, thus undocumented right now. no cap, they're just vibes at this stage π§
π₯ EXAMPLES π₯
- Disable configuration file parsing:
$ compton --config /dev/null
- Run
comptonwith client-side shadow and fading, disable shadow on dock windows and drag-and-drop windows:
$ compton -cCGf
- Same thing as above, plus making inactive windows 80% transparent, making frame 80% transparent, don't fade on window open/close, enable software optimization, and fork to background:
$ compton -bcCGf -i 0.8 -e 0.8 --no-fading-openclose --sw-opti
- Draw white shadows:
$ compton -c --shadow-red 1 --shadow-green 1 --shadow-blue 1
- Avoid drawing shadows on
wbarwindow:
$ compton -c --shadow-exclude 'class_g = "wbar"'
- Enable OpenGL
SGI_swap_controlVSync with GLX backend:
$ compton --backend glx --vsync opengl-swc
π BUGS π
Please report any you find to https://github.com/chjj/compton . like, genuinely, they wanna know π
π AUTHORS π
xcompmgr, originally written by Keith Packard, with contributions from Matthew Allum, Eric Anholt, Dan Doel, Thomas Luebking, Matthew Hawn, Ely Levy, Phil Blundell, and Carl Worth. Compton by Christopher Jeffrey, based on Dana Jansens' original work, with contributions from Richard Grenville. absolute legends, all of them π«Ά
π RESOURCES π
Homepage: https://github.com/chjj/compton
π SEE ALSO π
and that's the whole page bestie!! this masterpiece is compton nightly-20141124, dated 01/14/2026, and it's giving COMPTON(1) main character energy β go forth and composite, you got this π¦πβ¨
π¦ where this page comes from
- ubuntu resolute: compton 1-3build2 Β· MIT
- ubuntu stonking: compton 1-3build2 Β· MIT
- π girlified by deepseek-ai/DeepSeek-V4.1-Flash on : a language model's rewrite of the original, under its terms