PhotoGIMP CSS Theme Customization: How to Style GIMP 3 with Custom Stylesheets

PhotoGIMP leverages GIMP 3's native CSS-based theme system by using an auto-generated theme.css file that imports both the base dark theme and a user-editable gimp.css stylesheet, enabling interface customization without code changes.

The Diolinux/PhotoGIMP project streamlines professional photo editing workflows in GIMP 3 by providing pre-configured settings and a standardized approach to CSS theme customization. Unlike applications with built-in theme engines, PhotoGIMP relies entirely on GIMP 3's declarative CSS framework, requiring users to understand the relationship between generated system files and custom stylesheets. This guide explains exactly how PhotoGIMP implements CSS theme customization and how you can modify the interface appearance using standard CSS rules based on the repository's configuration files.

Understanding PhotoGIMP's CSS Architecture

PhotoGIMP does not implement a proprietary theming engine. Instead, it utilizes GIMP 3's built-in CSS theme system through a specific file structure that separates system-generated styles from user customizations.

When PhotoGIMP launches, GIMP 3 automatically generates a runtime stylesheet called theme.css located at .config/GIMP/3.0/theme.css. This file serves as the entry point for all theme styling and performs two critical imports:

• Base Theme Import: Loads the default dark theme from gimp-dark.css located in the system themes directory (/app/share/gimp/3.0/themes/Default/)
• User Override Import: Loads the user-editable gimp.css file from the configuration directory

The generated theme.css file contains CSS directives like:

@import url("file:///app/share/gimp/3.0/themes/Default/gimp-dark.css");
@import url("file:///app/etc/gimp/3.0/gimp.css");

/* Force symbolic icons for all widgets */
* { -gtk-icon-style: symbolic; }

Because theme.css is regenerated on every launch and whenever the user switches themes, any changes placed in gimp.css are automatically incorporated on the next startup. This architecture ensures that PhotoGIMP preserves the standard GIMP workflow while providing a consistent baseline configuration.

Customizing PhotoGIMP Themes with CSS

Customizing the PhotoGIMP interface requires editing the user-specific gimp.css file rather than modifying the auto-generated theme.css. Since theme.css imports gimp.css after the base theme, your custom rules naturally override the defaults.

Locating the Configuration Files

The gimp.css file resides in the user's GIMP 3 configuration directory. For Flatpak installations of PhotoGIMP (the default distribution method), create or edit the file at:

~/.var/app/org.gimp.GIMP/config/GIMP/3.0/gimp.css

For standard installations, the location is typically:

~/.config/GIMP/3.0/gimp.css

If the file does not exist, create it with a standard text editor. GIMP automatically detects this file on startup and applies the contained CSS rules via the import chain established in .config/GIMP/3.0/theme.css.

Creating Your First Custom Theme Rule

To customize the PhotoGIMP interface, add CSS selectors to gimp.css targeting specific GIMP widgets. For example, to change the toolbox background color, add:

/* gimp.css – user customization */
#gimp-toolbox {
    background-color: #2e2e2e;
}

Save the file and restart PhotoGIMP to see the changes. The generated theme.css automatically imports your updated stylesheet, applying the new background color to the toolbox.

Practical CSS Customization Examples

Below are common PhotoGIMP CSS customizations you can add to your gimp.css file.

Override icon style for all buttons:

/* gimp.css */
button {
    -gtk-icon-style: requested;
}

This changes the icon display from symbolic (monochrome) to full-color icons.

Adjust image window title font size:

/* gimp.css */
.gimp-image-window .titlebar {
    font-size: 12pt;
}

Modify menu spacing:

/* gimp.css */
menuitem {
    padding: 6px;
}

Each of these rules is processed when .config/GIMP/3.0/theme.css imports gimp.css during PhotoGIMP initialization.

Key Files in the PhotoGIMP Repository

The PhotoGIMP repository (Diolinux/PhotoGIMP) includes specific files that demonstrate the expected CSS structure:

• .config/GIMP/3.0/theme.css: The reference stylesheet that establishes the import chain for the dark theme and user customizations. This file ships with PhotoGIMP to ensure consistent theme loading across different environments.

While the repository provides this baseline theme.css, the actual customization happens in the user's local gimp.css file, which PhotoGIMP does not ship but expects users to create according to their preferences.

Summary

• PhotoGIMP utilizes GIMP 3's native CSS theme system rather than implementing a custom theming engine.
• The auto-generated theme.css file imports the base dark theme and the user-editable gimp.css file on every startup.
• Users customize PhotoGIMP by editing gimp.css in their configuration directory (~/.var/app/org.gimp.GIMP/config/GIMP/3.0/ for Flatpak).
• Changes require a PhotoGIMP restart to take effect, as theme.css is regenerated and re-imports the custom stylesheet.
• CSS selectors target standard GIMP widgets like #gimp-toolbox, .gimp-image-window, and GTK elements such as button and menuitem.

Frequently Asked Questions

Where do I place custom CSS files for PhotoGIMP?

Place your custom CSS in the gimp.css file located at ~/.var/app/org.gimp.GIMP/config/GIMP/3.0/gimp.css for Flatpak installations, or ~/.config/GIMP/3.0/gimp.css for standard installations. Do not edit the auto-generated theme.css file directly, as it is overwritten on every launch.

Do I need to recompile PhotoGIMP to see CSS changes?

No. PhotoGIMP uses a declarative CSS system that requires only a restart. After saving changes to gimp.css, restart the application. The theme.css file is regenerated on startup and imports your updated stylesheet automatically, applying the new styles without any code compilation.

What CSS selectors are available for PhotoGIMP customization?

You can use standard GIMP 3 widget selectors including #gimp-toolbox for the toolbox, .gimp-image-window for image windows, and standard GTK selectors like button, menuitem, and .titlebar. These correspond to GTK CSS nodes used throughout the GIMP interface, allowing you to modify colors, spacing, fonts, and icon styles.

Can I use PhotoGIMP CSS customization on Windows or macOS?

Yes. PhotoGIMP's CSS customization works on any platform running GIMP 3, though the file paths differ. On Windows, the gimp.css file is typically located at %APPDATA%\GIMP\3.0\gimp.css, while macOS uses ~/Library/Application Support/GIMP/3.0/gimp.css. The import mechanism via theme.css functions identically across all operating systems.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}