In this article
You enable transparency in your terminal, yet the background stays opaque. A lightweight X11 desktop may be missing a compositor. Picom supplies this additional display layer: it combines windows into the final image and can apply transparency or shadows.
My Picom file in the X1 Gruvnode profile is deliberately small. This article explains its choices and a controlled test. It targets X11, for example XMonad; you do not need this setup for a Sway or Plasma Wayland session.
Separate the window manager from the compositor
XMonad decides where windows go and which receives focus. Picom then composes their X11 surfaces. They cooperate but remain separate processes. A complete desktop may already combine these responsibilities in its own window manager.
Only one compositor should own this task. Do not add Picom if KWin already handles composition in an X11 session. Under Wayland, the compositor is part of the session itself; Picom is not a general replacement for missing effects there.
Check the session type:
printenv XDG_SESSION_TYPE
A missing value does not establish that the session is X11. In that case, check what you selected at login. The concrete reference here is my X1 profile running XMonad on X11.
Read my profile line by line
The published file contains:
backend = "xrender";
vsync = true;
use-damage = true;
shadow = false;
fading = false;
inactive-opacity = 1.0;
active-opacity = 1.0;
frame-opacity = 1.0;
detect-client-opacity = true;
detect-rounded-corners = true;
Unlike Kitty, this syntax uses =, quoted strings and semicolons. xrender selects a rendering backend. Available backends and options depend on the installed Picom version.
Shadows and fade animations are disabled. Active windows, inactive windows and frames receive no extra global transparency factor, leaving Kitty in charge of its terminal opacity. use-damage considers changes reported by the X server instead of always treating unchanged areas as new content. The best combination for a particular GPU requires a real test.
Why Kitty can still be transparent
Kitty chooses its background rendering through background_opacity; Picom processes the resulting surface. Setting inactive-opacity = 0.8 in Picom would additionally affect whole inactive windows. That can change text and controls too, and is a different effect.
Start with my profile's absence of global window transparency. In the Kitty tutorial, compare terminal backgrounds at 1.0 and 0.8 independently. This helps you identify which component controls the appearance.
vsync = true requests a display behaviour; it is not a promise to eliminate all tearing. The backend, driver and version also matter. Record that combination when a problem persists rather than combine unrelated options from different Picom forks.
Test one process with a separate file
Check the version:
picom --version
Check for an existing Picom process:
pgrep -a picom
No output does not rule out another compositor. This exercise assumes an X11 session with no active compositor. If Picom already starts automatically, inspect that process's configuration instead of forcing a second instance.
Create an exercise directory:
mkdir -p ~/picom-tutorial
Save the file shown above as ~/picom-tutorial/picom.conf. Start Picom in the foreground:
picom --config ~/picom-tutorial/picom.conf
The terminal remains occupied and displays messages. From a second terminal, open a Kitty test window with reduced background opacity. To undo the experiment, press Ctrl + C in the first terminal to stop the Picom process you started. Your regular configuration file has not been replaced.
Try shadows as a single change
Stop the test process, change only shadow = false; to shadow = true; in the exercise file, then run the same command again. Compare the effect around an ordinary application window.
Some windows may eventually need exclusion rules, such as panels or special popups. Keep the first test small nevertheless. Changing shadows, rounding, blur and backend at once makes it harder to identify the cause of display problems.
Return the shadow setting to false and stop the process when finished. Add a session startup command only after testing. My Gruvnode profile starts Picom through the XMonad setup; avoid adding another invocation to several login files.
Identify common problems
| Problem | First check |
|---|---|
| Another compositor already owns the display | Identify the session's compositor |
| File is not being read | Check the explicit --config path and semicolons |
| Kitty remains opaque | Check Kitty's value, session type and rendering support |
| Black surfaces or flickering | Undo one change and record backend/version |
| Two instances after login | Inspect startup locations for duplicate commands |
Picom usually searches ~/.config/picom.conf, then ~/.config/picom/picom.conf, according to XDG directories. An explicit path removes this ambiguity in the exercise. Foreground messages are more useful during diagnosis than a process immediately sent into the background.
References and local data flows
The shown profile composes local window surfaces. It does not inspect online accounts or require a web service. Applications within windows can still be online, and screenshots may contain their private content.
- Checked Gruvnode Picom profile.
- Official Picom manual: backends, options and file search.
- Picom project: source and version-specific changes.
- Kitty transparency: terminal background and compositor requirements.
Sources checked on 8 October 2026. This article does not establish that any particular driver/GPU combination is universally free of rendering problems.