Picom Compositor Setup

Picom is a lightweight compositor for X11 that provides window transparency, shadows, fading, and blur effects.

Overview

Configuration file: ~/.config/picom/picom.conf Picom enhances the visual experience of i3 window manager with modern visual effects while maintaining performance.

Basic Configuration

Backend Settings

backend = "glx";
glx-no-stencil = true;
glx-copy-from-front = false;
vsync = true

The GLX backend provides the best performance and compatibility with modern graphics drivers.

Backend Options Explained

glx - OpenGL backend (recommended)
xrender - X Render backend (fallback for older systems)
xr_glx_hybrid - Hybrid mode

GLX Options:

glx-no-stencil - Disables stencil buffer for better performance
glx-copy-from-front - Disabled for better performance
vsync - Synchronizes rendering with monitor refresh rate

Shadow Configuration

Enable and Configure Shadows

shadow = true;
shadow-radius = 7;
shadow-opacity = 0.4
shadow-offset-x = -7;
shadow-offset-y = -4;

Shadow Parameters

Parameter	Value	Description
`shadow`	`true`	Enable client-side shadows
`shadow-radius`	`7`	Blur radius in pixels
`shadow-opacity`	`0.4`	Shadow opacity (0.0-1.0)
`shadow-offset-x`	`-7`	Horizontal offset
`shadow-offset-y`	`-4`	Vertical offset

Shadow Exclusions

shadow-exclude = [
  "name = 'Notification'",
  "class_g = 'Conky'",
  "class_g ?= 'Notify-osd'",
  "class_g = 'Cairo-clock'",
  "_GTK_FRAME_EXTENTS@:c"
];

Excluding notifications and specific applications prevents unwanted shadow artifacts.

Fading Effects

Fade Configuration

fading = true
fade-in-step = 0.03;
fade-out-step = 0.03;
fade-delta = 7
no-fading-openclose = false

Fading Parameters

Fade Settings Explained

fading: Enable fade effects
fade-in-step: Opacity increase per step (0.01-1.0)
fade-out-step: Opacity decrease per step (0.01-1.0)
fade-delta: Time between steps in milliseconds
no-fading-openclose: Whether to disable fade on window open/close

Example calculations:

fade-in-step = 0.03 with fade-delta = 7 means ~233ms to fully fade in
Lower values = smoother but longer animations
Higher values = faster but choppier transitions

Fade Exclusions

# Uncomment to exclude windows from fading
# fade-exclude = []

Transparency and Opacity

Opacity Settings

active-opacity = 1.0;
inactive-opacity = 1.0;
frame-opacity = 0.7;
inactive-opacity-override = false;

Setting inactive-opacity < 1.0 makes all unfocused windows transparent, which can be distracting. Use per-application rules instead.

Application-Specific Opacity

opacity-rule = [
  "96:class_g = 'discord'",
  "90:class_g = 'Thunar'",
  "90:class_g = 'Spotify'",
  "90:class_g = 'Element'",
  "90:class_g = 'neothesia'",
  "84:class_g = 'kitty'",
  "84:class_g = 'Alacritty'",
];

Opacity Rule Syntax

"<opacity>:<condition>"

Examples:

# Set terminal to 85% opacity
"85:class_g = 'Alacritty'"

# Set Firefox to 95% opacity
"95:class_g = 'firefox'"

# Make floating windows slightly transparent
"95:window_type = 'normal' && !focused"

Finding Window Classes

Install xprop:

sudo pacman -S xorg-xprop  # Arch
sudo apt install x11-utils  # Debian/Ubuntu

Run xprop:

xprop | grep WM_CLASS

Click on the window you want to identify

Use the second value from WM_CLASS(STRING)

Focus Exclusions

focus-exclude = [ "class_g = 'Cairo-clock'" ];

Windows matching these rules are always considered focused.

Background Blur

Blur Configuration

blur-method = "dual_kawase"
blur-strength = 8
blur-background = true
blur-kern = "3x3box";

Blur Methods

dual_kawase - Fast and high-quality (recommended)
kawase - Similar to dual_kawase
gaussian - Traditional Gaussian blur
box - Simple box blur
kernel - Custom kernel blur
none - Disable blur

Blur Strength:

Range: 1-20
Lower = subtle blur
Higher = intense blur (more GPU intensive)

Blur Exclusions

blur-background-exclude = [
  "window_type = 'dock'",
  "window_type = 'desktop'",
  "_GTK_FRAME_EXTENTS@:c"
];

Excluding docks and desktop prevents blurring where it’s not needed, improving performance.

Window Type Rules

Window Type Configuration

wintypes:
{
  tooltip = { fade = true; shadow = true; opacity = 0.75; focus = true; full-shadow = false; };
  dock = { shadow = false; }
  dnd = { shadow = false; }
  popup_menu = { opacity = 0.8; }
  dropdown_menu = { opacity = 0.8; }
};

Available Window Types

Window Type Reference

Type	Description
`tooltip`	Tooltip windows
`dock`	Dock/panel windows (like Polybar)
`dnd`	Drag-and-drop windows
`popup_menu`	Popup menus
`dropdown_menu`	Dropdown menus
`menu`	Menu windows
`utility`	Utility windows
`toolbar`	Toolbar windows
`splash`	Splash screens
`dialog`	Dialog windows
`normal`	Normal windows
`notification`	Notification windows
`combo`	Combo boxes
`desktop`	Desktop windows

