How to Add a GIMP Plugin to the Top Menu Bar

Registering a custom plugin to appear directly in GIMP's top-level menu bar requires writing a compatible script, configuring the registration call with the appropriate menu path, setting correct file permissions, and installing the file in GIMP's designated plug-ins directory. This guide outlines the exact steps needed to create and expose a Python plugin directly in the primary interface of GIMP.

1. Write the Plugin Function

Create a Python script (e.g., custom_menu_item.py) and import the required GIMP modules. Define the main function that will execute when the menu item is clicked.

#!/usr/bin/env python
from gimpfu import *

def my_custom_task(image, drawable):
    # Your processing code here
    gimp.message("Plugin executed successfully!")

2. Define the Top-Level Menu Path in the register Call

The key to placing an item on GIMP’s top-level menu bar lies in the menu parameter of the register() function.

Prepend the path with <Image>/ followed by the name of the top-level menu you want to create or append to:

register(
    "python_fu_custom_task",              # Internal procedure name
    "A short description of the plugin",  # Blurb
    "Detailed help information",          # Help
    "Your Name",                          # Author
    "Your Name",                          # Copyright
    "2024",                               # Year
    "Run Custom Task",                    # Label displayed in the menu
    "*",                                  # Image types supported (* for all)
    [
        (PF_IMAGE, "image", "Input image", None),
        (PF_DRAWABLE, "drawable", "Input drawable", None),
    ],
    [],
    my_custom_task,
    menu="<Image>/MyCustomMenu"            # Top-level menu path
)

main()

Using <Image>/MyCustomMenu instructs GIMP to create a new top-level menu named MyCustomMenu on the main window bar. If you prefer to place it under an existing top-level menu (such as Filters or Tools), set the path accordingly (e.g., <Image>/Filters/MySubMenu).

3. Make the Script Executable

GIMP requires plugin files to have executable permissions on Unix-based systems (Linux and macOS).

Open your terminal and run:

chmod +x custom_menu_item.py

(On Windows, ensure the script retains the .py extension.)

4. Install the Plugin in the Plug-ins Directory

GIMP looks for custom plugins in user-specific directory paths. In modern versions of GIMP (2.10 and later), each plugin should typically reside in its own folder with the same name as the script.

  1. Navigate to the GIMP plug-ins folder:
    • Linux: ~/.config/GIMP/2.10/plug-ins/
    • Windows: %APPDATA%\GIMP\2.10\plug-ins\
    • macOS: ~/Library/Application Support/GIMP/2.10/plug-ins/
  2. Create a folder named custom_menu_item.
  3. Move custom_menu_item.py into this folder.

5. Launch and Verify

Restart GIMP. Upon startup, GIMP queries the plug-in directory, registers the metadata, and adds MyCustomMenu to the primary menu bar alongside defaults like File, Edit, and Select. Clicking the menu item will execute your defined Python function.