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

> Learn how PhotoGIMP uses CSS to customize GIMP 3's theme with its auto-generated theme.css. Easily style GIMP without changing code.

- Repository: [Diolinux/PhotoGIMP](https://github.com/Diolinux/PhotoGIMP)
- Tags: how-to-guide
- Published: 2026-05-20

---

**PhotoGIMP leverages GIMP 3's native CSS-based theme system by using an auto-generated [`theme.css`](https://github.com/Diolinux/PhotoGIMP/blob/main/theme.css) file that imports both the base dark theme and a user-editable [`gimp.css`](https://github.com/Diolinux/PhotoGIMP/blob/main/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`](https://github.com/Diolinux/PhotoGIMP/blob/main/theme.css)** located at [`.config/GIMP/3.0/theme.css`](https://github.com/Diolinux/PhotoGIMP/blob/main/.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`](https://github.com/Diolinux/PhotoGIMP/blob/main/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`](https://github.com/Diolinux/PhotoGIMP/blob/main/gimp.css)** file from the configuration directory

The generated [`theme.css`](https://github.com/Diolinux/PhotoGIMP/blob/main/theme.css) file contains CSS directives like:

```css
@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`](https://github.com/Diolinux/PhotoGIMP/blob/main/theme.css) is regenerated on every launch and whenever the user switches themes, any changes placed in [`gimp.css`](https://github.com/Diolinux/PhotoGIMP/blob/main/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`](https://github.com/Diolinux/PhotoGIMP/blob/main/gimp.css) file rather than modifying the auto-generated [`theme.css`](https://github.com/Diolinux/PhotoGIMP/blob/main/theme.css). Since [`theme.css`](https://github.com/Diolinux/PhotoGIMP/blob/main/theme.css) imports [`gimp.css`](https://github.com/Diolinux/PhotoGIMP/blob/main/gimp.css) after the base theme, your custom rules naturally override the defaults.

### Locating the Configuration Files

The [`gimp.css`](https://github.com/Diolinux/PhotoGIMP/blob/main/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:

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

```

For standard installations, the location is typically:

```text
~/.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`](https://github.com/Diolinux/PhotoGIMP/blob/main/.config/GIMP/3.0/theme.css).

### Creating Your First Custom Theme Rule

To customize the PhotoGIMP interface, add CSS selectors to [`gimp.css`](https://github.com/Diolinux/PhotoGIMP/blob/main/gimp.css) targeting specific GIMP widgets. For example, to change the toolbox background color, add:

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

```

Save the file and restart PhotoGIMP to see the changes. The generated [`theme.css`](https://github.com/Diolinux/PhotoGIMP/blob/main/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`](https://github.com/Diolinux/PhotoGIMP/blob/main/gimp.css) file.

**Override icon style for all buttons:**

```css
/* 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:**

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

```

**Modify menu spacing:**

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

```

Each of these rules is processed when [`.config/GIMP/3.0/theme.css`](https://github.com/Diolinux/PhotoGIMP/blob/main/.config/GIMP/3.0/theme.css) imports [`gimp.css`](https://github.com/Diolinux/PhotoGIMP/blob/main/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`](https://github.com/Diolinux/PhotoGIMP/blob/main/.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`](https://github.com/Diolinux/PhotoGIMP/blob/main/theme.css), the actual customization happens in the user's local [`gimp.css`](https://github.com/Diolinux/PhotoGIMP/blob/main/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`](https://github.com/Diolinux/PhotoGIMP/blob/main/theme.css)** file imports the base dark theme and the user-editable **[`gimp.css`](https://github.com/Diolinux/PhotoGIMP/blob/main/gimp.css)** file on every startup.
- Users customize PhotoGIMP by editing [`gimp.css`](https://github.com/Diolinux/PhotoGIMP/blob/main/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`](https://github.com/Diolinux/PhotoGIMP/blob/main/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`](https://github.com/Diolinux/PhotoGIMP/blob/main/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`](https://github.com/Diolinux/PhotoGIMP/blob/main/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`](https://github.com/Diolinux/PhotoGIMP/blob/main/gimp.css), restart the application. The [`theme.css`](https://github.com/Diolinux/PhotoGIMP/blob/main/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`](https://github.com/Diolinux/PhotoGIMP/blob/main/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`](https://github.com/Diolinux/PhotoGIMP/blob/main/theme.css) functions identically across all operating systems.