GIMP plugin path resolution failure in headless production environments

Question

When GIMP 2.10 fails to load custom plugins during batch processing

GIMP relies on the search paths defined within the user-specific gimprc file, typically located in ~/.config/GIMP/2.10/. While these paths are correctly recognized in local desktop environments, batch jobs executed via gimp -i -b often fail to initialize these plugins when running on production containers or headless servers. This discrepancy often arises because production environments frequently lack the full configuration directory or have restricted permissions that prevent the discovery of non-standard paths. Even if the plugin binaries are present on the disk, GIMP may skip them if the configuration file is missing or improperly initialized, leading to silent failures or command-not errors in automated workflows.

Is there a method to force a global plugin search path via environment variables without requiring a user-level gimprc? How can GIMP verify which configuration directories are being scanned when started in non-interactive mode?

Tasadduq Burney · Answer

Forcing GIMP plugin search paths in headless containers
When GIMP starts without a user‑level gimprc it falls back to its built‑in plug‑in search list, so any paths you added manually are ignored.
Confirmed way to add a global plug‑in path

Set GIMP2_PLUGINDIR (or GIMP2_PLUGIN_PATH on some builds) to an absolute directory that contains your plug‑ins. GIMP appends this value to its internal search list.
If you can provide a writable configuration directory, set GIMP2_DIRECTORY to point at a folder that holds a gimprc file containing a plug-in-path entry. GIMP will read that file and honour the path.

Steps for the common case (no writable gimprc)

Determine the absolute path to the directory that holds your plug‑in binaries, e.g. /opt/gimp-plugins.
Export the variable before invoking GIMP:
export GIMP2_PLUGINDIR=/opt/gimp-plugins

Run GIMP in batch mode, for example:
gimp -i -b '(some‑script)' -b '(gimp-quit 0)'

How to verify which directories are scanned
Run GIMP with verbose mode and quit immediately:
gimp -v -i -b '(gimp-quit 0)' 2>&1 | grep -i "scanning for plug‑ins"

The output will list each directory GIMP examined, including the one you added via GIMP2_PLUGINDIR or the gimprc location.
To confirm a specific plug‑in is visible, query the procedure database:
gimp -i -b '(gimp-get-procedure-list "plug-in-myplug")' -b '(gimp-quit 0)'

If the procedure name appears, the plug‑in was loaded successfully.
If you can place a gimprc file inside the container, let me know so we can adjust the recommendation to use GIMP2_DIRECTORY instead of relying solely on GIMP2_PLUGINDIR.

GIMP plugin path resolution failure in headless production environments

When GIMP 2.10 fails to load custom plugins during batch processing

1 answer

Forcing GIMP plugin search paths in headless containers

Confirmed way to add a global plug‑in path

Steps for the common case (no writable gimprc)

How to verify which directories are scanned

Your perspective belongs here.

0 question comments