General Settings

Detection and Optimization

mark-wmwin-focused = true;
mark-ovredir-focused = true;
detect-rounded-corners = true;
detect-client-opacity = true;
detect-transient = true
detect-client-leader = true
use-damage = true
log-level = "warn";

Settings Explained

mark-wmwin-focused: Mark window-manager windows as focused
mark-ovredir-focused: Mark override-redirect windows as focused
detect-rounded-corners: Auto-detect rounded corners
detect-client-opacity: Detect client-side opacity
detect-transient: Detect transient windows
detect-client-leader: Group windows by leader
use-damage: Enable damage tracking (better performance)
log-level: Logging verbosity (debug, info, warn, error)

Performance Note:Setting use-damage = false can fix visual glitches but significantly impacts performance. Only disable if absolutely necessary.

Starting Picom

Launch from i3

Add to i3 config:

exec_always --no-startup-id picom --backend glx --xrender-sync-fence

Command Line Options

# Basic startup
picom

# With specific backend
picom --backend glx

# With config file
picom --config ~/.config/picom/picom.conf

# Enable/disable features
picom --no-fading
picom --no-shadows
picom --blur-method dual_kawase

# Debug mode
picom --log-level=debug

Advanced Configuration

Corner Radius

Picom doesn’t have built-in corner rounding. Use picom-jonaburg-git fork for this feature.

Animation Settings

For custom animations, consider using picom-animations fork:

yay -S picom-git  # picom-animations fork

Performance Tuning

Performance Optimization

For better performance:

# Disable blur on low-end systems
blur-background = false

# Reduce shadow quality
shadow-radius = 5;

# Faster fade
fade-in-step = 0.05;
fade-out-step = 0.05;

# Disable vsync if tearing isn't an issue
vsync = false

For better quality:

# Enhanced shadows
shadow-radius = 12;
shadow-opacity = 0.6;

# Stronger blur
blur-strength = 12

# Smoother fading
fade-in-step = 0.02;
fade-out-step = 0.02;
fade-delta = 5

Troubleshooting

Check if Picom is Running

ps aux | grep picom

Kill Existing Instance

killall picom

Test Configuration

picom --config ~/.config/picom/picom.conf

View Logs

picom --log-level=debug 2>&1 | tee picom.log

Common Issues

Screen Tearing

Solution:

vsync = true
backend = "glx"

If still experiencing tearing, try:

picom --backend glx --vsync

Performance Issues

Solutions:

Disable blur:

blur-background = false

Reduce shadow quality:

shadow-radius = 5;

Use xrender backend:

picom --backend xrender

Transparency Not Working

Check:

Verify opacity rules:

picom --show-all-xerrors

Test with specific window:

xprop | grep WM_CLASS

Ensure no conflicts with other compositors:

killall compton xcompmgr

Shadows Flickering

Solutions:

Disable shadow on problematic windows:

shadow-exclude = [
  "class_g = 'ProblematicApp'"
];

Adjust shadow settings:

shadow-radius = 10;
shadow-offset-x = -10;
shadow-offset-y = -10;

Integration with i3

Auto-start Configuration

In ~/.config/i3/config:

# Start picom with specific options
exec_always --no-startup-id picom --backend glx --xrender-sync-fence

# Alternative: use config file settings
exec_always --no-startup-id picom -b

Restart Picom

Add to i3 config for quick restart:

bindsym $mod+Shift+p exec --no-startup-id "killall picom; picom -b"

Additional Resources

Picom GitHub
Picom Wiki
Sample configs: /usr/share/doc/picom/picom.conf.example

Getting Started

Window Manager

Terminal Setup

Editors

Custom Commands

System Configuration

​Picom Compositor Setup

​Overview

​Basic Configuration

​Backend Settings

​Shadow Configuration

​Enable and Configure Shadows

​Shadow Parameters

​Shadow Exclusions

​Fading Effects

​Fade Configuration

​Fading Parameters

​Fade Exclusions

​Transparency and Opacity

​Opacity Settings

​Application-Specific Opacity

​Opacity Rule Syntax

​Finding Window Classes

​Focus Exclusions

​Background Blur

​Blur Configuration

​Blur Exclusions

​Window Type Rules

​Window Type Configuration

​Available Window Types

​General Settings

​Detection and Optimization

​Starting Picom

​Launch from i3

​Command Line Options

​Advanced Configuration

​Corner Radius

​Animation Settings

​Performance Tuning

​Troubleshooting

​Common Issues

​Integration with i3

​Auto-start Configuration

​Restart Picom

​Additional Resources

Build docs developers (and LLMs) love

Picom Compositor Setup

Overview

Basic Configuration

Backend Settings

Shadow Configuration

Enable and Configure Shadows

Shadow Parameters

Shadow Exclusions

Fading Effects

Fade Configuration

Fading Parameters

Fade Exclusions

Transparency and Opacity

Opacity Settings

Application-Specific Opacity

Opacity Rule Syntax

Finding Window Classes

Focus Exclusions

Background Blur

Blur Configuration

Blur Exclusions

Window Type Rules

Window Type Configuration

Available Window Types

General Settings

Detection and Optimization

Starting Picom

Launch from i3

Command Line Options

Advanced Configuration

Corner Radius

Animation Settings

Performance Tuning

Troubleshooting

Common Issues

Integration with i3

Auto-start Configuration

Restart Picom

Additional Resources